voss harness
An agent loop that
stays inside the lines.
The Voss harness is an agent loop that lives in your terminal. Run `voss` in any repo, give it a goal, and keep reads, edits, shell commands, memory, and resumes inside explicit boundaries.
Install
Install through npm without managing Python yourself, or pip install from GitHub when you manage Python 3.11+ yourself.
Modes
Modes are explicit: observe and plan for read-only work, edit for scoped changes, auto for higher-trust local automation.
Memory
Project memory, code recall, and your AGENTS.md and CLAUDE.md instructions carry repo context across sessions.
A turn looks like this
Plan, edit, run, verify.
Each turn is a plan with its confidence on record, permission-checked tool calls, and a validation loop. In plan and observe modes, mutating tools are denied before they run.
$ voss do --mode=auto "add a /healthz endpoint and a test for it"
[plan] confidence 0.92
1. fs_grep "FastAPI\(" -> app/main.py
2. fs_edit app/main.py -> add @app.get("/healthz")
3. fs_write tests/test_health.py -> pytest case
4. shell_run pytest tests/test_health.py -q
[edit] app/main.py +4 -0 ✓ allow (mode=auto)
[write] tests/test_health.py +12 ✓ allow (mode=auto)
[shell] pytest tests/test_health.py -q
1 passed in 0.18s ✓
done. token spend: 4,128 / budget 8,000, saved as session 0193...Built for AI-first builders.
You're shipping AI inside a product. The harness is the agent that helps you do it, without leaving the terminal, without a second subscription, without surrendering your repo.
Bring your own subscription
Sign in with Claude Code or Codex OAuth, or use ANTHROPIC_API_KEY / OPENAI_API_KEY for CI. `/model` and `/auth` switch model and provider mid-session, and the choice persists.
Permission modes that match how you work
observe and plan are read-only, edit supports scoped writes, and auto allows broader local automation. Project rules in `.voss/permissions.yml` can deny tools outright.
Real tools, not toys
File, code search, symbol lookup, git, shell, and web tools. Core file tools stay project-scoped, shell runs from an allowlist, and network tools need `--allow-net`.
Plans that admit doubt
Each turn plans before it acts. The plan's confidence is recorded as the model's own report, and a plan below 0.60 stops to ask you instead of running.
Sessions you can resume
Sessions are stored per project under .voss/sessions. Resume by id or name with `voss resume` or `/resume`, and the saved transcript replays in the TUI.
Code-aware recall
`voss recall` and the `code_recall` tool search code and project memory together, with labeled sources and lexical fallback. Jev reranking is opt-in.
Your MCP servers and skills
Voss picks up the MCP servers and skills you already configured for Claude Code and Codex. MCP calls still pass Voss's network and permission checks.
Instructions you can inspect
AGENTS.md and CLAUDE.md load into every run within a token budget. `voss instructions show` lists each file, its token count, and its hash.
Headless or interactive
`voss do "ship the login flow"` for one-shots, bare `voss` for the full-screen Go TUI, and `voss serve` for clients. Same agent loop each way.
Permissions
Four modes. Persistent decisions.
Every project gets its own permission record at ~/.config/voss/permissions.json. Grant once, ship.
Read-only and never prompts. Network tools are denied too.
Inspect a repo without touching it.
Default for voss edit. Scope expansions require approval.
Allowlisted everything. Destructive patterns still prompt.
Auth
Three ways in. Subscription-first.
Use local OAuth where it fits, or set provider API keys when you need predictable CI and automation behavior.
Interactive login
Sign in with Claude Code or Codex OAuth, or paste an API key that Voss stores in the OS keychain.
voss login
Environment key
Set a provider API key for CI or machines where interactive login is not the right fit.
export ANTHROPIC_API_KEY=sk-ant-...
Doctor check
Confirm Python, imports, credentials, git, writable directories, and project setup before running work.
voss doctor
The verbs you'll actually use.
- $ vossFull-screen Go terminal client
- $ voss do "find the auth flow and name the risky files"Read-only repo task
- $ voss sessionsList saved project sessions
- $ voss resume <id>Pick up where you left off
- $ voss recall "where is retry backoff handled?"Search code and memory together
- $ voss mcp listShow discovered MCP servers and tools
- $ voss instructions showSee the instructions the agent gets
- $ voss toolsInspect available harness tools
- $ voss doctorVerify credentials, tools, sandbox
Install
Try it in a repo.
Install the npm CLI, log into a provider or set an API key, and run voss doctor to verify. Then run voss to open the TUI.
npm i -g @vosslang/cli voss doctor voss
