Voss

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.

$voss do "plan the login flow"
Install

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.

~/my-api - voss do
$ 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.

observe
readsauto
writesdenied
shelldenied

Read-only and never prompts. Network tools are denied too.

plan
readsauto
writesdenied
shelldenied

Inspect a repo without touching it.

edit
readsauto
writesscoped
shelldenied

Default for voss edit. Scope expansions require approval.

auto
readsauto
writesauto
shellauto

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