VossA language for AI workflows.

voss harness

Ship AI features
without becoming an SRE.

The Voss harness is an agent loop that lives in your terminal. Drop into any repo, give it a goal, watch it read, edit, run, and verify code. Built for AI-first developers who already pay for Claude Pro or ChatGPT — and want their subscription to do the work.

$voss do "ship the login flow"
Install →

01

Use the Claude or ChatGPT subscription you already have. No second API bill.

02

Sandboxed by default. cwd jail, shell allowlist, no network surprises.

03

Built on the same runtime as Voss the language. Confidence-gated planning, token budgets, episodic memory — all first-class.

A turn looks like this

Plan, edit, run, verify.

Each turn is a confidence-gated plan, gated tool calls, and a verification step. You see what it's going to do before it does it.

~/voss-app — voss do
$ voss do "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=edit)
[write]  tests/test_health.py +12     ✓ allow (mode=edit)
[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

OAuth into Claude Code or Codex CLI. The harness reuses those tokens — your Pro/Max plan covers the bill, no API key required.

Permission modes that match how you work

plan (read-only), edit (read + scoped writes), or auto (allowlisted everything). Decisions persist per-project, so you grant once and ship.

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. Everything jailed to your cwd.

Confidence-gated planning

Each turn produces a `ProbableValue<Plan>`. Low-confidence plans get rerolled, not executed. Same primitive Voss programs use — eat your own dog food.

Sessions you can resume

Every chat persists to ~/.local/state/voss/sessions. Restart, switch machines, replay a transcript — the episodic memory comes with it.

Headless or interactive

`voss do "ship the login flow"` for one-shots. `voss chat` for the REPL. Same agent loop either way — script it in CI or babysit it locally.

Permissions

Three modes. Persistent decisions.

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

plan
readsauto
writesprompt
shellprompt

Inspect a repo without touching it.

edit
readsauto
writesscoped
shellprompt

Default. Reads + writes inside cwd, ask before shell.

auto
readsauto
writesauto
shellauto

Allowlisted everything. Destructive patterns still prompt.

Auth

Three ways in. Subscription-first.

If you already pay Anthropic or OpenAI for a coding tool, you don't need to pay them twice.

Claude Code OAuth

Reuses your Claude Pro / Max subscription via the Claude Code login. macOS Keychain or ~/.claude/.credentials.json.

claude login    # then: voss --auth=claude do ...

Codex / ChatGPT OAuth

Reuses your ChatGPT subscription via the Codex CLI auth file. Tokens auto-refresh.

codex login     # then: voss --auth=codex do ...

Plain API key

Drop ANTHROPIC_API_KEY or OPENAI_API_KEY in the env. Useful for CI.

export ANTHROPIC_API_KEY=sk-ant-...

The verbs you'll actually use.

  • $ voss do "fix the failing tests in tests/auth/"One-shot agent task
  • $ voss chatInteractive REPL with persistent session
  • $ voss chat --resume <id>Pick up where you left off
  • $ voss --auth=claude do ...Force Claude Code OAuth
  • $ voss --auth=codex do ...Force Codex (ChatGPT) OAuth
  • $ voss doctorVerify credentials, tools, sandbox

Install

Try it in a repo.

Clone Voss, install in editable mode, log into your Claude or Codex account, and run voss doctor to verify.

git clone https://github.com/bm9797/Voss
cd voss
pip install -e ".[dev]"
voss doctor
Read the docsAbout the language