SpecWeave

Change agents. Keep the thread.
Plan work as small specs, hand it between Claude, Codex, Grok and any other tool in two words, and close it with evidence.

Install

npm install -g specweave        # Node.js 20.12.0+
cd your-project
specweave init .

init writes AGENTS.md (read by Codex, Grok, Cursor, Gemini and Copilot), a two-line CLAUDE.md that imports it, and the skills for Claude Code and Codex. Nothing else runs in the background.

Out of tokens? Say "hand off"

you (in Claude, account 1):   hand off
you (in Codex, or account 2): pick up

That is the whole handoff. "Hand off" runs specweave handoff: it releases your task claims, records why you stopped, and pushes your branch plus a snapshot of your uncommitted edits. "Pick up" runs specweave pickup in any other tool, account, machine or cloud session (a Claude Code Projects thread, a Codex cloud task): it brings that work into the checkout and prints the next task with its acceptance criteria. Nothing to copy, no paths to paste.

Running out mid-task? specweave auto-handoff on, once per machine, makes it automatic: when a session reaches 90% of your plan's 5-hour or weekly limit, it hands off by itself and tells you to say "pick up" elsewhere. Claude Code reads the limit through its status line (your own status line keeps working) and Codex through a Stop hook. Under the threshold it costs no tokens. --at 85 changes the threshold and off undoes every change.

specweave report writes an HTML timeline of who did what on an increment (tools, sessions, handoffs, pickups, test evidence), straight from the ledger.

The loop

An increment is one folder, .specweave/increments/NNNN-slug/, with one file you read (spec.md) and one the CLI appends to (ledger.jsonl). Increments from 2.x with a tasks.md keep working unchanged.

Works the way Claude Code Projects work

Project memory in claude.ai stays with one account. .specweave/memory/ travels with the code, so Codex, Grok and a second Claude subscription start from the same decisions.

The eleven skills

The CLI is the product and runs in any tool or in CI. The skills expose it to coding agents: /sw:<name> in Claude Code, sw-<name> in .claude/skills/ (for Projects threads, where plugins do not load) and .agents/skills/ (Codex, Grok).

Upgrade to 3.0

npm i -g specweave@3
specweave update

specweave update rewrites AGENTS.md into the lean form, turns CLAUDE.md into an import of it, keeps your own sections, and backs up the old files under .specweave/backups/. Existing increments need no migration. The 3.0.0 changelog lists what changed and what was removed. To have sessions hand off by themselves near the usage limit, run specweave auto-handoff on once.

Built With SpecWeave

Examples from the maintainer's portfolio. These are usage examples, not controlled productivity measurements.

Browse increments on GitHub — full transparency.

How It Compares

Cursor tells AI "use Tailwind." SpecWeave tells AI "build a checkout flow against these five acceptance criteria, prove the tests pass, review the diff, then close."

Key Features

Spec-First Planning — Every feature starts as one spec.md: Problem, Scope, ACs, Approach and Tasks.

Evidence, not vibes — specweave task done --run "<test>" refuses a failing command and stores the exit code and output tail in the ledger.

Multi-agent, any vendor — A worktree per agent, claims through ledger.jsonl, one closure. Coordination happens only through committed files.

┌──────────────────┬──────────────────┬──────────────────┐
│  Agent 1 (auth)  │ Agent 2 (payments)│ Agent 3 (catalog)│
│  T-01..T-04      │  T-05..T-08      │  T-09..T-12      │
│  ████████░░ 80%  │  ██████░░░░ 60%  │  ████░░░░░░ 40%  │
└──────────────────┴──────────────────┴──────────────────┘

LSP Code Intelligence — 198x faster than grep, 0 false positives. Semantic references, definitions, and types.

11 skills, one source — the same skills for Claude Code, Codex and Grok; see The eleven skills.

External Sync — specweave sync push|pull|status|setup. GitHub is first-class; Jira and Azure DevOps are opt-in. Nothing calls a tracker unless you run sync.

Enterprise Ready — Compliance audit trails. Brownfield analysis. Multi-repo workspaces.

Dashboard — specweave dashboard shows intents, increments and evidence from local files, with no model calls.

Skills Ecosystem

SpecWeave skills are published and verified at verified-skill.com. The vskill package manager provides:

• Security scanning — 52 attack patterns, SHA-256 pinning, blocklist API
• 49 agent platforms — one install deploys to Claude Code, Cursor, Copilot, Windsurf, and 45 more
• Skill evals — unit tests, A/B comparisons, cross-model testing. Skills tested like programs.
• Visual Skill Studio — vskill eval serve for benchmarks, comparisons, and history

npx vskill install remotion-best-practices    # Install from registry
npx vskill eval run my-skill                  # Run eval suite

Documentation

spec-weave.com — SpecWeave 3.0 · handoff · commands · skills · configuration

Contributing

Inside this repo dependency install scripts are disabled (.npmrc): run npm ci, then npm run setup (rebuilds the allowlisted native deps), and npm run security:scan before pushing — see SECURITY.md.

Community

Discord · YouTube · GitHub Issues

License

MIT — github.com/anton-abyzov/specweave