The complete SPAVN reference

Overview#

SPAVN is a terminal coding agent: you describe a change, it reads the repo, edits files, runs commands and reports back. It runs as a single native binary with a synchronous TUI — there is no Node, no Electron, no plugin tree, and no daemon.

The design bets

Autonomous harness intelligence (v0.2.0)

At a glance

Install#

Five channels. Pick one; they all install the same binary.

Install script

curl -fsSL https://spavn.dev/install.sh | sh

# custom target directory
SPAVN_INSTALL_DIR=/usr/local/bin sh install.sh

# build from a local binary instead of downloading
SPAVN_LOCAL_BIN=./target/release/spavn sh install.sh

Lands in $HOME/.local/bin/spavn plus the spvn alias, then executes the binary once to prove execve works. Staging uses a fresh inode and an ad-hoc signature so macOS amfid does not kill the result.

Homebrew

brew install tugayoktayokay/tap/spavn
brew upgrade spavn        # later

# Homebrew 6+ trusts third-party taps explicitly:
brew trust tugayoktayokay/tap

The formula lives in tugayoktayokay/homebrew-tap and is generated, never hand-edited: packaging/homebrew/sync-tap.sh <version> <tap-checkout> pulls each .sha256 sidecar and rewrites the URLs.

Cargo

cargo install --git https://github.com/tugayoktayokay/spavn-cli   # tracks main
cargo install spavn                                             # once published

Verify a download

gh release download v0.2.0 --pattern '*aarch64-apple-darwin*'
shasum -a 256 -c ./*.sha256

Quickstart#

spavn                            # interactive TUI in the current directory
spavn "explain the spill module" # one-shot prompt, still interactive
spavn -p "fix the failing test" -q   # headless: print and exit
spavn --resume                   # session picker
spavn --help                     # every flag, path and env var

Flags

First five minutes

1. spavn — the TUI opens with a dock: model, access mode, phase, host, context use.
2. /byok — paste a provider key (stored in ~/.spavn/secrets.env, 0600) or start a local model instead.
3. /model — pick from local → BYOK → catalog → free tier.
4. /access auto — read-only calls run freely, mutations ask.
5. /plan then describe the change; /code when you are ready to write.

Models & routing#

One picker, four sources, resolved in this order: local → BYOK credits → provider catalog → free tier. Zero vendor lock-in: bring your own local GPU server or API key.

Local models

# Ollama ships as a provider group at http://127.0.0.1:11434/v1 — zero config
spavn --model ollama:qwen2.5-coder "refactor the spill module"

# Other OpenAI-compatible servers: point discovery at the /v1 root once
#   LM Studio   http://localhost:1234/v1
#   llama.cpp   http://localhost:8080/v1
export SPAVN_LOCAL_MODELS_URL=http://localhost:8080/v1
export SPAVN_LOCAL_BASE_URL=http://localhost:8080/v1

Your own gateway

"providers": [
  {
    "id": "my-gw",
    "title": "My gateway",
    "base_url": "https://gw.example.test/v1",
    "api_key_env": "MY_GW_KEY",
    "models": [{ "key": "fast", "model_id": "gw-fast-1", "desc": "cheap", "context_window": 32768 }]
  }
]

Set byokCatalog: false to drop the built-in catalog entirely and drive the picker from providers alone.

/bench and /fleet

/bench runs one prompt across every candidate and reports TTFT, tokens/sec and whether the tool-call format actually parsed — JSON, NO TOOL CALL, or a malformed call. /fleet probes every hosts[] entry over ssh -o ConnectTimeout=3 and prints round-trip latency plus the host's uptime line.

Slash commands#

37 entries, all with aliases. /help prints the same set in the TUI; / opens the menu.

Keyboard

Piping into a busy session

busy_input_mode decides what happens when you type during a turn: queue (default) defers to the next turn, steer interrupts and redirects the model mid-flight.

Tools#

Eleven builtins, each a fixed contract in tool_definitions(). Anything else comes from an mcpServers entry.

Points worth knowing

• Oversized output spills, it is not truncated away. bash keeps 8 MiB per stream in ~/.spavn/tool-output/ (newest 40 kept, 0600) and tells the model the path instead of silently dropping bytes.
• read beats bash cat. Range syntax avoids re-reading a whole file and never spawns a shell.
• subagent cannot write. Investigate in parallel, then apply the change yourself.
• web has no built-in endpoint. Search stays off until you point webSearchUrl or webSearchServer at a backend.

MCP servers#

The extension path. There is no builtin desktop-control tool and no hardcoded path to one — the catalog is read from your config, so nothing assumes a vendor or an install location.

{
  "mcpServers": {
    "memory":  { "command": "noospire-memory", "args": ["--stdio"], "readOnly": true },
    "desktop": { "command": "open-computer-use", "args": ["mcp"], "readOnly": false },
    "remote":  { "url": "https://bridge.example.test/mcp", "readOnly": true }
  }
}

// the model reaches any of them through the generic MCP call
{ "op": "mcp", "server": "desktop", "tool": "click", "arguments": { "x": 640, "y": 320 } }

Rules

• Every configured server name is listed in the lsp tool description, so the model finds them without a second prompt.
• Servers not in mcpServers are unreachable.
• readOnly: true declares no side effects; without it, calls pass the mutation gate.
• In PLAN phase a mutating MCP call is refused outright — no prompt, no override.
• Stdio servers get a scrubbed environment: only what env declares survives.
• url selects a streamable-HTTP server instead of a subprocess.

Config#

~/.spavn/config.json. Every key is optional; an absent file is a working default. Both camelCase and snake_case spellings parse.

{
  "default_model": "sonnet",
  "busy_input_mode": "queue",
  "language": "en",
  "byokCatalog": true,
  "updateCheck": true,
  "updateCheckIntervalHours": 24,
  "providers": [],
  "mcpServers": {},
  "hosts": [{ "key": "buildbox", "ssh_target": "deploy@10.0.0.5", "badge": "BB", "sensitive": true }]
}

General

Web / search backends

Local discovery and paths

Remote hosts

read, write, bash, glob and search all accept <host>:/path, so one investigation can span machines.

MCP servers

Environment variables#

Security gates#

Access modes

The six gates, in order

Phases

/plan is a read-only planning mode enforced in code: the model can read, search and think, but write, edit, bash and mutating MCP calls are refused. /code unlocks them. Prompt text cannot talk its way out of the phase.

What is on disk

~/.spavn/                 0700
├── config.json           providers, paths, MCP servers
├── secrets.env           0600 · flagged as secret material by the path policy
├── PROFILE.md            user profile injected into the prompt
├── sessions/             transcripts
├── skills/               on-demand domain instructions
├── tool-output/          spilled tool output, newest 40 kept
└── audit.key             HMAC key for the audit chain

Context & memory#

Four layers, increasing specificity. Everything is a file you can read and edit.

External recall

memory can delegate to your own binaries via memory_recall_bin and memory_remember_bin instead of the local store. The local store is the default, not the only path.

Compaction

/compact rewrites the transcript into a shorter form and keeps going; /recap controls the idle summary line. Context-window usage is shown in the dock as a bar, sourced from the model's declared window.

Architecture#

Modules

src/
├── main.rs           CLI parsing, TUI & --rpc entry point
├── lib.rs            module surface
├── rpc.rs            headless JSON-RPC 2.0 stdio bridge
├── router/           model resolution, catalog, OAuth, SSE stream watchdog
├── turn/             agentic turn loop, Zero-Stop compiler gate, repeat-tool breaker
├── tools/            schema, fuzzy self-heal edit, stale-file guard, live signature map, shell, MCP
├── guard.rs          access, path, shell AST risk and egress enforcement
├── hud/              dock, input, keys, menus, pickers, panels, tool cards
├── slash_commands.rs command dispatch and /help
├── session/          JSONL persistence, budget-relative compactor, fork
├── spavn_engine.rs   audit chain, secret scrubbing, janitor, goals, pins
├── memory.rs         recall / remember bridge & repo map builder
├── skills.rs         skill discovery and injection
├── update.rs         release check and upgrade advice
├── spill.rs          oversized-output spill files
├── markdown.rs       terminal Markdown rendering
├── state.rs          shared signals between TUI and agent
├── http.rs           the only socket code
├── ansi.rs           escape sequences & OSC-52 clipboard
└── config.rs         config loading, defaults, provider catalog (Claude 5.5, etc.)

Invariants

1. Gates are code, never prompt text. Only guard.rs can permit.
2. No implicit peers. The binary talks to the endpoint you configured and to processes you named in mcpServers.
3. One socket layer. All network I/O goes through http.rs, which classifies every host before dialling.

Threads

No async runtime. The render loop is synchronous; threads exist only where a child process would otherwise block: the pipe drainer that caps large output, the background-job waiter, bounded subagent fan-out, and the one-shot update check. A long tool call still blocks the render loop; interruption is by signal.

The request lifecycle

1. Prompt is assembled from AGENTS.md, profile, skills and pins.
2. Router resolves model key → endpoint.
3. Egress is classified and secrets are scrubbed before the body leaves.
4. Tokens stream into the transcript; tool calls arrive as structured JSON.
5. Each tool call walks the six gates; a mutation may prompt.
6. Result returns to the model; the dock and tool cards update.

Updates#

There is no auto-updater and no daemon. The binary compares its own version against the newest published tag and tells you the command to run.

• Background check — once per updateCheckIntervalHours (default 24), a single GET. Nothing is downloaded and nothing is executed.
• Banner notice — when a newer release is known, the welcome output carries a box with both versions and the upgrade command.
• Mid-session notice — if the check finishes later, the notice is parked and printed once the prompt is idle. It is never shown twice.
• /update — check on demand and print the exact command.

/update

# the command it chooses depends on how this binary was installed
#   brew  →  brew upgrade spavn
#   cargo →  cargo install spavn --locked --force
#   curl  →  curl -fsSL https://spavn.dev/install.sh | sh

Turning it off

// ~/.spavn/config.json
{ "updateCheck": false }

# or per invocation
SPAVN_UPDATE_CHECK=0 spavn

/update says the check is disabled rather than falsely reporting "up to date".

Release channels

One tag drives everything: the GitHub archives with SHA-256 sidecars, the Homebrew formula (generated by packaging/homebrew/sync-tap.sh) and the crates.io publish. Nothing is rebuilt per channel.

Troubleshooting#

Health checks

spavn --version          # version, OS, arch
spavn --help             # flags, paths, env vars
/audit                   # what actually ran, HMAC-chained
/fleet                   # host reachability and latency
/local                   # local model discovery

FAQ#

Contributing#

Build and gate

cargo build --release
cargo fmt --all --check
cargo clippy --all-targets
cargo test

# the ignored test needs a live MCP server from your own config
cargo test -- --ignored

Rules that keep the project intact

• No new runtime dependency without a strong reason, and no async runtime.
• Every gate is enforced in code, never only in the prompt.
• New behaviour needs a test that fails without it.
• User-facing changes update README.md and CHANGELOG.md.

Release order

cargo fmt --all --check && cargo clippy --all-targets && cargo test
cargo publish --dry-run

git commit -am "chore(release): v0.1.1" && git tag v0.1.1 && git push --tags
# CI builds the matrix and attaches SHA-256 sidecars

cargo publish                                                  # needs a token
sh packaging/homebrew/sync-tap.sh 0.1.1 /path/to/homebrew-tap   # or let CI do it