Wells
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 — vs Aider · vs OpenHands · vs OpenCode · vs Claude Code · vs Cursor · vs the 2026 harnesses (Codex / Kimi Code / Grok Build / DSH)
- What it does — the planner→coder→tester→reviewer graph
- The TUI — commands, keyboard shortcuts, the info panel
- Provider profiles — model-agnostic setup
- Quick start — cloning, embedding, global install, manual setup
- CLI
- Scheduled runs — unattended recurring runs (Task Scheduler / cron)
- Notifications & daily spend cap — desktop/webhook alerts, cross-run budget
- Safety model — auto / approve / dryrun / plan / sandbox (+ auto-upgrade)
- Operating rules — deterministic enforcement + permission allowlists
- Repository index (
wells-index) - Behavioral principles (
AGENT.md) - Global user memory — standing preferences across every project
- Durable project memory — BigBrain — transaction-log lessons, curated compile,
memory_searchrecall - Agent capabilities
- Skills (incl. cross-harness packs) · CodeAct · Code Mode · Browser
- Background agents · Subagent personas · Model-driven todo list
- Self-improvement — Reflexion (failure critiques) · Auto-skill authoring (proven-run → skill proposals) · SEACS bench + evolve (mine a task corpus, gate AGENT.md mutations against it)
- MCP — server and client
- ACP — drive Wells from your editor (
wells-acp, Zed/JetBrains) - Project structure
- Configuration reference
- Token & cost optimization
- Tests & CI
- Semantic code retrieval
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_researchfan-out that runs 2–4 read-only subagents concurrently), then writes a concrete plan with exact files and line numbers — and labels itSIMPLEorCOMPLEX. - 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.mdproject memory and optionally creates awells/<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 fromMODEL_PROFILES; if it was the active/cheap/ vision slot, that slot is cleared (cheap/vision) or reassigned (active) automaticallyv— dedicated vision-profile flow: pointMODEL_PROFILE_VISIONat an existing profile, create a new one on the spot (suggests a free OpenRouter vision model when the name isopenrouter), 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 and wells is on your PATH from any directory. From PyPI
(recommended — versioned, and uvx wells-agent works with no install at all):
uv tool install wells-agent # or: pipx install wells-agent
Or straight from the repo (tracks master, or your own fork):
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"
(wells-index, the native Rust code index, ships as a core dependency —
abi3 wheels cover every Python 3.12+ on all four platforms.)
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,osascripton macOS,notify-sendon Linux. No extra package on any platform. - Webhook —
WELLS_NOTIFY_WEBHOOK_URLgets 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:
- Tool-boundary enforcement (
.wells/rules.yaml, merged over~/.wells/rules.yaml): every tool call is checked before execution.blockrefuses outright,confirmpauses for y/N,warninjects the rule into the model's next observation,allowpre-clearsapprovemode's normal per-action y/N for a matching call (a permission allowlist — "always allowgit status, always ask beforerm" instead of a blanket prompt for every mutating call;auto/dryrun/plan/sandboxare unaffected either way), andliabilityregisters 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⚠ LIABILITYbadge in the status bar, warns on next startup, and keeps the ledger in~/.wells/liabilities.jsonso even a crash can't lose track of a running paid resource. - 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.
- 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.
/doctordetects 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)
WELLS_PRINCIPLESenv var — point at any file path. Use this for organization-wide principles across all projects.AGENT.mdin the workspace root — lets a team customize the rules for one project. Version-controlled with that project.- 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_searchtool (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):
<workspace>/skills/— the conventional location- 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
-
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 === -
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. -
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:
- 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. - Right-panel banner (TUI). A
⚡ N skill proposals — click to reviewbar 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. - Review modal (TUI).
/skills proposals(or the banner click) opensProposalReviewScreen: 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 emitsllm_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 — theprogramtool, with safety gating inside the program.Editor integration via ACP.✅ Shipped —wells-acp.Durable project memory.✅ Shipped — BigBrain transaction-log memory (memory_bridge),memory_searchrecall, Reflexion mirroring.Cross-harness skill compatibility.✅ Shipped —.claude/.agents/.codexskill 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 soevolve gateruns end-to-end. - Sandbox-by-default — flip the
WELLS_SANDBOX_AUTOshipped 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-vecvirtual table inside the existing.wells_index/index.db— no separate vector database. - Repomap re-rank: when embeddings are available,
build_repo_mapblends 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 onpyproject.tomlmeans it only runs once per spec change. - Best-effort: if the install fails (e.g. corporate proxy blocks PyPI),
Wells still starts;
semantic_searchreturns an informative message and the other tools are unaffected. - Opt-out: set
WELLS_NO_EMBEDDINGS=1to 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.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| wells_agent-0.4.0.tar.gz | 2.0 MB | With provenance | Details for wells_agent-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| wells_agent-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for wells_agent-0.4.0-py3-none-any.whl |
Total release size: 2.5 MB
Release files / wells_agent-0.4.0.tar.gz
| Download URL | wells_agent-0.4.0.tar.gz |
|---|---|
| Size | 2.0 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0dc232a559f4ca385bf9b218c4f00310894611f5b668477acd40fd367c4fd4e9
|
|
BLAKE2b-256 checksum How to use checksums |
af0f79018e6877d3f907b4f4351cc182f574d8f076d4ec93321e41c41dd0c354
|
| 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 logRelease files / wells_agent-0.4.0-py3-none-any.whl
| Download URL | wells_agent-0.4.0-py3-none-any.whl |
|---|---|
| Size | 455.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
2cfd54b934213f7eaa8d9c01e7aab340fc77efd0f393babf898396dd97257b55
|
|
BLAKE2b-256 checksum How to use checksums |
0d2600200fae3cde1e851141fd6a27407155f346735501fb68f6fe55eda824e9
|
| 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 logSecurity for wells-agent 0.4.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.
Attestation for wells_agent-0.4.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 logA 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.