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.
Beyond the core loop described below, Wells now ships:
/config settings and /mcp server manager.wells-index, Rust/tree-sitter, on PyPI) — instant symbol lookups plus a goal-ranked repo map injected into planner/coder prompts./undo reverts a run; per-node session checkpoints make /resume crash-proof; opt-in auto-commits./mode plan | approve | auto | dryrun, parallel read-only research fan-out, per-run token budgets, cheap-model routing for verification.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.
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.
Five stacked layers turn any decent LLM into a safe, efficient coding agent. Each is independent and swappable.
AGENTS.md knowledge that accumulates across runs; automatic branch/commit/PR via git + gh; parallel research & fix subagents the model can spawn.
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.
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.
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.
tiktoken estimator (auto-calibrated), per-call ledger, categorized context trimming, log compressor, rolling summarizer, model router, cache-friendly prompt prefixes. Runs under everything.
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.
Models that support OpenAI/Anthropic-style tool_calls (Z.ai GLM, GPT, Claude, Gemini…) bind the tool schemas directly. Fastest, most reliable path.
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.
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.
Eight tools cover the full edit-test-verify cycle. Reads are always allowed; writes and shell commands pass through the safety gate.
green = read-only, always allowed · orange = mutating, safety-gated · teal = delegation
HARNESS_SAFETY)| Mode | Behaviour |
|---|---|
auto | Execute immediately, confined to WORKSPACE_ROOT. Destructive commands (rm -rf /, mkfs…) are always blocked. |
approve | Require an approval callback. Degrades to dry-run when no callback is wired, so nothing destructive happens unattended. |
dryrun | Never 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.
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.
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.
Every call is tracked and trimmed. Here's a typical run's token budget visualized:
Approximate composition of tokens billed in a multi-step agent run.
tiktoken-based, auto-calibrated against real API responses. Per-step actuals (input/output/reasoning/cache_read) captured from usage_metadata.
Categorized chunks, stable-prefix ordering for prompt-cache hits, priority-based budget trimming when over budget.
Strips ANSI, collapses duplicates/blanks, keeps a tail window, preserves tracebacks. Tool outputs auto-compressed before going back to the model.
On loop iterations, verbatim plan/architecture is replaced with a summary once durable context exceeds SUMMARIZE_THRESHOLD.
Low-stakes tasks (summarization, compression, classification) route to MODEL_PROFILE_CHEAP when configured.
SystemMessage + deterministic chunk order maximizes provider-side prompt-cache hits — visible as cache_read savings in the report.
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.
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.
| Command | What it does |
|---|---|
wells | Launch 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 config | Interactive settings menu (all 22 settings, persists to .env) |
wells info | Show effective configuration |
wells "<goal>" MAX_ITERATIONS=5 | Inline 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).