Voss

voss harness

An agent loop that
stays inside the lines.

The Voss harness is an agent loop that lives in your terminal. Drop into 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 use pip when you want the Python package directly.

Modes

Modes are explicit: plan for read-only work, edit for scoped changes, auto for higher-trust local automation.

Memory

Project memory and code recall keep useful repo context available beyond one chat.

A turn looks like this

Plan, edit, run, verify.

Each turn is a confidence-gated plan, permission-checked tool calls, and a validation loop. In plan mode, mutating tools are denied before they run.

~/voss-app - 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

Use Claude Code or Codex CLI auth when available, or fall back to ANTHROPIC_API_KEY / OPENAI_API_KEY for CI and reliable provider access.

Permission modes that match how you work

plan is read-only, edit supports scoped writes, and auto allows broader local automation through the lower-level safeguards.

Real tools, not toys

fs_read, fs_glob, fs_grep, fs_write, fs_edit, shell_run with an allowlist, git_status, git_diff, and voss_check. Core file tools stay project-scoped and mutating actions pass through explicit permission metadata.

Confidence-gated planning

Each turn produces a `ProbableValue<Plan>`. Low-confidence plans get rerolled, not executed. It is the same primitive Voss programs use.

Sessions you can resume

Sessions are stored per project under .voss/sessions. List them, resume by id, and keep prior runs tied to the repo.

Code-aware recall

`voss recall` and the `code_recall` tool search code and project memory together, with labeled sources and lexical fallback when vector search is unavailable.

Headless or interactive

`voss do "ship the login flow"` for one-shots. `voss chat` for the REPL. Same agent loop either way, whether scripted or supervised locally.

Permissions

Three modes. Persistent decisions.

Every project gets its own permission record at ~/.config/voss/permissions.json. Grant once, ship.

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

Use the Voss login wizard when you want provider credentials managed outside the shell environment.

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.

  • $ voss do "find the auth flow and name the risky files"Read-only repo task
  • $ voss chatInteractive REPL with persistent session
  • $ 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 sync --checkCheck managed project docs for drift
  • $ voss toolsInspect available harness tools
  • $ voss config --showInspect local harness config
  • $ 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.

npm i -g @vosslang/cli
voss doctor
Read the docsAbout the language