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. Local-only: the server binds to 127.0.0.1 and generation runs with your own Anthropic credentials.

Quick start

npx @coopcli/specsketch ./openspec/changes/new-feature-change
# or: npm install -g @coopcli/specsketch && specsketch ./openspec/changes/new-feature-change

Open the printed URL, draw labeled boxes and arrows (loose text becomes design notes), and press Generate Spec. The change directory is the workspace:

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

Stop and rerun with the same directory to resume where you left off. If the directory already contains artifacts — scaffolded by openspec new change or hand-written — they're the baseline: generation makes the smallest revision that fulfills the drawing, leaving unimplicated files byte-identical.

Use cases

• Spec-first feature kickoff. Sketch the shape of a change, generate the OpenSpec proposal/design/tasks/capability specs, review, and hand the change directory to an implementing agent. npx openspec validate works on the output.
• Revising an existing change. Point specsketch at a change directory that already has artifacts; update the drawing and regenerate — only what the diagram implicates changes.
• Design review, captured. Chat about the generated spec (answers are grounded in the artifacts on disk), then Regenerate — your corrections in the conversation become requirements for the next pass, so review decisions land in the spec instead of a meeting doc.
• Whiteboarding with the team. --share hosts the canvas live; teammates draw with you from a plain browser link, no account or install, and everything lands in the change directory on your machine.
• Grounded in real code. @ references pull actual files into the model's context, so the spec describes your system rather than a guess at it.

File references: @<path | filename>

Anywhere you type — the architecture title, text on the canvas (labels and loose notes), or the review chat — an @ reference pulls a real file into the model's context:

• @server/app.ts — a path relative to the directory you launched specsketch from.
• @schema.ts — a bare filename; the tree is searched (skipping .git, node_modules, dist) and the shallowest match wins. Multiple matches are noted in the context.
• @src/ui or @src/ui/ — a directory; its files (recursively, up to 50 files and the size budgets) are all pulled into context, each reported individually.

Typing @ in the chat composer or the system prompt editor opens an inline search over that same scope — files and directories, filtered as you type; arrows + Enter/Tab (or a click) select, Escape dismisses. Selecting a directory inserts @dir/ and keeps the search open scoped to it: stop there to reference the whole directory, or keep typing to drill down to a file.

References are scoped to the launch directory: absolute paths, .., and symlinks that escape it are refused. Large files truncate at 64KB (256KB across all references). An unresolvable reference never fails generation or chat — it degrades to a "could not be resolved" note in the context, and the chat pane lists which files resolved and which didn't under each answer.

The spec review pane: Spec / System Prompt / Chat

The right-hand panel has a menu with three options:

• Spec — the generated artifacts (summary, proposal, design, tasks, capability specs).
• System Prompt — view and edit the prompt that drives generation. Saved edits apply to every subsequent generation and persist with the change directory (specsketch.json); Reset restores the built-in default. @ references inside the prompt resolve like any other input, so you can pin conventions with @docs/style.md.
• Chat — available once a spec exists. Ask questions about the generated OpenSpec, pull files in with @ references, and iterate:
  • Regenerate (header, next to Generate Spec) re-runs generation with the conversation as extra context.
  • Clear (in the pane) discards the conversation and starts over.
  • Every generation resets the chat and seeds it with an AI-written summary of the prior conversation and what changed on disk — context stays bounded, the thread of decisions survives. The chat persists in specsketch.json across restarts.

Requirements & auth

• Node ≥ 22 (the CLI checks at startup).

• Anthropic credentials — only needed for Generate Spec; drawing works without them, and the CLI tells you at startup if none are found. Either:

  export ANTHROPIC_API_KEY=sk-ant-...        # option 1: plain API key
  # option 2: the Anthropic CLI's login profile (no key handling)
  brew install anthropics/tap/ant && ant auth login

CLI reference

specsketch <path-to-openspec-change-dir> [--port <n>] [--share]
specsketch login [--profile <name>] [--web-url <url>]

• The directory is created if it doesn't exist; its basename becomes the change name.
• --port sets the preferred port (default 8787). If it's already in use — say another specsketch session is running — the server moves to the next available port and the printed URL reflects the one actually bound. Binds to 127.0.0.1 exclusively — there is no --host.
• --share hosts the canvas as a live multiplayer session (see below).
• Model picker (top bar): claude-opus-4-8 (default), claude-sonnet-5, or claude-fable-5. The choice is saved with the change directory. Fable runs with server-side refusal fallbacks to Opus and requires your org to allow 30-day data retention.

Shared sessions (--share)

specsketch login                                                 # once per machine
specsketch ./openspec/changes/new-feature-change --share

--share creates a multiplayer session on your CoopCLI account and prints a link like https://coopcli.com/products/specsketch/s/<id>?k=<token>. Coworkers open it in a plain browser — no account, no install — see the live canvas, and can draw on it; their edits stream back and land in diagram.excalidraw like your own. The top bar shows a live pill with the participant count and a copy-link button.

Worth knowing:

• The host needs a CoopCLI account (specsketch login — opens a browser, saves credentials to ~/.coopcli/config.json, the same file coop login writes); guests never do. The link itself is the capability: anyone holding it can view and edit until the session ends. The server stores only a hash of the link token.
• The local server still binds to 127.0.0.1 only — sharing runs over a single outbound connection from the CLI. Your CoopCLI API key never reaches any browser.
• Concurrent edits resolve per element, last-write-wins. The change directory on the host remains the durable copy.
• Connections heal themselves (heartbeat + reconnect with backoff); a brief "reconnecting…" pill is normal.
• Ctrl-C ends the session and invalidates the link. Idle sessions expire server-side after 24 h.

Troubleshooting

| Symptom | Fix | |---|---| | npm error 404 @coopcli/specsketch not found right after a release | Registry propagation lag — retry in a minute or two | | Startup warning "No Anthropic credentials detected" | Set ANTHROPIC_API_KEY or run ant auth login, then restart | | Generate fails with a 401 / "anthropic-auth" | Same as above — the server found no credentials, or the login profile expired (ant auth status) | | "Node NN detected — specsketch needs Node >= 22" | Upgrade Node (https://nodejs.org) | | Port already in use | Handled automatically — the server moves to the next free port and prints it; --port <n> sets the preferred starting port | | Regeneration changed a file you hand-edited | Expected when the drawing implicates it — the diagram is the source of truth; use git diff/git checkout to recover, and keep change dirs in version control | | --share says it needs login | Run specsketch login once on the hosting machine; --profile selects a non-default CoopCLI config profile | | Share link says it no longer works | The host ended the session (Ctrl-C) or it idled out — ask for a fresh link |

More: product page · docs. Sibling product: specplan — plan the roadmap those changes live on. Source, contributor setup, and the QA checklist live in the coopcli repo (packages/specsketch).