wrencode

wrencode is a minimal agentic coding assistant in a single Python file. A lightweight, hackable alternative to Claude Code: the whole tool-calling agent loop fits in one readable file, runs against local or hosted models, and is yours to hack.

Named after Harold Wren, the alias of a genius who built a superintelligent AI and operated quietly in the background.

wrencode on GitHub →

Install

Standalone binary (recommended)

The guided installer detects your OS and architecture, downloads the matching binary from the latest GitHub Release, and installs it to ~/.local/bin (no sudo).

curl -LsSf https://almostly.ai/wrencode/install.sh | sh

Pin a version or change the install location:

curl -fsSL https://almostly.ai/wrencode/install.sh \
  | WRENCODE_INSTALL_DIR=/usr/local/bin WRENCODE_VERSION=0.1.3 sh

Manual binary download

Grab the binary for your platform from the latest GitHub Release:

macOS Apple Silicon: wrencode-macos-arm64
macOS Intel: wrencode-macos-x64
Linux x64: wrencode-linux-x64

Make it executable and move it onto your PATH:

chmod +x wrencode-macos-arm64
sudo mv wrencode-macos-arm64 /usr/local/bin/wrencode

Run from source

Single file, standard library only (except the backend you choose).

git clone https://github.com/almostly/wrencode
cd wrencode
python3 wrencode.py

Backend-specific dependencies, if you need them:

pip install mlx-lm              # MLX on Apple Silicon
pip install transformers torch  # HuggingFace Transformers

Usage

First launch prompts for a backend and saves it to ~/.wrencode/config.json. Re-pick at any time:

wrencode --configure

Override the saved choice for a single session (useful in CI):

BACKEND=anthropic wrencode
BACKEND=openai MODEL=gpt-4o wrencode
BACKEND=openrouter MODEL=anthropic/claude-3-haiku wrencode
BACKEND=ollama MODEL=llama3.2 wrencode
BACKEND=transformers MODEL=deburky/gpt-oss-claude-code python3 wrencode.py
BACKEND=local LOCAL_PORT=8082 wrencode

For headless runs, skip the y/N confirmation on writes and shell commands:

wrencode --yes

Backends

Backend	Description	Availability
`anthropic`	Claude via the Anthropic API	binary + source
`openai`	GPT models via the OpenAI API	binary + source
`openrouter`	Any model via OpenRouter	binary + source
`ollama`	Local models via a running `ollama serve`	binary + source
`local`	Local proxy via an Anthropic-compatible API	binary + source
`transformers`	HuggingFace Transformers (CPU / MPS / GPU)	source install only
`mlx`	Apple Silicon via MLX	source install, macOS

The standalone binary can’t bundle the heavy ML stack, so mlx and transformers are only offered when running from source.

Default local models: deburky/gpt-oss-claude-code (transformers) and deburky/gpt-oss-claude-mlx (MLX). Override either with MODEL=....

Tools

The agent has seven tools available in the loop:

read: read a file with line numbers, or list a directory
write: write content to a file
edit: replace a unique string in a file
glob: find files by pattern, sorted by modification time
grep: search files for a regex using rg when available, falling back to grep
bash: run a shell command with timeout and streaming output
task: delegate a self-contained subtask to a fresh subagent (its own context, same tools) that returns only its final result

All file operations are sandboxed to the workspace root by default. Set WRENCODE_UNRESTRICTED_PATHS=1 to allow paths outside the workspace.

Subagents

The task tool runs a nested agent loop on a fresh message history, so the parent’s context only grows by the returned summary. Useful for context-heavy subtasks. Recursion is capped by WRENCODE_MAX_SUBAGENT_DEPTH (default 2). For autonomous runs, enable --yes or WRENCODE_AUTO_APPROVE=1 so sub-tool calls don’t block on confirmation.

Slash commands

Command	Description
`/help`	Show available commands
`/c`	Clear conversation history
`/compact`	Summarize history to reduce context (mlx only)
`/q` or `exit`	Quit

Environment variables

Variable	Default	Description
`BACKEND`	chooser / saved config	Override the saved inference backend
`MODEL`	backend-dependent	Model path or ID
`WRENCODE_CONFIG_DIR`	`~/.wrencode`	Dir for `config.json` (saved backend / key)
`WRENCODE_WORKSPACE`	cwd	Root directory for file operations
`WRENCODE_HISTORY_FILE`	`~/.wrencode/history.json`	Conversation history file path
`WRENCODE_UNRESTRICTED_PATHS`	`0`	Allow paths outside the workspace
`WRENCODE_AUTO_APPROVE`	`0`	Skip y/N confirmation for writes / shell (headless; also `--yes`)
`WRENCODE_MAX_SUBAGENT_DEPTH`	`2`	Max nested subagent recursion depth (`task` tool)
`MAX_TOKENS`	`4096`	Max tokens per response
`MAX_READ_BYTES`	`4MB`	Max file size to read
`MAX_READ_LINES`	`800`	Max lines returned per read
`GREP_MAX_MATCHES`	`80`	Max grep results
`BASH_TIMEOUT`	`120`	Shell command timeout in seconds
`MAX_TOOL_OUTPUT_CHARS`	`48000`	Max tool output before truncation
`GLOB_SKIP_DIRS`	`.git,node_modules,...`	Directories to skip in glob
`ANTHROPIC_API_KEY`		Anthropic API key
`OPENAI_API_KEY`		OpenAI API key
`OPENROUTER_API_KEY`		OpenRouter API key
`LOCAL_API_KEY`	`local`	Local proxy API key
`LOCAL_PORT`	`8082`	Local proxy port
`OLLAMA_HOST`	`http://localhost:11434`	Ollama server base URL

History

Conversation history is persisted to ~/.wrencode/history.json by default and restored on the next launch. Override the path with WRENCODE_HISTORY_FILE. Clear it with /c in-session, or delete the file.