Skip to main content

​
User config

Harness config lives under the user’s config directory:
Use:

​
[instructions]

Controls how AGENTS.md and CLAUDE.md are loaded into every native run (see voss instructions show).
Files load in this order: global (opt-in), project root AGENTS.md then CLAUDE.md, then each directory down to the target. A CLAUDE.md that only contains @AGENTS.md collapses into the file it imports. The bundle hash is recorded on every session and run.

​
[billing]

Overrides the billing kind of an auth source. Automatic Observe investigations use call, token, and time limits for subscription sources and reserve dollars for metered ones.

​
[judgments]

Model and limits for opt-in Jev judgments. Defaults are 4 calls and $0.01 per turn.
Judgments are switched on per project in .voss/config.yml, not here. See Config and auth.

​
MCP and skills

Voss imports MCP servers from Claude and Codex config. ~/.config/voss/mcp.yml and project .voss/mcp.yml override imported entries. Skills come from user and project .claude/skills, .codex/skills, and .agents/skills folders; Voss’s user skills folder and project .voss/skills take precedence.

​
Project state

Durable project state is split between human-readable VOSS.md and machine-managed .voss/ directories:
VOSS.md is injected into harness context at session start. Machine fences inside it let Voss update architecture notes without overwriting surrounding human prose. principles.yml and team.voss drive the orchestration layer: principles.yml extends or overrides the six default principles, and team.voss declares the role roster validated by voss team check.

​
Cache state

Rebuildable state belongs under .voss-cache/:
You should be able to delete cache state and rebuild it. The code/ directory holds the derived code recall index used by voss recall and the code_recall tool; it is not the curated project memory store.

​
Session state

Current project sessions live under .voss/sessions/. Legacy sessions in the old user-state directory are read-only via voss sessions --all. A team run also persists its session tree here, one file per agent node, plus per-card review sidecars:
Node and review files are written with 0o600 permissions. token-savings.jsonl contains estimated counts only. It does not store prompt text, tool arguments, or tool output.
Do not commit secrets to VOSS.md, .voss/, or .voss-cache/. Voss avoids storing provider credentials, but prompt text and project notes are still local files.