speccoder

speccoder documentation

Run Spec Kit features and OpenSpec changes with a coding agent that has to prove its work: setup, running, evidence, approvals, security and reference.

speccoder is a coding agent for GitHub Spec Kit features and OpenSpec changes, on the command line, in a browser or desktop window and in editors. Kiro specs are recognised and refused. You write the spec, or let the planning skills draft it; speccoder implements it task by task, and evidence, not the model, decides when a task is done.

The idea

  1. A separate model call turns the acceptance examples in your spec into tests that must fail on the current code.
  2. The implementing model works in an isolated git worktree; every tool call is checked before it runs.
  3. speccoder runs your checks and the acceptance tests itself and audits the diff.
  4. A task is ticked and committed only when its tests went from red to green, nothing regressed and no test was weakened. Anything else is saved and stopped for you.

Core concepts

  • The spec is the judge. spec.md says what is wanted, plan.md how, tasks.md in which steps. The implementing model may not edit them.
  • The worktree. Work happens on the branch speccoder/<feature> in a worktree under speccoder’s state directory (in-place runs are the exception). You merge the branch.
  • Committed files only. Commit speccoder.toml and your spec files before a run.
  • Evidence, not claims. The model’s report is shown to you and ignored for the verdict.
  • Everything is recorded. Model and tool calls are journaled; passed tasks are commits with trailers; other attempts are kept under refs/speccoder/attempts/….
  • A person decides what is uncertain: calls outside the policy, suspicious changes, gaps no test can demonstrate, tasks that contradict their spec.

Where to start

Install it, then follow the quickstart. For the guarantees, read how it works and security.

StartInstallationInstall speccoder with Homebrew, the installer or Cargo, verify what you downloaded, and what it needs: git, a Spec Kit or OpenSpec project, a model and your project's toolchain.StartQuickstartFrom a git repository to a verified branch: a Spec Kit project, speccoder's checks, a spec, a run, the evidence, a pull request.StartHow it worksHow speccoder decides a task: readiness, a baseline, spec-derived acceptance tests, a governed attempt, independent verification, and a recorded outcome.UsePlanning with Spec KitWrite the spec, plan and tasks with Spec Kit's own skills run by speccoder, honour Spec Kit extension hooks, and run speccoder as a step of a Spec Kit workflow.UseOpenSpec projectsRun an OpenSpec change task by task under the same judge: scenarios become failing tests, ticks need evidence, broken deltas are caught before any model call, and archiving stays yours.UseRunning a featureRun tasks one by one or all at once, in parallel worktrees or as best-of-n samples; read outcomes, act on a task, converge on the spec, and watch progress and cost.UseBug fixesspeccoder bug: a bug in your words, reproduced by a test that fails on the untouched code by an assertion, confirmed by you once, then fixed and judged — with the fix undone rejected.UseThe web interfacespeccoder ui: the feature, its evidence and the next step in a browser tab or a desktop window, served from your machine with nothing fetched from the network.UseReading the evidenceWhat each task state means, where the evidence lives in git, how the diff audit, acceptance strength, mutation testing and the gaming monitor work, and how to inspect any attempt.UseApprovals and controlsDecide calls inline, in an editor or later; what a decision covers and who made it; the asking budget; allow lists; frozen tests; and accepting, skipping and nudging tasks.UseIntegrationsUse speccoder from Zed and JetBrains over the Agent Client Protocol, give it MCP tools, let Copilot, OpenCode, Claude Code, Codex or Gemini CLI make the attempts, run it in CI, and as a Spec Kit workflow step.UseGitHubStart a feature from an issue, see its pull request beside the evidence, and open or update the draft — through GitHub's API, as you, with nothing else to install.TrustSecurity and the sandboxspeccoder's security model: an isolated worktree, an OS sandbox on macOS and Linux, a policy that classifies every call, secret scrubbing, provenance labels — and what it does not protect against.TrustAttestationsThe signed in-toto statements every tick leaves in git, how anyone checks them with speccoder or with ssh-keygen, gpg and cosign, and what a signature does and does not prove.TrustProof in pull requestsspeccoder attest verify --branch checks every ticked task of a branch against its signed evidence, with the maintainer's trust: no model key, no network, nothing from the pull request executed. The speccoder / evidence check, the evidence tour and the badge.TrustThe task-verification predicatehttps://speccoder.dev/task-verification/v0 as an open specification: what speccoder signs about a ticked task, every field, its JSON Schema, the bundle it travels in, and the rules a verifier applies.TrustRecovery and replayWhat happens when speccoder is interrupted, how a killed attempt resumes without repeating work, and how any recorded run replays offline without a model.TrustEvaluation and benchmarksMeasure speccoder on Spec Kit cases with hidden oracles, impossible tasks and bugs, compare models and external agents, and import SWE-bench-format benchmarks.ReferenceConfigurationEvery section and key of speccoder.toml: checks, model, budget, commands, tests, acceptance, sandbox, mutation, monitor, executor, MCP servers and more.ReferenceCLI referenceEvery speccoder command and its options, the global flags, the JSON output contract and the exit codes.ReferenceCodesEvery code speccoder prints with an error, a stop or a warning: what it means, why it happens and how to fix it.ReferenceTroubleshootingCommon speccoder errors and what they mean: uncommitted files, missing keys, commands that keep asking, sandbox network errors, stuck runs and exhausted provider accounts.