Skip to main content

Wells — the tripod coding robot

Wells

CI wells-index on PyPI

Bring your own API key — Anthropic (Claude), OpenAI, Google (Gemini), Z.ai (GLM), OpenRouter, any OpenAI-compatible endpoint, or run entirely local (Ollama, vLLM). Your choice, switchable per task.

Wells is a model-agnostic agentic coding platform you run yourself: a full-screen terminal TUI plus an orchestration engine of autonomous tool-using agents (planner → architect → coder → tester → reviewer → finisher) that actually read files, make edits, run tests, and verify their own work — Claude Code / Codex CLI / OpenCode style, pointed at whichever provider you already have an API key for. Local models are a first-class option, not the point — they're just another provider profile, and nothing in Wells requires them. Ships with a Rust structural repo index (wells-index), an MCP server and MCP client, git-checkpointed undo, a deterministic verification layer, agent skills (load-on-demand know-how), CodeAct (sandboxed code execution), background agents (concurrent fan-out), and a browser tool (Playwright — navigate, click, type, read, screenshot a real JS-rendered session).

Get started in one command

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/corbybender/Wells/master/install-remote.sh | bash

Windows (PowerShell):

irm https://raw.githubusercontent.com/corbybender/Wells/master/install-remote.ps1 | iex

That's the whole install. The script installs uv if you don't have it (which manages Python for you — no Python pre-installed, no venv juggling), puts the wells command on your PATH, and drops you into first-run provider setup — pick Claude, OpenAI, Gemini, Z.ai, OpenRouter, or a local model, paste a key, done. Then:

cd your-project
wells

Re-running the installer updates an existing install.

Already have uv or pipx? Skip the script:

uv tool install wells-agent && wells config      # from PyPI
# or, tracking the repo:  uv tool install git+https://github.com/corbybender/Wells.git

Wells is published on PyPI as wells-agent (the bare name wells was taken by an unrelated package; the wells command is unchanged). That gives you versioned installs, uvx wells-agent for a no-install trial run, and a corporate-proxy-friendly path.

No Python at all? Every release also ships standalone binaries:

# https://github.com/corbybender/Wells/releases  -> wells-<version>-<platform>

Unzip, put the wells folder on your PATH, run wells config. These are self-contained (no Python, no uv, no venv) and start instantly.

Which install path fits you?

You want ... Use
It to just work (default) The one-liner above
Versioned installs / uvx trials / corporate proxies uv tool install wells-agent (PyPI)
No Python runtime at all, instant cold start Standalone binary from Releases
No global install — run Wells against one project from a clone Option A
To embed Wells inside another project's folder Option B
Every knob and prerequisite explained Quick start

Contents

How Wells compares

Wells sits in the same space as Aider, OpenHands (formerly OpenDevin), OpenCode, and Claude Code — an autonomous coding agent you run yourself, not an editor-embedded copilot. Continue.dev is a different category (an IDE extension) rather than a competing harness, so it isn't compared here. Cursor is the same category mismatch (a full IDE, not a CLI/TUI) — but its Agent/Composer mode is a real, comparable agent loop, so it gets a table below with that caveat up front rather than being excluded outright.

vs Aider

Aider Wells
Loop Single-pass edit → diff → commit Full graph: indexer → planner → [architect] → coder → tester → reviewer ↔ summarizer → finisher — plan, execute, test, and review are separate, checkpointed stages
Repo grounding Static ctags repo-map Planner agentically investigates (find_symbol/grep/read_file, plus parallel research fan-out) before writing a plan with exact files and line numbers
Test verification Model interprets test output Deterministic test-gate: the real suite's exit code is ground truth — a green suite skips the LLM interpretation pass entirely
Broken edits Caught on the next round-trip Self-heal runs ruff/node --check/JSON-parse after every write and feeds failures back the same round
Weak/local models Assumes a capable model Built for them: structured-output JSON-grammar fallback, Ollama context-window auto-detect + warmup, compact-prompt mode
Policy enforcement None built in Tiered rules engine (.wells/rules.yaml) + liabilities tracking + hooks.yaml — deterministic, not just prompted
Recovery Re-run from scratch Per-node session checkpoints (/resume), pre-run git snapshot (/undo), full run trace + replay
Parallel edits Sequential Background git-worktree fan-out — multiple sub-agents edit concurrently in isolated checkouts, cherry-picked back on collect

vs OpenHands

OpenHands Wells
Footprint Docker sandbox + web UI CLI/TUI — one Python env, no container required
Operational visibility Browser-based event stream Textual TUI dashboard in one pane: live token/cost ledger, pipeline-stage breadcrumb with the active step highlighted, pinned-file context, MCP server manager, index stats, git branch, open liabilities
Providers Typically one model per session Named provider profiles (zai/openai/anthropic/gemini/ollama/openrouter/local/...), with automatic cheap-task and vision-task routing per call
Interop Its own agent, standalone MCP server (drive Wells from Claude Code/OpenCode/other CLIs) and MCP client (give Wells external tool servers)
Domain know-how Baked into the base prompt Skills: progressive-disclosure SKILL.md files — name + one-line description always visible, full body loads only when relevant
Deterministic computation Reasons it out CodeAct: sandboxed run_code tool for exact arithmetic/regex/counts instead of eyeballed answers
Subagent identities One generic agent persona Custom PERSONA.md specialists (system prompt + toolset), invoked per-call via bg_start(persona=...) — a security reviewer and a performance investigator get different framing, not the same generic prompt
Unattended operation Needs a live session wells schedule registers a goal with the OS's own scheduler (Task Scheduler/cron) — no Wells process has to be running for it to fire
Cross-project memory Session-scoped ~/.wells/memory/ — standing preferences that follow you to every project, distinct from per-repo AGENTS.md

vs OpenCode

The closest peer of the four — also a provider-agnostic TUI harness with subagents, custom commands, MCP, and a permission system. Credit where due: several Wells features exist because OpenCode (and Claude Code, next) already proved the pattern — this is a comparison between two harnesses built on overlapping ideas, not a one-sided list.

OpenCode Wells
Test verification Model-driven (runs tests via its own tool calls, no ground-truth gate) Deterministic test-gate: the real suite's exit code is ground truth — a green suite skips the LLM interpretation pass entirely, and post-edit self-heal (fast: ruff/node --check/JSON-parse; optional semantic: pyright/tsc/cargo check/go vet) catches broken syntax and type errors the same round
Code Mode Experimental execute tool (MCP tools as JS functions) program tool: Python, all harness tools callable — and every inner call passes the safety gate/deny-lists inside the program
Sandboxing Permission gating (allow/deny/ask); no container/VM isolation found sandbox mode: disposable Podman/Docker container; with WELLS_SANDBOX_AUTO=1 the default auto policy upgrades itself whenever a runtime is available
Skill portability Reads .claude/skills + .agents/skills Reads .claude/.agents/.codex skill dirs (workspace + user-global) — packs written for Claude Code/Codex/Kimi work unmodified
Editor integration Desktop app / IDE integrations ACP server (wells-acp) — any ACP client (Zed, JetBrains) drives Wells; plus the MCP server mode below
MCP Client only (connects out to MCP servers) Server (drive Wells from Claude Code/OpenCode/other CLIs) and client
Durable project memory Session-scoped BigBrain transaction-log memory: every finished run appends lessons/invariants to a locked log, deterministically compiled into curated memory, recallable via the memory_search tool
Unattended operation Not found wells schedule — Task Scheduler/cron, no live process required, with completion notifications (desktop/webhook) and a cross-run daily spend cap
Code intelligence Live LSP servers per language (accurate, but a process to start/maintain per language) Precomputed Rust structural index (wells-index) — find_symbol/find_references/find_callers in one lookup, ~98% fewer tokens than a live search; a different tradeoff (speed + low overhead vs. a language server's live accuracy), not a strict upgrade
Parallel work Subagents (blocking) Both blocking (parallel_research) and non-blocking (bg_start/bg_status/bg_collect) fan-out, plus fleet — N full parallel worktree attempts at the same task, pick the winner

vs Claude Code

The actual named target for this project, and the one Wells borrows the most acknowledged patterns from: subagent personas, custom slash commands, hooks, a model-driven todo list, and cross-project memory all exist in Wells because Claude Code proved they work well. Where Wells tries to go further:

Claude Code Wells
Provider Anthropic's Claude only Any of them — Claude, OpenAI, Gemini, Z.ai, OpenRouter, any OpenAI-compatible endpoint, or fully local (Ollama/vLLM), switchable per task, not a one-time choice
Test verification Model decides whether/when to run tests via its own Bash calls Deterministic test-gate + automatic post-edit self-heal — enforced by the harness, not left to model judgment
Sandboxing Bash tool runs on the host directly (as far as the CLI itself exposes) sandbox mode: disposable Podman/Docker container per run — opt-in, or auto-upgrade from auto with WELLS_SANDBOX_AUTO=1
Editor integration First-party VS Code/JetBrains extensions ACP server (wells-acp) — any ACP-capable editor (Zed, JetBrains, custom clients) drives the full pipeline over stdio
Long-term project memory Auto-memory notes BigBrain transaction log — locked append + deterministic compile into curated memory; planner recallable via memory_search; Reflexion failure critiques mirrored in automatically
Unattended operation Cloud-hosted scheduled routines (Anthropic's infrastructure, needs an account/plan tier) wells schedule — your own machine's Task Scheduler/cron, no cloud dependency; completion notifications + a cross-run daily spend cap guard against a stuck/runaway recurring goal
Parallel fan-out Task-tool subagent delegation (blocking) Blocking and non-blocking (bg_start), plus fleet — N parallel worktree attempts, pick the winner, merge or discard
Code intelligence Grep/Glob live search each time Precomputed structural index (wells-index) — exact file:line answers, ~98% fewer tokens per lookup
Cost visibility Point-in-time (/cost) Live, continuously-updating token/dollar ledger in the status panel throughout the run
Permission allowlists ✓ (settings.json allow/ask/deny) ✓ (.wells/rules.yaml severity: allow) — built to reach parity with this, not a Wells-only feature
Custom subagents / slash commands / hooks / todo list / auto-memory ✓ (the originals) ✓ (deliberately mirrored — PERSONA.md, .wells/commands/, hooks.yaml, update_todos, ~/.wells/memory/)

vs Cursor

Cursor is a full IDE (a VS Code fork), not a CLI/TUI — genuinely a different product category, the same mismatch as Continue.dev. It gets a table anyway because its Agent/Composer mode is a real, comparable agent loop (runs terminal commands, edits multiple files, has its own rules and MCP support) — just wrapped in a GUI editor instead of a terminal.

Cursor (Agent mode) Wells
Interface Full Electron-based IDE — a GUI is required Terminal TUI or headless CLI (wells -p --output-format json) — scriptable, runs over SSH, no GUI needed
Providers (BYOK) OpenAI, Anthropic, Google, Azure, AWS Bedrock All of those, plus Z.ai, OpenRouter, any OpenAI-compatible endpoint, and fully local (Ollama/vLLM)
Background/parallel agents Cloud Agents — isolated VMs in Cursor's own cloud infrastructure bg_start/fleet — your own local git worktrees, on your own disk, nothing leaves your machine unless you choose a hosted provider for the model call itself
Persistent instructions .cursor/rules — static context injected at the start of every prompt Both static (AGENT.md/AGENTS.md/RULES.md, prompt-injected) and a stateful liability ledger + tool-boundary enforcement that runs before a call, not just prompted
Test verification Not found as a distinct ground-truth gate Deterministic test-gate + automatic post-edit self-heal
MCP Client only (confirmed); no evidence of an MCP server mode Server and client

vs the 2026 first-party harnesses (Codex, Kimi Code, Grok Build, DeepSeek Harness)

The field has since filled with vendor-built harnesses — OpenAI's Codex, Moonshot's Kimi Code, xAI's Grok Build, and DeepSeek's DSH. They're converging on a shared template (single agent loop + AGENTS.md/SKILL.md/MCP portability + wide subagent fan-out) and competing on models and scale. Wells differ on architecture, not just polish:

The 2026 template Wells
Agent structure One agentic loop; agents = prompts + permission sets Staged graph — planner/architect/coder/tester/reviewer as checkpointed nodes with deterministic routing (failing tests loop to the coder; simple+green skips review entirely)
Ground truth Model judges its own work (or a classifier approves) Deterministic test gate — the suite's exit code routes the graph; post-edit self-heal fixes syntax/type errors the same round
Tool latency One tool call = one model round trip Code Mode — one program call composes N tool calls, safety-gated inside the program
Self-improvement Config/memory tuning by hand SEACS evolution — mine git history into an oracle-scored corpus, benchmark, and evolve the harness's own principles file with Wilson-bound gating
Long-term memory Flat memory files / session logs BigBrain transaction-log memory — locked appends, deterministic compile, keyword recall, Reflexion mirroring
Unattended operation Cloud schedulers / dashboards wells schedule on the OS's own scheduler + cross-run spend cap; fleet runs N parallel best-of-N attempts locally
Lock-in Each vendor's model ecosystem Model-agnostic by design — 12+ provider profiles incl. fully local, switchable per task

Credit where due: they win on scale (Grok Build's 128–1,024-agent workflows, DSH's plugin ecosystem and community), polish, and first-party model tuning. Wells is the harness for people who want determinism, verification, and self-improvement in one self-hosted package.

What it does

START → indexer → planner ──(simple plan)──────────┐
                     │ (complex)                    ▼
                  architect ─────────────────────► coder → tester ──(tests FAIL)──┐
                                                     ▲         │ (pass/unknown)   │
                                                     │         ▼                  │
                                                summarizer ◄─ reviewer ◄──────────┘
                                                     ▲         │(INCOMPLETE)
                                                     └─────────┘
                                                               │(COMPLETE / cap)
                                                    finisher (memory + git/PR) → END
  • Indexer builds/refreshes the structural repo index (symbols, references, call graph) before anything else runs.
  • Planner is agentic: it investigates the codebase with read-only tools (index-first lookups, plus a parallel_research fan-out that runs 2–4 read-only subagents concurrently), then writes a concrete plan with exact files and line numbers — and labels it SIMPLE or COMPLEX.
  • Architect validates complex plans; simple plans skip straight to the coder (one less LLM call).
  • Coder drives the agentic executor: reads, edits, creates files, and runs verification inside your workspace. Edits are whitespace-tolerant (an indentation slip in the model's match string no longer wastes a round-trip) and every applied change shows a colorized diff live. After each write, the harness itself runs the fastest checker for the file type (ruff/py_compile, node --check, JSON parse) and injects failures into the model's next observation — broken code is caught in milliseconds, not a tester round-trip later. Opt in to a slower, project-aware semantic pass (WELLS_SEMANTIC_CHECK=1) that runs a real type-checker — pyright/mypy, tsc, cargo check, go vet — for the file's language and catches type errors and bad cross-file references the fast pass can't see.
  • Tester runs a deterministic gate first: if the repo has a recognizable test setup, the harness executes the suite and records the exit code as ground truth. Green suite → the LLM interpretation pass is skipped entirely. Red suite → routes straight back to the coder (reviewer skipped) with the failure report as feedback.
  • Reviewer independently verifies the work (reads changed files, re-runs tests) and emits COMPLETE / INCOMPLETE. Tester + reviewer route to the cheap model profile when one is configured (CHEAP_VERIFY).
  • Summarizer condenses durable context on loop iterations (bounded by MAX_ITERATIONS).
  • Finisher writes a lesson to AGENTS.md project memory and optionally creates a wells/<slug> branch + commit + PR.

The session is checkpointed after every node, so a crash loses at most one node's work and /resume continues from the last state. Every run also snapshots your working tree first — /undo reverts everything a run changed.

The TUI

Running wells with no arguments opens the full-screen TUI: scrollable output log, multi-line prompt (Shift+Enter for newlines, ↑/↓ history, persisted across sessions), and an always-on status bar showing workspace, model, live token count and dollar cost, operating mode, pinned-file count, and — while running — the current agent activity (coder-1 · step 12/60, current tool). Escape cancels a running task cooperatively at the next step boundary. Answers stream token-by-token. F2 hides the panel (full-width select/copy); F4 stages a clipboard screenshot as an image attachment (see below — Ctrl+V can't do this: terminals intercept it as their own paste keybinding and swallow it when the clipboard holds an image instead of text).

The right-hand panel always shows one of two states, never blank: a plain ○ chat line when idle, or — the moment anything routes through the planning graph — the full indexer → planner → architect → coder → tester → reviewer → summarizer → finisher step list, with the in-flight step highlighted (▶ yellow + elapsed time), completed steps checked off (✓ green), and failures marked (✗ red). A third, independent section renders the model's own live task breakdown (the update_todos tool — see Agent capabilities) whenever it declares one: each item shown pending (dim), in-progress (▶ yellow, at most one at a time), or completed (struck through) — complementary to the pipeline breadcrumb, which shows structural graph position, not what the model actually decided to do inside a step.

Command What it does
/mode plan|approve|auto|dryrun|sandbox Switch operating mode (read-only / confirm each change / full autonomy / simulate / containerized shell) — or pick it visually via the /config choice picker
/add <path> / /drop <path> / /context Pin files into every prompt (guaranteed context, token-trimmed)
/image <path> / clear Attach an image file to the next task (screenshot of a bug, a design mock, a diagram)
/paste-image (or F4) Grab an image from the system clipboard and attach it to the next task
/undo Revert everything the last run changed (automatic pre-run git checkpoint)
/config Modal settings panel — all settings grouped, edit in place, saves to .env. Choice-constrained settings (HARNESS_SAFETY, PLAN_MODE, ...) open an arrow+Enter picker instead of typing — no way to mistype a value
/mcp Modal MCP server manager — add / enable / disable / test / remove servers
/rules Operating rules + open liabilities (list / reload / discharge <id> / add / remove <id>)
/skills Modal skills manager — list / view / add / edit / remove SKILL.md know-how; proposals reviews auto-authored skills
/agents Modal subagent-persona manager — list / view / add / edit / remove PERSONA.md custom specialist identities
/memory Modal global-memory manager — list / view / add / edit / remove standing preferences (~/.wells/memory/, every project)
/reflections List / clear captured failure critiques (.wells/reflections.md)
/schedule Register/list/remove unattended recurring runs (Task Scheduler / cron)
/orchestrate Route the next message through the full planning graph
/resume / /sessions Continue a previous session / browse history
/index Build or refresh the structural repo index
/doctor Diagnose the environment (model ping + latency, API key, TLS, index health, git, checkers)
/export [path] Save the session transcript to a file
/status /info /help /clear /quit Status panel, effective config, command list, clear history, exit

Under approve mode, destructive tool calls (writes, shell commands, MCP calls) pause the run and ask y/N in the TUI. AUTO_COMMIT=1 (opt-in) commits each successful run with an LLM-generated Conventional Commits message and a Wells authorship trailer.

Images staged with /image, /paste-image, or F4 are sent to whatever model is active — but if it isn't vision-capable (most coding-tuned models aren't), the harness automatically routes just that one call to MODEL_PROFILE_VISION instead (see Provider profiles) and reverts to normal routing on the very next call. No manual switching back and forth. The browser_screenshot tool (see Browser) uses the same MODEL_PROFILE_VISION routing independently, to describe a page back to the agent in text.

Provider profiles (model-agnostic)

Models are configured as named profiles. Any number can coexist; one is active, one optionally cheap (used for summarization/classification and, with CHEAP_VERIFY, the tester/reviewer).

Profile name Provider kind Notes
zai (default) openai (OpenAI-compatible) Z.ai GLM via the coding endpoint /api/coding/paas/v4/. Backward-compatible with legacy ZAI_* vars.
openai openai OpenAI directly
openrouter openai OpenRouter (hundreds of models, incl. several free-tier :free vision models — good fit for MODEL_PROFILE_VISION); auto-detects OPENROUTER_API_KEY
anthropic anthropic Requires pip install langchain-anthropic
ollama ollama Local models; requires pip install langchain-ollama
local openai Any local vLLM / Ollama OpenAI shim
together / groq / fireworks / deepseek / mistral openai One-line setup
google / gemini google Google Gemini. Requires pip install langchain-google-genai
bedrock / azure provider-specific Optional provider packages

A profile is configured with three env vars:

MODEL_<name>=<model-id>            # required
API_KEY_<name>=<key>               # if the provider needs one
BASE_URL_<name>=<url>              # for OpenAI-compatible endpoints

API_KEY_<name> also falls back to that provider's own standard env var (OPENROUTER_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, GEMINI_API_KEY, GROQ_API_KEY, TOGETHER_API_KEY, FIREWORKS_API_KEY, MISTRAL_API_KEY, DEEPSEEK_API_KEY) for a profile named after that provider — so a key you already have set from another tool works immediately, no duplicate API_KEY_<name> needed.

Select which profiles exist and which is active:

MODEL_PROFILES=zai,openrouter,local
MODEL_PROFILE=openrouter           # the active profile
MODEL_PROFILE_CHEAP=zai            # optional: cheaper model for subtasks
MODEL_PROFILE_VISION=openrouter    # optional: routed to for image-attached
                                    # tasks when the active profile isn't
                                    # vision-capable (e.g. a free OpenRouter
                                    # vision model alongside a non-vision main)

Manage every profile from /config (full CRUD, no manual .env editing required):

  • p — switch the active profile, or edit an existing one's model/key/URL
  • + — add a brand-new profile from scratch
  • - — remove a profile from MODEL_PROFILES; if it was the active/cheap/ vision slot, that slot is cleared (cheap/vision) or reassigned (active) automatically
  • v — dedicated vision-profile flow: point MODEL_PROFILE_VISION at an existing profile, create a new one on the spot (suggests a free OpenRouter vision model when the name is openrouter), or clear it back to "same as active"

Typing an env var name directly (e.g. MODEL_PROFILE_CHEAP) still works too.

Optional provider packages are imported lazily — the harness runs out-of-the-box with only langchain-openai (the OpenAI-compatible path covers Z.ai, OpenAI, OpenRouter, Together, Groq, Fireworks, local vLLM, Ollama's OpenAI shim, …).

Dollar costs are estimated from a built-in rate table (GLM / GPT / Claude / DeepSeek / local); pin exact rates per profile with MODEL_PRICE_<profile>=<in>,<out> ($/1M tokens).

Quick start

Requires uv and Python ≥ 3.12.

Option A — Cloned standalone (no install needed)

After git clone, run the one-time setup script for your OS. It puts the wells command on your PATH — no package build, no PyPI, works the same on Mac, Linux, and Windows:

git clone https://github.com/corbybender/Wells.git
cd Wells

./install.sh             # Mac/Linux — or install.ps1 on Windows (PowerShell)
# open a new terminal, then:

wells config              # first run: set up your provider
wells info                 # show effective configuration
wells                      # open the TUI
wells "your goal"          # run the harness single-shot on THIS repo

wells itself still handles the venv/deps automatically on every run — the installer only wires up the command name. You can also skip the installer and call the launcher directly: ./wells (Mac/Linux) or wells.bat (Windows).

Option B — Drive a DIFFERENT project (embedding)

Wells can operate on any project, not just itself. Clone it anywhere, then point it at your project with --workspace:

# From your project root, with Wells cloned as a subfolder:
./Wells/wells --workspace . "add JWT auth to the Express app"

# Or an absolute path:
./Wells/wells --workspace /home/me/myapp "fix the failing tests"

# Preview only (plan mode — describe edits without applying):
./Wells/wells --workspace . --plan "refactor the data layer"

All file operations, shell commands, and tests run inside the --workspace directory; Wells' own source is never touched.

Option C — Global install (available everywhere)

Install once, directly from GitHub (not published to PyPI — only the wells-index native indexer is; pip install wells won't find this package), then wells is on your PATH from any directory:

uv tool install git+https://github.com/corbybender/Wells.git
# or: pipx install git+https://github.com/corbybender/Wells.git
# or, from a local clone: uv tool install . / pipx install .

wells "your goal"                        # from any directory
wells --workspace /path/to/project "goal"

Note: During installation, uv may show a warning about hardlinks across filesystems (WARN: Hardlink or symlink copy required…). It's harmless; suppress it with UV_LINK_MODE=copy.

Manual setup (any option)

cp .env.example .env             # then edit .env with your API key
# or run the interactive menu:
./wells config

CLI

Both wells and wells work identically (they're the same entry point).

wells                                     # launch the TUI
wells "<goal>"                            # run the full harness (single-shot)
wells --workspace /path "fix the bug"     # run against another project
wells --safety dryrun "goal"              # force dry-run (preview only)
wells --safety sandbox "goal"             # shell commands run in a disposable container
wells --plan "<goal>"                     # plan mode: plan edits, don't apply
wells config                              # interactive settings menu (terminal)
wells info                                # show effective configuration
wells principles                          # show active operating principles (AGENT.md)
wells --version                           # show version
wells "<goal>" MAX_ITERATIONS=5           # inline setting override

In the TUI, /config opens the modal settings panel instead (same schema, same .env persistence).

Scheduled runs

Register a goal to run unattended, on a recurring interval, via the OS's native scheduler — Task Scheduler on Windows, cron on Linux/macOS. Wells doesn't need to be running for a scheduled run to fire; the scheduler invokes wells directly.

wells schedule add nightly-lint every1h "run the linter and fix any issues"
wells schedule list
wells schedule remove nightly-lint

Or from inside the TUI/REPL: /schedule add (opens a form), /schedule list, /schedule remove <name>. Interval spec: every<N>m / every<N>h (e.g. every15m, every2h), daily@HH:MM, or a raw 5-field cron expression (Linux/macOS only — Windows Task Scheduler has no cron-expression concept, so it's rejected there rather than mistranslated). Schedules are tracked in ~/.wells/schedules.json (so wells schedule list works even if the OS-side entry was later removed by hand) and mirrored into the real scheduler — verified live against Windows Task Scheduler: registration, schtasks /query showing the correct recurrence, removal, and confirmed-gone via a second query.

Each schedule gets a small wrapper script (~/.wells/schedule-scripts/) instead of trying to embed the goal directly in a Task Scheduler/cron command line — a goal can contain spaces, quotes, and newlines, and getting nested command-line quoting right (especially on Windows) is fragile. A PowerShell here-string / bash heredoc, written directly by Python and never re-parsed through a shell, sidesteps that whole class of bug.

Notifications & daily spend cap

Two gaps a scheduled/unattended run opens up: no way to know it finished without checking logs by hand, and no ceiling on how much a stuck or runaway recurring goal can spend across a day.

Run-completion notifications (WELLS_NOTIFY=1) fire on every run — headless or TUI — once it finishes:

  • Desktop popup via each OS's own native mechanism: a balloon tip (System.Windows.Forms.NotifyIcon) on Windows, osascript on macOS, notify-send on Linux. No extra package on any platform.
  • Webhook — WELLS_NOTIFY_WEBHOOK_URL gets a POST of {"text": ..., "event": ..., "detail": ...}. That's exactly the shape Slack's Incoming Webhooks expect, so pointing it at a Slack webhook URL works with zero Slack-specific code; any other JSON-accepting endpoint works too.

Both channels are best-effort — a notification failure never affects the run's own reported outcome.

Daily spend cap (WELLS_DAILY_BUDGET, dollars) tracks cumulative spend across every run in ~/.wells/spend.json (global, resets at midnight local time) and refuses to start a new run once the day's budget is reached — headless exits 1 with a clear error, the TUI prints the same message and doesn't launch. This is a different guarantee from MAX_RUN_TOKENS (which caps one run's tokens): the daily cap stops the next run in a recurring schedule from starting once the day's money is spent. Unset or 0 (the default) means no cap.

export WELLS_NOTIFY=1
export WELLS_NOTIFY_WEBHOOK_URL=https://hooks.slack.com/services/...
export WELLS_DAILY_BUDGET=5.00

Or set any of the three from /config (category: Notifications).

Safety model

The agent operates inside a workspace root (path escapes blocked) and a safety policy for writes, shell commands, and MCP tool calls:

Mode (/mode or HARNESS_SAFETY) Behaviour
auto (default) Execute immediately, confined to WORKSPACE_ROOT. Destructive commands (rm -rf /, mkfs, …) are always blocked.
approve Every destructive action pauses the run and asks y/N in the TUI.
dryrun Never execute — describe what would happen. Truly side-effect free.
plan (PLAN_MODE=1) All mutating tools simulate; reads still work. Preview exactly what would change.
sandbox Same full autonomy as auto — but shell commands (run_command) and CodeAct's run_code execute inside a disposable container instead of directly on your machine. Requires Podman (recommended, lightweight) or Docker; picked explicitly, per run.

sandbox is opt-in and additive: every other mode behaves exactly as before, so day-to-day use never launches a container runtime. Reach for it when you don't fully trust a repo, want an unattended auto run walled off, or are testing something you'd rather not risk on the host. File reads/writes/edits are unaffected in every mode — the workspace is bind-mounted into the container, so both sides see identical bytes; Wells' own workspace confinement already keeps those inside WORKSPACE_ROOT regardless of mode. One container is launched per workspace (lazily, on the first sandboxed command) and reused for the rest of the session; WELLS_SANDBOX_IMAGE overrides the default python:3.12-slim image. Pick the mode with the new /config choice picker (arrow keys + Enter) or /mode sandbox.

Auto-upgrade to sandbox (Codex-style sandbox-by-default, staged): with WELLS_SANDBOX_AUTO=1, the auto policy upgrades itself to sandbox whenever a container runtime is installed and its daemon answers — a cached reachability probe, checked once per process, with silent fallback to auto when no runtime is reachable. Explicit modes (dryrun, approve, sandbox) are never overridden. Opt-in today; enabling it as the shipped default is planned once the sandbox has soaked in real unattended runs.

Two extra safety nets regardless of mode: every run snapshots the working tree (including untracked files) to a hidden git commit before starting — /undo restores it — and MAX_RUN_TOKENS hard-caps a run's spend.

Operating rules — deterministic, not hopeful

Prompted rules are probabilistic: every model eventually forgets a wall of rules at prompt top. Wells enforces rules in tiers, strongest first:

  1. Tool-boundary enforcement (.wells/rules.yaml, merged over ~/.wells/rules.yaml): every tool call is checked before execution. block refuses outright, confirm pauses for y/N, warn injects the rule into the model's next observation, allow pre-clears approve mode's normal per-action y/N for a matching call (a permission allowlist — "always allow git status, always ask before rm" instead of a blanket prompt for every mutating call; auto/dryrun/plan/sandbox are unaffected either way), and liability registers a stateful obligation — e.g. a rented GPU was started and must be terminated. A run cannot silently end with an open liability: Wells attempts an automatic discharge pass, marks the run INCOMPLETE otherwise, shows a red ⚠ LIABILITY badge in the status bar, warns on next startup, and keeps the ledger in ~/.wells/liabilities.json so even a crash can't lose track of a running paid resource.
  2. Moment-of-relevance injection: when a rule fires, its text lands in the exact tool observation the model reads next — one rule, at the moment it applies — plus open liabilities pinned into the never-pruned working memory.
  3. Prompt + audit: the workspace RULES.md (universal, incident-derived rules) is injected into every system prompt, and the reviewer audits compliance — violations force the INCOMPLETE loop.

Manage with /rules (list, reload after editing, discharge <id> to acknowledge a manually-closed resource, add/remove <id> for simple pattern-triggered rules — liability rules, with their open/close regex pairs, stay hand-edited). /rules add (or the TUI form) writes a new rule by appending to .wells/rules.yaml — never a full parse+rewrite — so an existing hand-edited file keeps every comment exactly as written; remove does need a full rewrite and won't preserve comments. Default rules ship globally on first run: GPU-rental teardown tracking, force-push/hard-reset confirmation, bulk-rsync confirmation, auth-preflight and monitor-quality warnings, and one allow rule (git status/diff/log/show/branch never need confirmation, even in approve mode). Kill-switch: RULES_ENFORCE=0; auto-discharge: RULES_AUTODISCHARGE.

Repository index (wells-index)

Wells ships a Rust structural indexer (wells-index — on PyPI): tree-sitter parsing for 8 languages, SQLite + LZ4 storage, BLAKE3 incremental hashing. It powers:

  • Index-first tools — find_symbol, find_references, find_callers, search_symbols, list_symbols: exact file:line answers instead of grep walls (~98% fewer tokens per lookup).
  • The repo map — a compressed files → key symbols map injected into planner/coder prompts, ranked by relevance to the current goal, so the model starts knowing where things live instead of spending steps on discovery.
  • A background file watcher keeps the index live during a session; the indexer node refreshes it before every orchestrate run. /doctor detects a stale native core and self-repairs from the repo-bundled binaries.

Behavioral principles (AGENT.md)

Every agent in the harness — regardless of which model you've configured — is governed by the same behavioral constitution: the operating principles in AGENT.md. These 11 rules (Think Before Coding, Simplicity First, Surgical Changes, Goal-Driven Execution, Deterministic First, Budget Everything, Verify Before Trust, Fail Loud, Isolate Side Effects, Check Before Declaring Done, Evidence Over Confidence) are always injected into every agent's system prompt, so the harness behaves consistently whether you drive it with GLM, GPT, Claude, Gemini, or a local model.

This is distinct from per-project AGENTS.md memory, and from global, cross-project user memory:

AGENT.md (bundled) AGENTS.md (per-project) User memory (global)
Purpose Behavioral rules — how the agent works Project knowledge — what it knows about this repo Standing facts about you — how you like to work
Scope Every run, every agent, every project One project; accumulates over runs Every project you point Wells at
Ship location Inside the harness package The workspace root ~/.wells/memory/
Who writes it The harness authors (you can override) The harness finisher + you You, via /memory

Override precedence (highest first)

  1. WELLS_PRINCIPLES env var — point at any file path. Use this for organization-wide principles across all projects.
  2. AGENT.md in the workspace root — lets a team customize the rules for one project. Version-controlled with that project.
  3. The bundled AGENT.md — the default constitution shipped with the harness. Always present as a baseline.

Inspect the active principles with wells principles or the MCP get_principles tool.

Global user memory

AGENTS.md accumulates facts about one repo; this is the complementary, orthogonal piece — durable preferences that follow you to every project, the same category of thing Claude Code's own auto-memory keeps across conversations. An entry is a small <name>.md file directly under ~/.wells/memory/ (YAML front-matter + a short body):

---
name: terse-commit-messages
type: feedback
description: Prefers short, why-focused commit messages over detailed ones.
---

Keep commit subject lines under 50 chars. Only add a body when the "why"
isn't obvious from the diff — never restate what changed.

Unlike skills/personas (below), entries are injected directly and in full into every system prompt — even in compact mode, alongside the AGENT.md principles — since these are meant to be short standing facts the agent should always have, not on-demand procedures. A total-size budget keeps an accumulated store from bloating every prompt, trimming the oldest entries with a notice rather than silently dropping one.

Manage with /memory (list / show / add / edit / remove — CLI or the modal TUI form). type is free-form categorization (conventional values: user, feedback, reference) — it doesn't gate behavior, unlike a persona's tools: field. WELLS_USER_MEMORY=0 disables the feature entirely.

Durable project memory — BigBrain

AGENTS.md lessons and Reflexion critiques are Wells's own memory layers. On top of them, Wells embeds BigBrain as a durable transaction-log store (optional dependency: pip install 'wells-agent[memory]'; disable with WELLS_BIGBRAIN=0):

  • Write: the finisher appends every run's lesson (LEARNING) and reviewer gotchas (INVARIANT) to a locked append-only log under .bigbrain/ — crash-safe and safe under concurrent writers (fleet mode, background agents), which direct file writes are not.
  • Compile: at session end the log is deterministically reconciled into curated Markdown memory files — no LLM involved, no data loss possible by design.
  • Recall: the read-only memory_search tool (available to the planner, coder, reviewer, and read-only subagents) answers "how did similar work go before?" from that curated memory before a plan is written.
  • Reflexion mirror: failure critiques are appended to the same log, so "we already failed at this once" is keyword-recallable instead of hoping the right prompt injection fires.

Retrieval stays Wells-side: semantic_search/wells-index handle code; BigBrain search covers decisions and learnings only. Library-only embedding — BigBrain's CLI/installer/MCP surface is deliberately unused.

Agent capabilities

Three capability layers let Wells' agents teach themselves, compute, and work in parallel — each is a self-contained, feature-gated module that plugs into the same executor loop and safety model. Together they address a core insight from Microsoft's Agent Framework write-up on scaling harness capabilities: stuffing every instruction into the system prompt doesn't scale, some questions need computation not reasoning, and blocking fan-out wastes the parent agent's time.

Skills — load-on-demand know-how

The problem

Stuffing every how-to into the system prompt bloats context and dilutes focus. Wells already injects AGENT.md principles, RULES.md, a goal-ranked repo map, and pinned context into every prompt — adding domain-specific how-to (tutorials, runbooks, architecture deep-dives) to that always-on block would starve the budget for the actual task.

The solution: progressive disclosure

Skills are small SKILL.md files that package a chunk of know-how. The agent sees only each skill's name and one-line description up front (injected into the system prompt as a compact index), and loads the full body on demand via the load_skill tool — only when a request matches that skill. Context stays small and focused; domain how-to scales without bloating every call.

This is the natural complement to AGENTS.md memory:

AGENTS.md (project memory) Skills
Content Accumulated facts about a repo (what the harness learned) How-to procedures authored by you
Visibility Always-on (small, trimmed by the budget) Name + description always visible; body loads on demand
Who writes it The harness finisher + you You (via /skills menu or by hand)
Size Kept small (budget-trimmed) Can be large (only loaded when relevant)

SKILL.md format

Each skill lives in skills/<name>/SKILL.md with YAML front-matter + markdown body:

Cross-harness compatibility: Wells also discovers skills written for other harnesses — <workspace>/.claude/skills/, .agents/skills/, .codex/skills/, plus user-global ~/.claude/skills/ and ~/.agents/skills/. Any Agent Skills pack built for Claude Code, Codex, or Kimi Code works unmodified; on a name collision your own skills/ dir wins. Disable with WELLS_CROSS_SKILLS=0.

---
name: release-checklist
description: How to cut and publish a new release of this project.
---

1. Bump the version in `package.json` and `Cargo.toml`
2. Update `CHANGELOG.md` with the changes since the last tag
3. Run the full test suite: `uv run pytest -q`
4. Tag: `git tag -a v0.x.0 -m "Release v0.x.0"`
5. Push tags: `git push --tags`
6. The CD pipeline publishes to PyPI automatically

The front-matter fields:

Field Required Purpose
name Yes (defaults to folder name) The identifier the agent uses with load_skill
description Recommended One line shown in the always-on index — should help the agent decide when to load it

The body is free-form markdown — instructions, code blocks, links, diagrams. It's capped at ~8 KB when loaded (truncated with a notice) so a single skill can't blow the context budget.

Discovery

Skills are discovered from (first match wins, so earlier roots can shadow):

  1. <workspace>/skills/ — the conventional location
  2. Any extra directory in WELLS_SKILLS_PATHS (path-separator list)

Two layouts are supported:

skills/
  release/SKILL.md        ← skill folder (recommended)
  add-provider/SKILL.md
  SKILL.md                ← a single skill at the skills/ root

Discovery is cached by directory mtime, so editing or adding a skill file invalidates the cache automatically. The skills.clear_cache() call after every mutation (create/update/delete) ensures the next read sees the change.

How the agent uses skills

  1. Every system prompt includes a compact index:

    === AVAILABLE SKILLS (load with the load_skill tool) ===
    - release-checklist: How to cut and publish a new release of this project.
    - add-provider: How to add a new model provider profile.
    Call load_skill(name) to load a skill's full instructions when a request
    matches one. Do not load a skill unless it is relevant.
    === END SKILLS ===
    
  2. When a request matches a skill (e.g. "cut a release"), the agent calls load_skill("release-checklist") and the full body lands in its context.

  3. If no skill matches, nothing is loaded — zero overhead.

Managing skills with /skills

Manage skills from the TUI or CLI:

Command What it does
/skills Open the modal manager — list, view, add, edit, remove (keyboard-driven)
/skills list List all discovered skills (name + description)
/skills show <name> Print the full SKILL.md file
/skills add <name> Create a new skill (interactive; or use the modal form with Ctrl+S)
/skills edit <name> Edit an existing skill's description and/or body
/skills remove <name> Delete a skill (its folder + file)

TUI modal — bare /skills opens a full-screen manager:

Key Action
↑ ↓ Select a skill
Enter View the full SKILL.md
a Add a new skill (form: name, description, markdown body editor)
e Edit the selected skill
d Remove the selected skill
Esc Close

In the add/edit form: Ctrl+S saves, Esc cancels.

All mutations go through the safety gate (plan/approve/dryrun apply), validate the skill name (lowercase letters, digits, hyphens — blocks path traversal), and only delete skills under the workspace skills/ tree (skills loaded from WELLS_SKILLS_PATHS can't be deleted from the menu).

Configuration:

Variable Default Description
WELLS_SKILLS 1 Discover skills and expose load_skill (set 0 to disable)
WELLS_SKILLS_PATHS (blank) Extra skill search dirs (OS path-separator list)

CodeAct — let it compute

The problem

Some questions are calculations, not lookups: "what's the total LOC across the changed files", "does this regex match all 12 of these strings", "generate the cartesian product of these test configurations", "count how many functions transitively call auth_check". Doing arithmetic in the model's head or eyeballing a regex is exactly what the harness's "Deterministic First" and "Verify Before Trust" principles say not to do.

The solution: run_code

CodeAct gives the agent a run_code tool: it writes a small Python snippet, the harness runs it in a workspace-confined subprocess, and returns structured stdout / stderr / exit code. The agent gets a clean, bounded result to reason over — no guessing.

Example tool calls the agent makes:

# Count lines changed in the working tree
import subprocess
diff = subprocess.check_output(["git", "diff", "--stat"]).decode()
print(diff)

# Validate a regex against test strings
import re
pat = re.compile(r'^\d{4}-\d{2}-\d{2}$')
for s in ["2024-01-15", "99-1-1", "2024-13-40"]:
    print(f"{s}: {'match' if pat.match(s) else 'no match'}")

Confinement + guardrails

Guardrail What it does
Workspace-confined cwd = workspace, so open("src/utils.py") works for repo inspection
Source screening Refuses code containing os.system, subprocess, popen, __import__, or fork() — use run_command for shell work
Deny-list screening The same BLOCKED_COMMANDS regex list that screens run_command is applied to the source text (catches rm -rf / in a string literal)
Output truncation stdout capped at 8 KB, stderr at 4 KB — a runaway print in a loop can't blow the budget
Timeout Hard wall-clock cap (default 30s via CODEACT_TIMEOUT; also bounded by SHELL_TIMEOUT)
Safety gate Honours plan/dry-run/approve modes like every other mutating tool
Sandbox mode Under HARNESS_SAFETY=sandbox / /mode sandbox, run_code executes inside the same disposable container as run_command (piped over stdin) instead of a host subprocess — see Safety model

Why a confined subprocess, not Hyperlight/Monty? Zero extra dependencies — works out of the box everywhere Python runs. Workspace confinement + the existing safety gate + the deny-list give the same first line of defense the article's LocalShellExecutor relies on, and sandbox mode (see Safety model) adds real container isolation on top for anyone who wants it, without imposing it by default.

Configuration:

Variable Default Description
WELLS_CODEACT 1 Expose the run_code tool (set 0 to disable)
CODEACT_TIMEOUT 30 Max seconds for a single run_code execution

Code Mode — compose many tool calls into one

run_code computes; Code Mode (program tool) orchestrates. The model writes one Python program in which every registered harness tool is a plain callable on a tools object — turning a chain of dependent lookups from N model round trips (each 5–30s of token generation) into one turn of milliseconds-fast tool execution:

program('''
listing = tools.list_dir(path="src")
api = tools.read_file(path="src/api.ts")
callers = {n: tools.grep(pattern=n) for n in ["handleIssue", "closeIssue"]}
RESULT = {"api_len": len(api), "callers": callers}
''')

Every inner call dispatches through the ordinary tool pipeline, so the safety gate, plan/dry-run modes, and deny-lists all apply inside the program — permissions the model can't see past. Guardrails: restricted exec (no open/exec/eval/__import__; imports limited to pure computation stdlib), budgets (40 tool calls / 200k result chars / wall-clock timeout), cancel checked before every inner call. This is guardrails for well-behaved models, not a hard security boundary — the safety modes are the boundary. WELLS_CODE_MODE=0 disables (recommended for weak/local model profiles, where orchestration code costs more than it saves).

Variable Default Description
WELLS_CODE_MODE 1 Expose the program tool
CODE_MODE_TIMEOUT 120 Max seconds for one program execution

Browser — drive a real, JS-rendered session

The problem

fetch_url only ever sees a page's initial static HTML. Most real web apps — single-page apps, dashboards, a local dev server's own frontend — render their actual content with JavaScript, so fetch_url against them returns an empty shell. Verifying a UI change, working through a logged-in flow, or filling out a multi-step form needs a real browser, not a text fetch.

The solution: browser_navigate / browser_click / browser_type / browser_read / browser_screenshot

A genuine headless browser session (Playwright), lazily launched on first use and kept alive for the rest of the process — cookies and login state persist across calls within a session, the same way a human keeps one tab open. Playwright drives whichever Chromium-based browser is already installed (Chrome, Edge, Brave) rather than downloading its own copy, falling back to Playwright's bundled Chromium only if none is found — WELLS_BROWSER_EXECUTABLE pins an exact path if auto-detection picks the wrong one.

Tool What it does
browser_navigate Open a URL; returns the title + rendered visible text
browser_click Click an element by CSS selector or visible text (falls back to a text search)
browser_type Type into an input by selector or visible label/placeholder; optional submit
browser_read Return the current page's rendered visible text
browser_screenshot Screenshot the page and get back a text description of its layout and every interactive element

browser_screenshot routes the PNG through the configured vision profile (MODEL_PROFILE_VISION — see Provider profiles) automatically, so screenshots are readable even when the active model isn't vision-capable itself; if no vision profile resolves to something usable it still saves the file and says so instead of failing the call.

browser_navigate / browser_read / browser_screenshot are read-only (no safety gate, same as fetch_url); browser_click / browser_type can have real side effects (submit a form, click "delete") and go through the same plan/approve/dryrun gate as every other mutating tool.

On by default, same as the other agent capabilities — the tools are always registered, so the agent knows they exist. Playwright the package still needs a one-time separate install (not part of the base dependency set):

pip install 'wells[browser]'      # or: uv sync --extra browser

The Chromium download step (playwright install chromium) usually isn't needed at all — if Chrome, Edge, or Brave is already on the machine (true for almost everyone), Wells drives that instead. Only run it if none of those are installed. Calling a browser_* tool before Playwright itself is installed returns a clear, actionable error instead of silently failing — the same pattern the anthropic/ollama/google provider profiles already use for their own optional packages. Turn the tools off entirely with WELLS_BROWSER=0 (or the /config picker) if you don't want them offered at all.

Configuration:

Variable Default Description
WELLS_BROWSER 1 Expose the browser_* tools (set 0 to disable; still needs the browser extra installed to actually run)
WELLS_BROWSER_HEADLESS 1 Run headless (set 0 to watch it drive a real window)
WELLS_BROWSER_EXECUTABLE (auto-detect) Pin an exact browser executable path, skipping auto-detection

Background agents — concurrent fan-out

The problem

parallel_research already fans out 2–4 read-only research subagents in parallel — but it blocks: the parent agent waits for all subagents to finish before it can do anything else. If one subagent takes 30 seconds, the parent is stuck for 30 seconds. The fan-out timing is also the tool's decision, not the agent's.

The solution: start / check / collect

Background agents flip the blocking pattern to the async start / check / collect model from the article. The agent gets three tools:

Tool What it does Returns
bg_start Launch a sub-agent on a background daemon thread Handle id (e.g. bg-1) — immediately, does not block
bg_status Poll all background agents List with status (running/done/error/cancelled) + elapsed seconds
bg_collect Collect a finished agent's report (once) The subagent's full report, or "still running" if it isn't done

The fan-out becomes the agent's decision: it starts N tasks, keeps working (reading files, making edits, running tests), and collects results when convenient — checking back periodically with bg_status.

Example workflow the agent drives:

bg_start(task="research the auth module's token validation flow")    → bg-1
bg_start(task="research the database migration history")             → bg-2
bg_start(task="find all callers of the deprecated API")              → bg-3

  # Agent keeps working while they run:
  read_file("src/main.py")
  edit_file("src/main.py", ...)
  run_tests()

bg_status                                                            → bg-1: done, bg-2: done, bg-3: running
bg_collect(id="bg-1")                                                → report from auth research
bg_collect(id="bg-2")                                                → report from migration research
  # bg-3 still running — collect later or move on

Roles — research, fix, worktree

Role Edits? Where Use when
research (default) No — Read-only investigation; safe to fan out widely
fix Yes Parent workspace directly One editor in flight, or edits target disjoint files
worktree Yes Its own isolated git worktree, cherry-picked into the parent on bg_collect Multiple write-fan-outs target overlapping areas, or whenever isolation is cheaper than reasoning about interleaving

The worktree role is what unblocks parallel write steps: two bg_start role=worktree agents run genuinely concurrently against their own checkouts (shared object store — fast, disk-cheap), and bg_collect merges each one's commit back into the parent. On conflict the cherry-pick is aborted and the diff is returned to the parent agent for manual re-apply — no surprise merges, no semantic guesses. Requires git; non-git workspaces get an error pointing at role=fix.

bg_start(task="refactor the auth middleware", role="worktree")        → bg-1
bg_start(task="refactor the session middleware", role="worktree")     → bg-2
bg_start(task="refactor the rate-limiter",   role="worktree")         → bg-3

  # All three edit concurrently in their own worktrees; the parent's
  # working tree is untouched until each is collected.

bg_status                                                            → all three: done
bg_collect(id="bg-1")                                                → merged into parent
bg_collect(id="bg-2")                                                → CONFLICT, diff returned
bg_collect(id="bg-3")                                                → merged into parent

Lifecycle + safety

Property Behaviour
Concurrency Each sub-agent runs on a daemon thread (LLM calls are I/O-bound, matching parallel_research)
Registry Process-wide, keyed by short stable ids (bg-1, bg-2, …); resets at the start of each executor run so slots don't leak
Collect once A result is collected at most once, then cleared — keeps memory bounded across a long run
Recursion blocked A sub-agent cannot start its own background agents (ctx.subagent is checked at dispatch)
Cooperative cancellation Escape / CONTROL.cancel() marks running slots as cancelled; pending threads check at step boundaries
Worktree reaping For role="worktree", the worktree + branch are reaped on collect and on reset() — a cancelled run never leaks disk
Roles role=research (read-only, default), role=fix (parent workspace), or role=worktree (isolated checkout, merged on collect)
Safety gate Each sub-agent's tool calls pass through the same safety gate as the parent

Contrast with parallel_research:

parallel_research Background agents (bg_*)
Blocking Yes — parent waits for all to finish No — returns immediately, collect later
Fan-out timing Tool's decision (2–4 fixed) Agent's decision (any number)
Parent works during? No Yes
Read-only? Yes research = yes; fix / worktree = can edit
Isolation N/A (read-only) fix = parent workspace; worktree = own checkout
Use case Quick parallel exploration Long-running fan-out the parent checks back on

Configuration:

Variable Default Description
WELLS_BG_AGENTS 1 Expose bg_start/bg_status/bg_collect (set 0 to disable)
WELLS_BG_WORKTREES 1 Allow bg_start role=worktree (isolated git worktree per sub-agent; set 0 to refuse the role without disabling the bg tools)

Subagent personas — custom specialist identities

The problem

bg_start's research/fix/worktree roles control mutation mechanics (read-only vs. writes vs. isolated checkout) but say nothing about expertise — every subagent gets the same generic prompt regardless of what it's actually being asked to do. A security review and a performance investigation deserve different framing, different things to look for, different tone in the report back.

The solution: PERSONA.md + bg_start(persona=...)

A persona is a small agents/<name>/PERSONA.md file — discovered, cached, and CRUD'd exactly like skills — that packages a subagent identity: a system prompt establishing its expertise/voice/constraints, plus which toolset tier it gets:

---
name: security-reviewer
description: Reviews a diff for injection/auth/secrets issues before merge.
tools: readonly
---

You are a senior application-security reviewer. For every file you're
shown, look specifically for: injection (SQL/command/template), broken
auth/session handling, hardcoded secrets, and unsafe deserialization.
Report findings as `file:line — issue — why it's exploitable`.

Even cheaper than skills: a persona's full system prompt never touches the parent's context at all — only its name + one-line description show up there (so the parent knows it exists), and the full prompt is handed to the subagent run itself the moment bg_start(persona=security-reviewer, role=research, task="review this diff") picks it. role still governs mutation/isolation mechanics — role=research is always forced read-only regardless of what a persona's tools: front-matter requests; the role is the safety ceiling, the persona is the voice/expertise within it.

Manage with /agents (list / show / add / edit / remove — CLI or the modal TUI form, identical interaction model to /skills). WELLS_AGENTS=0 disables discovery; WELLS_AGENTS_PATHS adds extra search directories (path-separator list), same convention as WELLS_SKILLS_PATHS.

Model-driven todo list

The problem

The pipeline breadcrumb (in The TUI) shows structural graph position — which fixed node (planner/coder/tester/...) is running — but nothing about what the coder actually decided to do inside a long, multi-step task. That's the transparency Claude Code's own todo-list rendering gives that a fixed pipeline view can't.

The solution: update_todos

A tool the model calls to declare or update its own task breakdown for the current task — rendered live as a third, independent section of the info panel. Resends the full list each call (no partial-update API to keep in sync); at most one item may be in_progress at a time, so the panel always has one unambiguous point of progress to highlight. Read-only (pure in-memory display state, no workspace mutation), so it's available to read-only investigations too, same as web_search/fetch_url. Cleared at the start of every run — a todo list belongs to one task, not the whole session. WELLS_TODO=0 disables it.

Self-improvement — Reflexion, auto-skill authoring & SEACS evolution

Three closed loops turn each run's outcome into a durable asset so Wells gets better at this repo — and, with SEACS, at being Wells — the more you use it. All three are human-readable/inspectable, version-controlled alongside the code, and gate any promotion behind explicit approval (yours, or an oracle-scored benchmark's).

Reflexion — persistent failure critiques

The problem

The reviewer and tester already emit rich, human-readable critiques when a run fails — but until now those critiques were ephemeral: they steered the coder's next iteration within the same run, then disappeared. The same failure mode could repeat verbatim on the next run, against the same repo, with no memory of having hit it before.

The solution: capture, dedupe, re-inject

After a run that failed the deterministic test gate or was genuinely rejected by the reviewer, the finisher writes a structured, timestamped critique to .wells/reflections.md:

### 2026-07-29 14:02 — wire up the payment webhook
- type: test_failure
<!-- sig: a3f9c1e08b4d -->
Critique: Automated test gate failed for this goal. FAILED tests/test_pay.py::test_sig - AssertionError: bad sig
Evidence:
FAILED tests/test_pay.py::test_sig - AssertionError: bad sig

Before the next run, the planner retrieves the top-K reflections relevant to the current goal (keyword-overlap ranking — deterministic and free; opt-in embedding re-rank with WELLS_REFLECTIONS_EMBED=1) and prepends them, so it starts already warned about the project's known traps:

PAST REFLECTIONS — failures this project hit before. Avoid repeating them:
[1] (test_failure) Automated test gate failed... bad sig
    goal: wire up the payment webhook
Behaviour Detail
What gets captured Deterministic test-gate red (tests_passed=False) or a real reviewer rejection (review_complete=False). Dry/plan runs never captured.
What does not Infra failures (review_error — an expired API key is not a lesson about this repo)
Dedup Each block carries a <!-- sig: ... --> fingerprint (type + goal keywords + evidence head), so the same failure loop is recorded once, not every iteration
Compaction A size cap folds the oldest entries into one summary line, the same strategy AGENTS.md uses
Safety gate Honours plan/approve/dryrun like every other write

Review or clear with /reflections (list / clear). Nothing about reflections is hidden — it's a plain markdown file you can edit, prune, or commit alongside the code it describes.

Auto-skill authoring — package verified runs into reusable skills

The problem

Skills are only ever as good as the procedure they encode. The most reliable procedures are the ones a run has already proven — a clean, verified execution path through this exact repo. Until now those paths stayed trapped in the run trace; the next similar task had to rediscover them from scratch.

The solution: qualify → propose → approve

Stage What happens
1. Qualify After a run, the finisher confirms it was genuinely verified (reviewer COMPLETE + suite green or no runnable tests) and actually produced a non-trivial change. Dry-run/plan runs and infra failures never qualify.
2. Propose The verified plan is packaged into a SKILL.md proposal staged under .wells/skill-proposals/. Proposals are not scanned by the skills system, so they cost zero context and cannot be loaded by the agent until promoted.
3. Approve You review proposals and either accept or reject each one. Accepting moves the file to .wells/skills/<name>/SKILL.md (a discoverable root) and clears the skill cache; from the next run on, the agent can load_skill it like any hand-authored skill.

Name/description/body synthesis is deterministic (no extra LLM call) — derived from the planner's verified steps and the coder's change summary. WELLS_AUTOSKILL_LLM=1 opts into a cheap-model-polished name and summary. A minimum-step threshold (WELLS_AUTOSKILL_MIN_STEPS, default 2) skips trivial one-liners so the proposal queue stays useful.

Three ways you find out a skill was proposed

Wells never silently promotes anything — but it does make sure you notice a proposal exists:

  1. End-of-run panel (every surface — TUI, headless, plain CLI). A highlighted ╭─ self-improvement ─╮ box appears right after the run summary, naming the proposed skill and showing the exact /skills proposals accept <name> / reject <name> commands. Silent when nothing was learned.
  2. Right-panel banner (TUI). A ⚡ N skill proposals — click to review bar appears at the top of the info panel within a second of the run finishing. Clicking it opens the review modal. Collapses to zero height when there's nothing pending.
  3. Review modal (TUI). /skills proposals (or the banner click) opens ProposalReviewScreen: list, view full body, accept, reject, or edit-then-accept (tweak name/description/body before promoting).
Command What it does
/skills proposals Open the visual review modal (TUI), or list proposals (CLI)
/skills proposals list List staged proposals (name + description + source goal)
/skills proposals show <name> Print a proposal's full staged file
/skills proposals accept <name> Promote a proposal to a discoverable .wells/skills/<name>/SKILL.md
/skills proposals reject <name> Delete a staged proposal
/reflections List captured failure critiques (or clear the file)

Configuration

Variable Default Description
WELLS_REFLECTIONS 1 Capture failure critiques to .wells/reflections.md and inject them into the planner (set 0 to disable)
WELLS_REFLECTIONS_K 3 Top-K reflections injected per goal
WELLS_REFLECTIONS_EMBED 0 Opt-in embedding re-rank (uses the local ONNX embedder; keyword ranking is the free default)
WELLS_REFLECTIONS_LLM 0 Opt-in LLM-distilled critique (one cheap-model call per captured failure)
WELLS_AUTOSKILL 1 Propose skills from clean, verified runs (set 0 to disable)
WELLS_AUTOSKILL_MIN_STEPS 2 Minimum plan steps a clean run must have to be worth packaging
WELLS_AUTOSKILL_LLM 0 Opt-in LLM-polished skill name + description + summary

Both features degrade to no-ops when disabled — a clean run with nothing learned produces no panel, no banner, and no proposal.

SEACS — oracle-scored bench + AGENT.md evolution

The problem

Reflexion and auto-skill authoring both improve Wells within a repo, one run at a time — but nothing measures whether a change to the harness itself (its behavioral principles, its tools, its skills) actually makes it better at coding in general, versus just "different." A prompt tweak that reads well can still be a net regression, and there's no way to know without an honest, repeatable measurement.

The solution: mine a task corpus, score it with an oracle, gate every change

wells bench turns a repo's own git history into a small SWE-bench-style benchmark: it walks non-merge commits that touch tests and source together, extracts the pytest node IDs the fix commit added, and dual-validates each candidate in a throwaway worktree — the target tests must genuinely fail at the base commit and pass at the fix commit, no LLM judgment involved. Only tasks that clear that bar are admitted, split deterministically 60/20/20 into train/val/blind (a stable hash of the task id, so the same task always lands in the same split).

wells bench mine --repo <repo> [--max N] [--skip-validation]
wells bench list [--split train|val|blind|all]
wells bench run --split val --profile zai [--task ID] [--seeds N] [--timeout SECONDS]
wells bench results [ID]

Running a split checks out each task's base_commit in an isolated worktree, runs a full headless harness attempt against the bare problem statement, then scores it with the task's own oracle — the model's own COMPLETE/INCOMPLETE claim is never trusted, only the test exit code. Results are Wilson-bounded (95% lower bound on pass@1), so two harness configurations are compared on the conservative estimate, not the noisy point estimate.

wells evolve is the first thing that acts on that number: it proposes a candidate replacement for the harness's own constitution (AGENT.md), gates it against a baseline using wells bench run, and promotes or rejects it.

wells evolve propose --file candidate.md "tighten the disk-budget rule"
wells evolve propose --auto "address recent bench failures"   # opt-in — spends real tokens
wells evolve gate <mutation_id> --split val [--profile zai]
wells evolve list
wells evolve show <mutation_id>
wells evolve promote <mutation_id>   # writes the candidate to AGENT.md
wells evolve reject <mutation_id>

gate runs two full bench passes over the split — one pinned to the current principles, one pinned to the candidate (via the AGENT.md override chain's top-precedence $WELLS_PRINCIPLES env var, so it's the only variable that changes between passes) — plus a free sanity pass over the recorded trace corpus (wells replay's scripted-model regression check — see traces.py in Project structure — no LLM calls). A candidate is recommended for promotion only when its Wilson lower bound is at least as good as the baseline's. Nothing auto-promotes: promote is always a separate, explicit step, and it never commits on your behalf — the written AGENT.md is a normal tracked file for you to review.

Command What it does
wells bench mine Mine a repo's history into a dual-validated, oracle-scored task corpus
wells bench run Execute a split, score it against the oracle, save Wilson-bounded results
wells evolve propose Stage a candidate AGENT.md — from a file (free) or --auto (one real harness run)
wells evolve gate Baseline-vs-candidate bench passes + replay, produce a promote/reject recommendation
wells evolve promote / reject Write the candidate to AGENT.md, or mark it rejected

Everything persists under ~/.wells/bench/ (per-workspace corpus + results under <workspace>/.wells/bench/) and ~/.wells/evolve/mutations/ — plain JSON, inspectable and diffable like any other run artifact.

MCP — server and client

Server: drive Wells from other agents

The harness exposes its capabilities as a Model Context Protocol server over stdio, so external agent clients (Claude Code, OpenCode, Codex CLIs, Gemini CLI, …) can invoke the harness:

wells-mcp          # console script

Exposed tools include run_agent_task (full loop), plan_task, review_code, run_executor, spawn_subagent, search_repo, read_file, run_command, git_status, get_memory, compress_logs, get_harness_info, and get_principles.

{
  "mcpServers": {
    "wells": { "command": "wells-mcp", "args": [] }
  }
}

Client: give Wells external tools

Wells also connects out to MCP servers (databases, docs, GitHub, memory banks) and registers their tools for the agent as mcp_<server>_<tool>. Two transports are supported:

Transport Spec shape Use when
stdio {"command": "...", "args": [...]} Local subprocess — the classic MCP servers (uvx mcp-server-fetch, npx @modelcontextprotocol/server-*)
HTTP (streamable-http) {"url": "https://...", "headers": {...}} Remote MCP server speaking the newer spec (default when url is present)
SSE (legacy) {"url": "https://...", "transport": "sse"} Remote server that only speaks the older SSE protocol

Configure via the /mcp modal manager in the TUI (add / enable / disable / test / remove — no JSON editing), the /mcp add … subcommands (auto-routes: a second arg starting with http(s):// becomes an HTTP server; otherwise it's stdio), or by editing ~/.wells/mcp.json directly (created on first run with ready-to-enable samples: fetch, filesystem, github, postgres, sqlite, memory, plus HTTP/SSE templates). The MCP_SERVERS env var (JSON) overrides the file. Every external call passes the safety gate, so approve and dryrun apply to MCP tools too.

ACP — drive Wells from your editor

Wells ships an Agent Client Protocol server (wells-acp): JSON-RPC over stdio, the protocol Zed, JetBrains, and other ACP-capable editors speak natively. A editor can open a session, send prompts (each runs the full Wells pipeline headlessly and streams turn updates back), and cancel mid-run — no terminal required:

// Zed: ~/.config/zed/settings.json
{
  "agent_servers": {
    "Wells": { "type": "custom", "command": "wells-acp", "args": [], "env": {} }
  }
}
Capability Status
initialize / session/new / session/prompt / session/cancel ✓
Turn streaming (session/update notifications) ✓ (turn start/complete + final message; token-level streaming is an easy upgrade via the event bus)
fs/read_text_file Unsupported (editors fall back to their own reads)
Session resume across server restarts Not yet (loadSession: false)

Project structure

src/wells/
├── main.py            # CLI entry: run / config / info / principles
├── cli.py             # REPL command layer: slash commands, run paths
├── tui.py             # Textual TUI: log, prompt, status bar, modals
├── control.py         # run control: cooperative cancel, activity, UI events
├── settings.py        # settings schema + .env persistence
├── config.py          # env vars, budgets, workspace/safety knobs
├── providers.py       # named provider profiles → chat-model factory
├── pricing.py         # dollar-cost estimation from the token ledger
├── state.py           # TypedDict LangGraph state
├── graph.py           # LangGraph workflow with conditional routing
├── runtime.py         # run_step(): LLM call + usage capture (reasoning nodes)
├── executor.py        # agentic tool loop: native+text tools, masking, streaming
├── tools.py           # repo tools: read/glob/grep/write/edit/shell/subagents
├── checkers.py        # post-edit self-heal: fast (ruff/node --check/json) + semantic (pyright/tsc/cargo/go vet)
├── notify.py          # run-completion desktop + webhook notifications
├── spend_guard.py     # cross-run daily spend cap
├── repomap.py         # goal-ranked repo map (files → key symbols)
├── safety.py          # workspace confinement + auto/approve/dryrun gate
├── subagents.py       # parallel read-only research fan-out
├── memory.py          # AGENTS.md project memory
├── gitops.py          # branch/commit/PR + working-tree snapshots (/undo)
├── finisher.py        # post-run memory write-back + git/PR node
├── sessions.py        # session persistence, /resume, per-node checkpoints
├── tokens.py          # token estimation, thread-safe ledger, usage report
├── context.py         # categorized, budget-trimmed prompt assembly
├── compress.py        # log/output compressor
├── summarize.py       # rolling task-state summarizer
├── index_tools.py     # wells-index bindings + stale-core self-repair
├── index_watcher.py   # background incremental re-indexing
├── mcp_server.py      # MCP server (Wells as a tool provider)
├── mcp_client.py      # MCP client (external tools for the agent)
├── logo.py            # TUI glyph lockup
├── principles.py      # AGENT.md injection
├── skills.py          # Agent skills: discoverable SKILL.md, load-on-demand
├── skill_authoring.py # Auto-skill authoring: package verified runs into skill proposals (self-improvement #2)
├── reflections.py     # Reflexion: persistent failure critiques → planner injection (self-improvement #1)
├── codeact.py         # CodeAct: sandboxed run_code tool
├── browser.py         # Browser tools: navigate/click/type/read/screenshot (Playwright)
├── sandbox.py         # sandbox mode: disposable per-workspace container (Podman/Docker) for run_command
├── background.py      # Background agents: bg_start/bg_status/bg_collect (research/fix/worktree)
├── worktree.py        # Per-subagent git worktrees (role=worktree isolation + cherry-pick)
├── personas.py        # Subagent personas: agents/<name>/PERSONA.md, discoverable custom identities*
├── user_memory.py     # Global user memory: ~/.wells/memory/, cross-project standing preferences
├── schedule.py        # wells schedule: unattended recurring runs (Task Scheduler / cron)
├── todo.py            # update_todos tool: model-declared task breakdown for the info panel
├── traces.py          # run-trace recording + wells replay (scripted-model regression check)
├── fleet.py           # wells fleet: N parallel worktree attempts at the same task
├── evolve/            # SEACS: bench + evolution engine (self-improvement #3)
│   ├── schema.py      #   TaskSpec + Oracle — one historical fix + its deterministic test oracle
│   ├── corpus.py      #   git-history mining, dual validation, train/val/blind split assignment
│   ├── runner.py      #   isolated worktree bench execution, oracle scoring, Wilson-bounded metrics
│   └── mutate.py      #   propose/gate/promote/reject AGENT.md mutations against a bench split
└── agents/            # planner / architect / coder / tester / reviewer
wells-index/           # Rust structural indexer (tree-sitter + SQLite)
.github/workflows/     # ci.yml (pytest) + release-index.yml (PyPI wheels)

*personas.py manages the workspace-level agents/ content directory (user-authored PERSONA.md files) — a different thing from the src/wells/agents/ package above it (the harness's own planner/ architect/coder/tester/reviewer code). Named personas.py, not agents.py, specifically to avoid colliding with that package.

Configuration reference

Variable Default Description
MODEL_PROFILES zai Comma-separated list of configured profile names
MODEL_PROFILE zai Active profile for main reasoning/coding
MODEL_PROFILE_CHEAP (blank) Profile for low-stakes subtasks (defaults to active)
MODEL_<name> / API_KEY_<name> / BASE_URL_<name> — Per-profile model, key, endpoint
MODEL_PRICE_<name> (rate table) Exact $/1M rates: in,out
WORKSPACE_ROOT cwd Directory the agent is confined to
HARNESS_SAFETY auto auto / approve / dryrun (or use /mode)
PLAN_MODE 0 When on, mutating tools simulate
MAX_ITERATIONS 0 (no limit) Max coder↔reviewer loops
MAX_TOOL_STEPS 0 (no limit) Max tool-call rounds per executor run
PLANNER_MAX_STEPS / TESTER_MAX_STEPS / REVIEWER_MAX_STEPS / SUBAGENT_MAX_STEPS 0 (no limit) Per-agent step caps
MAX_RUN_TOKENS 0 (off) Hard token cap per run; warns at 80%
SELF_CHECK 1 Post-edit lint/syntax self-heal
WELLS_SEMANTIC_CHECK 0 Post-edit type-checker self-heal (pyright/mypy, tsc, cargo check, go vet) — project-aware, opt-in
WELLS_NOTIFY 0 Desktop + webhook notification on run completion
WELLS_NOTIFY_WEBHOOK_URL (blank) POST target for run-completion notifications (Slack-compatible payload)
WELLS_DAILY_BUDGET 0 (off) Refuse new runs once today's cumulative spend reaches this many dollars
CHEAP_VERIFY 1 Route tester/reviewer to the cheap profile
AUTO_COMMIT 0 Commit each successful run (Conventional Commits)
STREAM_OUTPUT 1 Stream answers token-by-token
INDEX_AUTO_UPDATE 1 Keep the repo index fresh automatically
MCP_SERVERS (blank) JSON server map; overrides ~/.wells/mcp.json
SHELL_TIMEOUT 120 Max seconds for a single shell command
TOKEN_BUDGET_MAX_INPUT 24000 Input budget per call (above this, trims)
SUMMARIZE_ON_LOOP 1 Replace durable context with a summary on loops
LLM_TIMEOUT / LLM_MAX_RETRIES 180 / 5 Per-call timeout / transient-error retries
WELLS_OPEN_PR 0 When 1, the finisher pushes + opens a PR via gh
WELLS_PRINCIPLES (bundled) Path to a custom AGENT.md constitution
BLOCKED_COMMANDS (see source) |-separated regex patterns always refused
WELLS_MASK_BATCH 4 Batch-stable masking: don't re-mask until the cutoff has advanced this many rounds past the last batch (0 = mask every round, the old behavior)
WELLS_SKILLS 1 Discover skills/<name>/SKILL.md and expose load_skill (on/off)
WELLS_SKILLS_PATHS (blank) Extra skill search dirs (path-separator list)
WELLS_REFLECTIONS 1 Capture failure critiques to .wells/reflections.md and inject them into the planner (Reflexion)
WELLS_REFLECTIONS_K 3 Top-K reflections injected per goal
WELLS_REFLECTIONS_EMBED 0 Opt-in embedding re-rank of reflections (uses the local ONNX embedder)
WELLS_REFLECTIONS_LLM 0 Opt-in LLM-distilled critique (one cheap-model call per captured failure)
WELLS_AUTOSKILL 1 Propose skills from clean, verified runs (auto-skill authoring)
WELLS_AUTOSKILL_MIN_STEPS 2 Minimum plan steps a clean run must have to be worth packaging as a skill
WELLS_AUTOSKILL_LLM 0 Opt-in LLM-polished skill name + description + summary
WELLS_CODEACT 1 Expose the sandboxed run_code tool for in-context computation
CODEACT_TIMEOUT 30 Max seconds for a single run_code execution
WELLS_BG_AGENTS 1 Expose bg_start / bg_status / bg_collect for concurrent fan-out
WELLS_BG_WORKTREES 1 Allow bg_start role=worktree (isolated git worktree per sub-agent)
MODEL_PROFILE_VISION (blank) Profile routed to for image-attached tasks when the active profile isn't vision-capable (defaults to active)
WELLS_BROWSER 1 Expose the browser_* tools (set 0 to disable; still needs the browser extra installed to actually run)
WELLS_BROWSER_HEADLESS 1 Run the browser session headless (set 0 to watch it)
WELLS_BROWSER_EXECUTABLE (auto-detect) Pin an exact browser executable path, skipping auto-detection of Chrome/Edge/Brave
WELLS_SANDBOX_IMAGE python:3.12-slim Container image used for sandbox mode's disposable container
WELLS_SANDBOX_RUNTIME (auto) Pin the container CLI (podman or docker); auto-detects, preferring Podman
WELLS_AGENTS 1 Discover agents/<name>/PERSONA.md and expose them to bg_start(persona=...)
WELLS_AGENTS_PATHS (blank) Extra persona search dirs (path-separator list)
WELLS_USER_MEMORY 1 Inject standing preferences from ~/.wells/memory/ into every project's prompts
WELLS_USER_MEMORY_DIR ~/.wells/memory Override the global memory directory (mainly for tests)
WELLS_TODO 1 Expose update_todos for a model-declared live task breakdown in the info panel

Legacy ZAI_* variables keep working unchanged — they seed the built-in zai profile.

Token & cost optimization

Component What it does
Estimator + Ledger tiktoken-based, auto-calibrated; thread-safe per-step actuals from usage_metadata
Dollar pricing Live cost in the status bar and run footers
Observation masking Old tool outputs compressed to typed one-liners; AI reasoning turns kept verbatim
Batch-stable masking Masking fires in batches (_MASK_BATCH_ROUNDS), so the provider's prompt cache stays warm between batches instead of being invalidated every round. wells analyze reports cache breaks round-by-round
Working memory Compact structured state (files read/modified, failed approaches, test status) injected every round — prevents re-reads and repeated failures
Repo map Goal-ranked structure injection — fewer discovery steps
Deterministic gates Real test runs and fast checkers replace LLM judgment calls where possible
Summarizer + trimming Rolling task-state summary on loops; categorized budget trimming
Model router Cheap profile for summarization/classification/verification

Tests & CI

uv run pytest -q          # 1000+ tests (a handful more if the optional
                           # `browser` extra + Chromium are installed)

The suite covers provider resolution, tool confinement + every safety mode, the executor loop (mocked model — no API credits needed), cancellation and budget stops, graph routing (complexity skip, test-gate fail-fast), fuzzy edits, self-heal checkers, repo-map ranking, git snapshot/undo, pricing, MCP client CRUD, background-agent worktree lifecycle (create/merge/conflict/reap), the settings persistence, and SEACS bench/evolve (corpus dual-validation on real git repos, oracle scoring, Wilson bounds, mutation propose/gate/promote — all stubbed, no LLM calls in CI). GitHub Actions runs it on every push/PR (ci.yml); release-index.yml builds and publishes wells-index wheels (Linux/macOS/Windows × Python 3.12/3.13) to PyPI on an index-v* tag.

Roadmap

  • Embedding-based retrieval for very large repos. ✅ Shipped — see "Semantic code retrieval" below.
  • Live progress / no more silent waits. ✅ Shipped — the executor emits llm_start / retry-backoff / first-token / tool-progress events through the UI bus; every pipeline node reports stage timings; long shell commands tick elapsed time in the status bar.
  • Code Mode (compose N tool calls in one turn). ✅ Shipped — the program tool, with safety gating inside the program.
  • Editor integration via ACP. ✅ Shipped — wells-acp.
  • Durable project memory. ✅ Shipped — BigBrain transaction-log memory (memory_bridge), memory_search recall, Reflexion mirroring.
  • Cross-harness skill compatibility. ✅ Shipped — .claude/.agents/ .codex skill dirs discovered natively.
  • SEACS corpus growth — the self-improvement loop's biggest lever: mine more repos (wells bench mine --env-setup '...' now handles repos a bare checkout can't run), quarantine structurally unreliable tasks, grow the val split past zero so evolve gate runs end-to-end.
  • Sandbox-by-default — flip the WELLS_SANDBOX_AUTO shipped default to on once the container path has soaked in real unattended runs.
  • Rust launcher / single-binary distribution — a compiled shell around the Python engine for millisecond cold start and one-command install.

Semantic code retrieval

Wells ships optional embedding-based symbol search alongside the structural indexer. The semantic_search tool finds functions/classes by meaning rather than exact name — useful when the user (or the planner) describes what something does without naming it.

  • Model: BAAI/bge-small-en-v1.5 (384-dim, runs locally via ONNX).
  • Storage: sqlite-vec virtual table inside the existing .wells_index/index.db — no separate vector database.
  • Repomap re-rank: when embeddings are available, build_repo_map blends cosine similarity with the keyword heuristic, so files are ranked by semantic relevance to the goal (capped at +8.0 boost so keyword hits still dominate).

Install behaviour

The launcher (wells.bat / wells) auto-installs fastembed and sqlite-vec on first run, after the main uv sync. The install is:

  • Cached: a stamp file (.venv/.embed-stamp) keyed on pyproject.toml means it only runs once per spec change.
  • Best-effort: if the install fails (e.g. corporate proxy blocks PyPI), Wells still starts; semantic_search returns an informative message and the other tools are unaffected.
  • Opt-out: set WELLS_NO_EMBEDDINGS=1 to skip the install entirely (e.g. for CI or minimal-footprint installs).

Manual install also works: uv pip install fastembed sqlite-vec.

The corpus is embedded once (a few seconds for a typical repo, more on a slow network for the first-ever model download); subsequent calls hit the cached table. An explicit semantic_search tool call embeds synchronously on first use (the model asked for a result and needs it to proceed), but the passive repomap re-rank never blocks a run waiting on it: it kicks the embed off in a background thread and falls back to keyword-only ranking until it lands — so a cold corpus can't turn "building repo map" into a multi-second stall on every message.

Metadata

Release files for wells-agent 0.3.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for wells-agent 0.3.0
File Size Uploaded Provenance Actions
wells_agent-0.3.0.tar.gz 2.0 MB With provenance Details for wells_agent-0.3.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for wells-agent 0.3.0
File Interpreter ABI Platform Actions
wells_agent-0.3.0-py3-none-any.whl Python 3 none any Details for wells_agent-0.3.0-py3-none-any.whl

Total release size: 2.4 MB

Release files / wells_agent-0.3.0.tar.gz

Download URL wells_agent-0.3.0.tar.gz
Size 2.0 MB
Tags Source
SHA-256 checksum
How to use checksums
5a3256f1fbcb3f0199e20a4c74b3f0eae8b954f957a56758e28ba7cb5092a1ee
BLAKE2b-256 checksum
How to use checksums
33e6e596a6f94055c352f6fcef49d4854c204b5f5d12a31003056a022da9bce4
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Release files / wells_agent-0.3.0-py3-none-any.whl

Download URL wells_agent-0.3.0-py3-none-any.whl
Size 454.1 kB
Tags Python 3
SHA-256 checksum
How to use checksums
9e22aa91d572c307926a2a47125d5f0ec26270305c0777539fe9217ea7230c7f
BLAKE2b-256 checksum
How to use checksums
56fe8b1ab4ad4c0557e469c4486adb36c2cf1fb833bcc035092f3e2ce0bdfa34
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

Security for wells-agent 0.3.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for wells_agent-0.3.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 20, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page