speccoder

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

1. 🟢 Ready — its dependencies in tasks.md are ticked.
2. 📏 Baseline — your checks run on the untouched worktree, so existing failures are not blamed on the change.
3. 🔴 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.
4. 🛠️ Attempt — the model works in the worktree; every call is classified before it runs.
5. ⚖️ 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.
6. 🏁 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.