Wells

A local, model-agnostic agentic coding harness. Give it a development goal and a crew of AI agents actually reads files, makes edits, runs tests, and ships a PR — Claude-Code style, driven by any model you choose.

★Current Capabilities (July 2026)

Beyond the core loop described below, Wells now ships:

1The Big Picture

One goal in, a verified code change out. Six reasoning stages run in a loop, with the middle three being autonomous tool-using agents that operate on your real workspace.

▶STARTgoal + workspace
→
📋Plannerbreaks down goal
→
🏗Architectdesigns approach
→
💻Coderedits + verifies
→
📝Testerruns test suite
→
🔍ReviewerCOMPLETE?
→
✅Finishermemory + PR
↺ if INCOMPLETE → summarizer condenses context → back to Coder (capped at MAX_ITERATIONS)
What makes this Claude-like: The Coder, Tester, and Reviewer don't just describe what they would do — they call real tools (read_file, edit_file, run_tests, …) in a model-driven loop, observe the results, and iterate until the work is genuinely done. The Reviewer independently re-checks by reading the changed files and re-running tests before signing off.

2Architecture in Layers

Five stacked layers turn any decent LLM into a safe, efficient coding agent. Each is independent and swappable.

L3

Advanced — Memory, Git, Subagents

AGENTS.md knowledge that accumulates across runs; automatic branch/commit/PR via git + gh; parallel research & fix subagents the model can spawn.

memory.py · gitops.py · subagents.py · finisher.py
L2

Agentic Executor — the tool-calling loop

The heart of it. A model-driven loop: model → tool calls → execute → observe → model, step-capped, with native tool-calling plus a text fallback so weaker models work too.

executor.py · agents/{planner,architect,coder,tester,reviewer}.py
L1

Tools & Safety — how the agent acts

Eight repo tools (read/list/glob/grep/write/edit/shell/tests) plus spawn_subagent. Every operation is workspace-confined and passes through an auto/approve/dryrun safety gate.

tools.py · safety.py
L0

Providers & Config — model-agnostic core

Named provider profiles (Z.ai, OpenAI, Anthropic, Ollama, OpenRouter…) selected by env vars. Lazy imports mean it runs out-of-the-box with just one provider package.

providers.py · config.py · settings.py (CLI menu)
∞

Token Optimization — the efficiency layer

tiktoken estimator (auto-calibrated), per-call ledger, categorized context trimming, log compressor, rolling summarizer, model router, cache-friendly prompt prefixes. Runs under everything.

tokens.py · context.py · compress.py · summarize.py

3Inside the Agentic Loop

This is where the agent actually works. Each of the Coder / Tester / Reviewer nodes spawns an executor that runs this loop with its own task and toolset.

🧠LLMdecides next action
→
🔧Tool Callread/edit/run/…
→
👁Observesee the result
→
🧠LLMnext step or done
↺ repeats until the model returns a final answer OR MAX_TOOL_STEPS is hit

Native tool-calling

Models that support OpenAI/Anthropic-style tool_calls (Z.ai GLM, GPT, Claude, Gemini…) bind the tool schemas directly. Fastest, most reliable path.

auto-detected

Text fallback

Models without native tool support emit <tool_call>{json}</tool_call> blocks in their text. The harness parses and dispatches them — so any decent AI can drive it.

universal compatibility

Subagent spawning

The model can call spawn_subagent to delegate a focused research (read-only) or fix task — keeping the parent's context lean. Runs in parallel via threads.

token-efficient parallelism

4The Tool Layer

Eight tools cover the full edit-test-verify cycle. Reads are always allowed; writes and shell commands pass through the safety gate.

read_file list_dir glob grep write_file edit_file run_command run_tests spawn_subagent

green = read-only, always allowed  ·  orange = mutating, safety-gated  ·  teal = delegation

Safety policy (HARNESS_SAFETY)

ModeBehaviour
autoExecute immediately, confined to WORKSPACE_ROOT. Destructive commands (rm -rf /, mkfs…) are always blocked.
approveRequire an approval callback. Degrades to dry-run when no callback is wired, so nothing destructive happens unattended.
dryrunNever execute — tools describe what they would do. Truly side-effect free.

PLAN_MODE=1 forces all mutating tools to simulate, so you can preview exactly what the agent would change before allowing it.

5Any Model, One Harness

Models are configured as named profiles. One is active (main reasoning), one optionally cheap (summarize/compress subtasks). Switch providers with a single env var — no code changes.

Z.ai GLM (default)
OpenAI
Anthropic Claude
OpenRouter
Ollama (local)
Together / Groq / Fireworks
DeepSeek / Mistral
Any vLLM / local endpoint
The built-in zai profile uses the coding endpoint /api/coding/paas/v4/ required by GLM-4.x/5.x. Legacy ZAI_* env vars still work and seed this profile. Explicit MODEL_zai / BASE_URL_zai / API_KEY_zai take precedence.

6Token Efficiency

Every call is tracked and trimmed. Here's a typical run's token budget visualized:

System
Durable context
Tool history
Output
Reasoning

Approximate composition of tokens billed in a multi-step agent run.

Estimator + Ledger

tiktoken-based, auto-calibrated against real API responses. Per-step actuals (input/output/reasoning/cache_read) captured from usage_metadata.

Context trimming

Categorized chunks, stable-prefix ordering for prompt-cache hits, priority-based budget trimming when over budget.

Log compressor

Strips ANSI, collapses duplicates/blanks, keeps a tail window, preserves tracebacks. Tool outputs auto-compressed before going back to the model.

Rolling summarizer

On loop iterations, verbatim plan/architecture is replaced with a summary once durable context exceeds SUMMARIZE_THRESHOLD.

Model router

Low-stakes tasks (summarization, compression, classification) route to MODEL_PROFILE_CHEAP when configured.

Cache-friendly prefix

SystemMessage + deterministic chunk order maximizes provider-side prompt-cache hits — visible as cache_read savings in the report.

7MCP Server — talk to it from anywhere

The harness runs as a Model Context Protocol server over stdio, so external agent clients (Claude Code, OpenCode, Codex CLIs, Gemini CLI…) can invoke it.

run_agent_task plan_task review_code run_executor spawn_subagent search_repo read_file run_command git_status get_memory compress_logs get_harness_info

Start it with wells-mcp or python -m wells. The MCP layer is deliberately thin — it delegates every call to the harness core, no duplicated logic.

8Command Line

CommandWhat it does
wellsLaunch the interactive chat REPL
wells "<goal>"Run the full harness on a goal (single-shot)
wells --plan "<goal>"Plan mode: plan edits without applying them
wells configInteractive settings menu (all 22 settings, persists to .env)
wells infoShow effective configuration
wells "<goal>" MAX_ITERATIONS=5Inline setting override

Running wells with no arguments opens a rich, interactive chat REPL (similar to Claude Code or OpenCode). It maintains conversational context across multiple goals and streams output tokens live to your terminal. Inside the REPL, you can type your goals naturally or use slash commands (/help, /config, /info, /plan, /quit).

Bottom line: Wells gives you a Claude-Code-class agent experience driven by whatever model you have access to — local or cloud, cheap or premium — with safety rails, token efficiency, and project memory that compounds over time.