coopcli specsketch

Draw the system. Get the spec.

An Excalidraw canvas that turns architecture diagrams into OpenSpec change proposals — written straight into your openspec/ change directory, next to the diagram that produced them, ready for an implementing agent.

specsketch

$ npx @coopcli/specsketch ./openspec/changes/new-feature-change

coopcli specsketch

workspace: ./openspec/changes/new-feature-change

open: http://127.0.0.1:8787

Local-only by design: the server binds to 127.0.0.1, generation runs with your own Anthropic credentials, and nothing leaves your machine except the model call.

Works with OpenSpec

OpenSpec is a spec-driven workflow: each change to a system lives in its own directory (openspec/changes/<change-name>/) as a proposal, design, task list, and capability specs — written before the code. specsketch generates those artifacts from your diagram. You don't need anything installed: point it at a change directory (created if missing) and it writes plain markdown. If the directory already has artifacts, generation makes the smallest revision that fulfills the drawing — and npx openspec validate works on the output.

Get started

Set up Anthropic auth

Pick one — an API key in your environment, or the Anthropic CLI's login profile (no key handling). Drawing works without either; Generate Spec needs one.

Option A — API key

export ANTHROPIC_API_KEY=sk-ant-...

Option B — Anthropic CLI (macOS)

brew install anthropics/tap/ant && ant auth login

Run it against a change directory

Run once with npx

npx @coopcli/specsketch ./openspec/changes/new-feature-change

Or install globally

npm install -g @coopcli/specsketch

Draw the architecture

Boxes are components, arrows are data/control flow, loose text becomes design notes. The session autosaves to diagram.excalidraw in the change directory — stop and rerun any time to resume.

Generate Spec

One click produces the OpenSpec artifacts. If the directory already has artifacts — scaffolded or hand-written — they're the baseline: generation makes the smallest revision that fulfills the drawing.

Hand it to your agent

Everything lands in the change directory, specs and diagram side by side:

openspec/changes/new-feature-change/
├── diagram.excalidraw      ← the drawing, agent-readable
├── specsketch.json
├── proposal.md
├── design.md
├── tasks.md
└── specs/<capability>/spec.md

Troubleshooting

"No Anthropic credentials detected"

The canvas still works; Generate Spec needs credentials. Set ANTHROPIC_API_KEY or run ant auth login, then restart. An expired login shows the same way — check ant auth status.

"specsketch needs Node >= 22"

Upgrade Node from nodejs.org (or your version manager) and rerun the npx command.

Regeneration changed my edits

The diagram is the source of truth: generation makes the smallest revision it can, but files the drawing implicates get updated. Keep change directories in git and use git diff to review each generation.

Running several sessions at once

Just start them — one per change directory. If the preferred port (default 8787) is taken, the server moves to the next free one and prints the actual URL. --port <n> sets the preferred starting port.

@coopcli/specsketch on npm Meet coop