SpecWeave CLI
A CLI that keeps the spec, tasks and proof of done in git so Claude, Codex, Grok and Cursor can hand work to each other
- 171 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- The CLI creates and commits files in `.specweave/`, makes auto-commits when enabled and pushes the branch on handoff
- The review command sends the code diff to another model at a third-party provider
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/specweaveDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The CLI creates and commits files in `.specweave/`, makes auto-commits when enabled and pushes the branch on handoff
- The review command sends the code diff to another model at a third-party provider
This is third-party code. Review the repository files before installing.
What it does
SpecWeave installs with `npm install -g specweave`, and `specweave init .` writes an `AGENTS.md` file, a two-line `CLAUDE.md` that imports it, and skills for Claude Code and Codex. Nothing runs in the background. Work goes in increments: one `.specweave/increments/NNNN-slug/` folder with a human-readable `spec.md` and a `ledger.jsonl` that only the CLI appends to. The loop has steps. `/sw:increment` or `specweave create-increment` creates a spec with the problem, scope, acceptance criteria, approach and tasks. Then `task claim` takes a task and `task done T-01 --run "<test>"` refuses to close it while the test fails and stores the evidence in the ledger. `specweave verify` runs tests, lint and build, `specweave review` hands the diff to another model family and `specweave complete` closes the increment on a green check. Handoff takes two words: "hand off" runs `specweave handoff`, releases your task claims and pushes the branch with a snapshot of uncommitted edits, and "pick up" in another tool continues from the same point. Project memory lives in `.specweave/memory/` and travels with the code.
Who it is for. Teams and solo developers who move a task between Claude Code, Codex, Grok and Cursor and want a shared spec and ledger in git.
Good fit when
- One agent starts a task and another finishes it, and you need a shared task list with acceptance criteria
- Closing a task has to be refused when the test command passed to `--run` fails
- Project decisions and agreements should live in `.specweave/memory/` next to the code, not in a chat
- A diff is reviewed by another model family through `specweave review`
- In an existing monorepo you need to register neighbouring projects through `--workspace` without moving files
Not a fit when
- A one-line change: a full increment cycle with tasks and verification is overkill
- You have no Node.js 20.12.0 or newer: the CLI depends on it
- You use a single agent and chat notes: a shared git spec adds nothing
Example request
Create an increment "CSV report export" with specweave create-increment, claim the first task and close it only after a green testLimitations
The CLI needs Node.js 20.12.0 or newer and installs globally through npm. Version 3.0 retired the `brainstorm` and `team` skills, replaced by the decision step in `increment`, the `grill-me` interview and parallel lanes in `do`. Old increments with `tasks.md` keep working. `specweave review` hands the diff to another model family, so code goes to a third-party provider under your key. Increment auto-commit is a separate `git.autoCommitIncrement` setting and is off by default. The optional `sync`, `project` and `jev` skills install when a tracker or setting is detected.
How to disable. Delete the `.specweave/` directory, the references in `CLAUDE.md` and `AGENTS.md` and the `sw-*` skills from `.claude/skills/`. The CLI itself is removed with `npm uninstall -g specweave`.
FAQ
How do I set up SpecWeave for Claude Code?
Run `npm install -g specweave`, then `specweave init .` in the project root. It adds `AGENTS.md`, a short `CLAUDE.md` and skills that answer to `/sw:increment`, `/sw:do` and `/sw:done`.
What do "hand off" and "pick up" mean?
The first runs `specweave handoff`: it releases your task claims, records why you stopped and pushes the branch with a copy of uncommitted edits. The second runs `specweave pickup` in another tool and shows the open increment and next task.
How does SpecWeave decide a task is done?
`specweave task done` with the `--run` flag runs your test and refuses to close the task if it fails. A passing result lands in `ledger.jsonl` as evidence.
How is SpecWeave different from Spec Kit?
Spec Kit installs spec-driven commands into a project. SpecWeave adds an evidence ledger in git, shared memory, handoff between agents and review by another model.
Can I attach existing repositories?
Yes. `specweave --workspace ./planning get ../existing-api --json` registers a neighbouring or nested repository without moving files. The `--dry-run` flag gives a preview.
Discussion
No questions or reviews yet.
Related
CLI toolsFeatherSpec drives spec-driven development in Claude Code and GitHub Copilot: 13 /sdd commands and a Markdown project memory
A skill that runs a long task as a package with verifiable steps and on-disk state, so work resumes in a new session.
The spxa CLI and a skill set for spec-driven development in Claude Code, Codex and Cursor, from a change proposal to the archive
A methodology and CLI for single-spec development: skills install into a project and lead an agent from idea to verified code
GitHub toolkit for spec-driven development: the specify CLI adds agent commands and skills to a project, from principles to implementation
A plugin with three skills for large development work: project analysis, phased tasks tracked as GitHub Issues, parallel agents and code review
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Repository stars | Main difference |
|---|---|---|---|
| SpecWeave (this card) | no | 171 | |
| Spec Kit | no | 149,434 | the GitHub toolkit of spec-driven commands, while this adds an evidence ledger, project memory and handoff between agents |
| OpenSpec | no | 74,686 | a proposal, requirements and tasks cycle, while this closes tasks with test evidence and review by another model |
README in short
The README starts with installation and what `init` writes into a project. Next come the SpecWithCode desktop app built on the CLI, attaching existing repositories, handoff between tools and a table of six loop steps. A comparison with Claude Code Projects follows, then seven core and four optional skills and the 3.0 upgrade guide.