See it run: the 48-second tour · a real pull request with its evidence · speccoder sample (no key needed)
💡 Why
Coding agents are good at writing code and too good at declaring victory. speccoder separates the two: a model proposes, and code decides.
- 🧪 Evidence decides. The spec's acceptance examples become one oracle per story; a task is verified by the scenarios it turns from red to green; your checks must not regress; the diff is audited for weakened tests; and plausible wrong versions of the change must fail the tests (the acceptance strength on every tick).
- 🔒 Isolated and sandboxed. Work happens on
speccoder/<feature> in a worktree of its own. Every command runs in an OS sandbox (procage: Seatbelt on macOS, Landlock and seccomp on Linux): writes only to the worktree (your package caches stay read-only), no credentials, no network beyond loopback unless you allow it.
- 🚦 Every call governed. Each tool call is allowed, sent to you, or denied before it runs; a command the sandbox confines runs without asking and is listed in the evidence. An approval covers exactly what you saw — that file, that command, that tool — and ends with the run. Every decision records who made it.
- 💾 Durable and replayable. Every model and tool call is journaled. A killed run resumes without repeating finished calls; a recorded run replays offline.
- 🧾 Proof a maintainer can check. Every tick leaves signed in-toto statements in git.
speccoder attest verify --branch (no model, no network) checks each [X] against them, and its GitHub Action posts the result as the speccoder / evidence check (proof in pull requests).
- 🤖 Your model, or your agent. Anthropic, OpenAI, Amazon Bedrock, any OpenAI-compatible server (Ollama, vLLM, …), or an agent — GitHub Copilot, OpenCode, Claude Code, Codex, Gemini CLI — making the attempts over ACP, every call it routes through speccoder decided by it (its own tools run as you).
🚀 Quickstart
You need git, a Spec Kit project (Spec Kit 0.13 to 1.2) or an OpenSpec project (1.0 or newer), and a model. No project yet: speccoder new md2csv --idea "a CLI that turns Markdown tables into CSV" makes one with the stack's and the spec tool's own commands, shown before they run (or New Project in speccoder ui); speccoder sample replays a recorded run, no key needed.
brew install hupe1980/tap/speccoder
# or: curl -LsSf https://github.com/hupe1980/speccoder/releases/latest/download/speccoder-installer.sh | sh
# or: cargo binstall speccoder (the release archive, no build)
# or: cargo install speccoder --locked
cd my-project
export ANTHROPIC_API_KEY=… # or OPENAI_API_KEY, or Bedrock's AWS credentials — read from the environment only
speccoder init # detects your checks, runs them, offers to commit speccoder.toml
speccoder run # works through the feature's tasks
speccoder do "make the login button blue" # a small change, judged like any other
speccoder bug "saving an empty title crashes" --expected "an empty title is refused"
# reproduced first, confirmed by you, fixed on evidence
speccoder review tests US1 --write # the tests the run will use, red now, before any code
speccoder review approve --run ask # approve the spec, freeze those tests, start the run
speccoder inbox # what waits for your decision
speccoder report # every task and the evidence behind its tick
git merge speccoder/001-my-feature # after reviewing the branch
A run at the terminal (--plain; at a terminal it is a live dashboard):
▶ T002 Collapse every run of other characters into one `-` in src/lib.rs (001-url-slugs)
✓ baseline
✓ red assertion
· attempt 1/2
∴ A single pass that remembers the last character pushed collapses every run.
“Every run of other characters should become a single dash, so I'll track the last character pushed.”
turn 1 read_file src/lib.rs allow
turn 2 write_file src/lib.rs allow
turn 3 run_command cargo test allow
✓ attempt 1/2
✓ verify
✓ audit
✓ commit 4be81c2
✓ T002 verified · 42.5k in / 2170 out · 3s — verdict: verified
Then, as you need them:
- 👀 Watch and decide. At a terminal,
run is a live dashboard that asks approvals with one key; the app shows the same work. The model's reasoning and words appear beside its calls — its account, never evidence.
- ⚙️ Automate. Every command takes
--json or --events, both with published schemas; every failure names a code and the command that fixes it.
- 🐙 Work from GitHub.
speccoder auth login once; speccoder issue start 42 specifies a feature from an issue, speccoder pr opens a draft whose description is the evidence. No gh needed.
- 💬 Ask, explore.
speccoder ask "why is T004 blocked?" (⌘L in the app) answers from what it read, each source checked against the reads, and changes nothing; speccoder spec explore "…" weighs approaches before there is a spec and starts one from the brief you chose.
- 📝 Plan with your spec tool.
speccoder spec specify "…" --through tasks runs Spec Kit's own skills in order — specify, then plan and tasks once you approved the spec — stopping for open questions and your review (OpenSpec: propose).
📸 The app
speccoder ui (or ui --window) shows the project on your machine, local only. What waits for you comes first; everything else is one click away.
⚖️ How a task is decided
- 🟢 Ready — its dependencies in
tasks.md are ticked.
- 📏 Baseline — your checks run on the untouched worktree, so existing failures are not blamed on the change.
- 🔴 Red — before a story's first code task, a separate model call with no tools writes the story's acceptance tests from the spec, through the product, and commits them: its oracle. The implementer cannot change them.
- 🛠️ Attempt — the model works in the worktree; every call is classified before it runs.
- ⚖️ Judgement —
verified when the task turns scenarios of its story red → green and nothing regresses; regression_only (with the reason) when it turns none and breaks none; failed otherwise. The story's last task must leave every scenario green. A test file the runner never collected fails the verdict. A verified task's tests then meet wrong variants of the change: how many they reject is its acceptance strength.
- 🏁 Outcome — a verified task is ticked and committed by speccoder. A failed one is retried once with the verifier's facts. Anything else is saved under
refs/speccoder/attempts/…, undone, and handed to a person.
🐞 A bug (speccoder bug) must first be reproduced: one test per expected behaviour that fails by an assertion, confirmed by you. The fix is verified only if undoing it makes a reproduction fail again; a bug that cannot be reproduced comes back to you (bug fixes).
🔄 Change the spec later and the ticks that cite a changed requirement say they were proven against the earlier wording; speccoder run --converge checks the code against the spec as it is now.
⚠️ verified does not mean correct, complete or safe. It means the evidence held. Review the branch like any contribution.
🚧 Status
Early (0.x): it works end to end on small projects with OpenAI, Anthropic and local models. Your checks run code the model wrote — read the security model and SECURITY.md before pointing it at anything important.
🧑💻 Development
| Crate | Role |
|---|
speccoder-core | Pure domain types: no IO, no async |
speccoder-speckit | Reads Spec Kit projects |
speccoder-openspec | Reads OpenSpec projects |
speccoder-runtime | Everything that executes: checks, tools, sandbox, git, the attestation checks, the embedded agentplane runtime |
speccoder-web | The web interface's host: the embedded UI (Svelte, in ui/) and its API, on 127.0.0.1 |
speccoder | The CLI (and the desktop window, feature app) |
- ✅
just ci runs every gate CI runs: formatting, clippy, tests, cargo-deny, layering, docs, a package dry run, the cold-start budget and the release scripts' tests. It needs just, cargo-nextest and cargo-deny; the toolchain is pinned in rust-toolchain.toml.
- 🎨
just ui checks, tests and rebuilds the web interface into its committed bundle (needs Node).
- 🌐
just site serves the documentation site (needs Zola).
- 🎯
evals/ holds spec projects with hidden oracles and impossible tasks that measure whether completions are really correct.
📜 License
Licensed under either of Apache License, Version 2.0 or MIT license at your option.
