SpecBuddy
Run your OpenSpec workflow from VS Code —
step-by-step agent execution with a review gate, a real diff and a rollback on every step.
OpenSpec is spec-driven development where every piece of work is a change: a directory
under openspec/changes/<id>/ holding a proposal.md, a tasks.md checklist, an
optional design.md and spec deltas. SpecBuddy is the editor half of that workflow. It
makes changes executable: your coding agent works through tasks.md one section at a
time, and each step stops for your review before the next one starts. You stay in the
editor; the agent runs in a terminal you can watch and take over.
SpecBuddy drives the agent CLI you already use — Claude Code, Codex,
OpenCode, or any agent that speaks ACP (Agent Client Protocol). It never ships
or replaces a model: it orchestrates the CLI on your PATH, through the same /opsx:*
commands the OpenSpec skills expect on the command line.
How it works
- Propose a change. Run SpecBuddy: New Spec and pick OpenSpec Change:
describe what you want, hit Generate, and the agent turns it into a change under
openspec/changes/.
- The change appears in the Specs view. So does every change already under
openspec/changes/ — no configuration needed. Opening one takes you to tasks.md
first (that's where the work is), falling back to the proposal or design.
- Run a step. Each
## section of tasks.md is a step. SpecBuddy snapshots the
tree, launches the agent with the step's prompt, and flips the step to Review
when it finishes.
- Review the diff. Accept it, Refine it with feedback, or Rollback the step
and try again. Inline review comments on any file in the workspace fold straight into
the refine prompt.
- Repeat, or hit Run all steps and let it work through the checklist.
- Sync and archive. When the change is implemented, fold its spec deltas into
openspec/specs/ and move it to the archive — right from the Cockpit, as tracked
agent sessions.
Every step's state lives on its heading — a coloured chip (PENDING, RUNNING,
REVIEW, INTERRUPTED, DONE, FAILED, MERGED) — and in the Cockpit panel, with
CodeLens actions above the document and each step.
Features
- Step-by-step execution with a review gate. No unattended multi-hour run you have
to untangle afterwards — each step stops for you.
- Rollback. The last completed step can be undone from the refs its run recorded,
including files it created. Interrupted runs take the same route.
- Refine. Re-run any completed step with corrective feedback, optionally rolling the
code back first.
- Inline review comments (VS Code Comments API) on any workspace file. Anchors are
maintained across edits, so a comment always points at the text it is about now.
- Interrupted-run recovery. If the agent exits, the terminal dies, or you press
Stop, the step says so and offers Continue, Finish Step, Rollback and
Refine rather than pretending nothing happened.
- Parallel changes in git worktrees, so two changes can run at once without
colliding.
- Sync and archive from the Cockpit — the full change lifecycle without touching a
terminal yourself, each operation logged and attributed to its change.
- Agent-agnostic. Claude Code, Codex, OpenCode, or any ACP adapter; auto-detected on
first launch, pinnable in settings.
Getting started
Install the extension.
Make sure your agent CLI is on PATH (claude, codex, opencode, or an ACP
adapter). SpecBuddy auto-detects on first launch; you can pin one in
specBuddy.agent.
Install the OpenSpec CLI, if you haven't:
npm install -g @fission-ai/openspec@latest
then openspec init in the project root (SpecBuddy will offer this itself).
Run SpecBuddy: New Spec and pick OpenSpec Change — or just open a project
that already has changes under openspec/changes/; they appear in the Specs view
immediately.
Run the first step, review the diff, keep going. Sync and archive from the
Cockpit when the change is done.
For ACP adapters, SpecBuddy: Configure ACP Agent walks you through picking a preset,
filling in the command, and verifying that the adapter actually answers.
Requirements
- VS Code 1.90 or later
- Git (SpecBuddy uses snapshots and worktrees for diffs and rollback)
- An agent CLI on
PATH
- The
openspec CLI
Settings
| Setting |
Default |
What it does |
specBuddy.agent |
(auto-detect) |
Which agent CLI to drive: claude, codex, opencode, acp |
specBuddy.acp.preset |
— |
Fills in the ACP command fields from a known adapter |
specBuddy.acp.command |
— |
The ACP adapter command to launch |
specBuddy.acp.resumeCommand |
— |
Terminal command to resume an ACP session ({sessionId} placeholder) |
specBuddy.autoMode |
false |
Always launch the agent in its CLI's auto mode — it edits files and runs shell commands without asking you to approve each one |
specBuddy.parallelSpecExecution |
true |
Allow running multiple changes concurrently in dedicated git worktrees |
specBuddy.submitCommentsAutomatically |
false |
A refine folds every pending inline comment into its prompt instead of asking which ones to include |
specBuddy.editor.stepMarkers |
chip |
chip draws the state chip on the heading; off hands the state back to the CodeLens row |
specBuddy.analyticsEnabled |
true |
Send anonymous usage analytics and crash reports |
Telemetry
SpecBuddy sends anonymous usage analytics — which action ran, the extension, editor and
OS version, the configured agent backend, and a slug of the spec file's name — and crash
reports carrying the error, its stack trace and those same environment facts. Both are
tied to a random UUID generated on first use. Your code, spec and prompt text, agent
output, diffs, directory paths and repository names are never sent.
Either specBuddy.analyticsEnabled → false or VS Code's own telemetry.telemetryLevel
→ off silences both, effective immediately. SpecBuddy: Report a Problem still sends
the description you type — invoking it is the consent for that one report. Data is
processed in the EU.
License
Proprietary, free of charge for personal and commercial use. The full terms ship with the
extension as LICENSE.md and are shown on the Marketplace listing's License tab.
