Documentation

Quickstart

Six steps from setup to a reviewed task. Any git repo, macOS or Linux.

What happens to a task

From the moment you queue it to the moment it’s yours to merge:

1. Queued

   Submitted to selvaged, the daemon that schedules work across models. Your terminal is free the second the command returns.

2. Isolated

   A selvage/<task-id> worktree and branch exist before implementation — a failed run is still inspectable. Your working tree is never touched.

3. Implemented

   An adapter drives the configured model — Claude, Kiro, or Codex — inside your repo, against your code and its conventions.

4. Verified

   The checks from .selvage/config.yaml run from the orchestrator, not the agent. Go tests run with -count=1, so a green run is fresh execution, not a cached replay.

5. Reviewed

   A separate session — never the implementer — reads the diff and files findings. Findings go back to the implementer for revision.

6. Reported

   Diff, build, tests, review, approval state — all on the evidence chain. selvage report <task> reads the ledger.

7. Gated by you

   selvage approve publishes per your config — or the branch simply stays local. There is no auto-push path.

Commands

Grouped the way the CLI groups itself. selvage with no arguments prints this same map; global flag --socket PATH (or SELVAGE_SOCKET) points at a non-default daemon.

Adapters — the CLIs it drives

Selvage does not call model APIs. It drives coding CLIs you have already installed and authenticated, one process per role, so your existing subscription and auth are the ones being used. selvage init detects what is on your PATH; selvage adapters list shows what the current config resolves to, and selvage adapters doctor checks each one is runnable and authenticated.

OpenCode

OpenCode is a useful adapter when you want a model that is not behind one of the first-party CLIs — a local model, or a hosted one such as Cloudflare Workers AI — without Selvage needing its own provider integration.

1. Authenticate a provider inside OpenCode first. This is the step people miss: opencode --version succeeding only proves the binary runs. Selvage checks opencode providers list and refuses setup unless at least one provider is authenticated, because an unauthenticated OpenCode fails at the first lease instead of at setup.

2. Add the adapter. Interactive, which reads the model list from opencode models for you:

3. Or write it directly in .selvage/config.yaml. Model ids are the fully qualified ones OpenCode prints, provider prefix included:

Three details matter. --pure keeps the run non-interactive and free of your local OpenCode session state. {model} is substituted from the model field, so the two never drift apart. And --completion commit tells Selvage this role finishes by committing, which is what an implementer must do — a reviewer omits it.

Then selvage trust to approve the changed config, and selvage start, which validates every adapter with a live prompt before accepting work. A model that cannot answer a one-line prompt is caught there rather than three minutes into a task.

What you get back is provider-dependent. Cost and token reporting is only as good as what the CLI prints. Claude emits machine-readable totals; Kiro reports credits; OpenCode's footer varies by provider, and Selvage records what is reported and marks the rest unavailable rather than inferring numbers. selvage usage shows the provenance for each figure, so an A/B measurement can tell a real zero from an unreported one.

Independence still applies: the reviewer must differ from every implementer that touched a task by node, profile, and provider, subject to minimum_independence. Running OpenCode as the implementer and Claude or Kiro as the reviewer satisfies it; the same OpenCode model on both sides does not.

Configuration

.selvage/config.yaml is created by selvage init: which adapters to drive, and which checks gate the work. Checks must defeat caches — the agent runs tests during implementation, so a verifier replaying cached results is just re-reading the agent’s own run:

The config is untrusted input: selvage trust approves its digest, and a changed config re-arms the prompt. Runtime state lives in XDG, never in the repo.

Local & hosted

Two ways to run it, one gate in both.

MCP — connect your agent tools

One stdio server; the agent terminal you already use submits work, reads evidence, and files review verdicts inside the chat it’s in. The project must be trusted first:

Claude Code — .mcp.json:

Codex and OpenCode take the same command in ~/.codex/config.toml / opencode.json — snippets on GitHub.

Guarantees

The invariants are architectural, not configurable — they survive every integration request and every “can we just…” conversation: