Get a saved report from your AI agent, with every claim tied to a line of code — not a chat answer you lose.
Cool Workflow (cw) is a small command-line tool that turns your AI coding agent's chat answer — easy to lose, hard to check — into a saved report. Point it at a repo, or any folder of docs, and:
- It plans the work. Your question becomes a set of small tasks.
- Your agent does the work. CW never runs a model itself — your own agent reads and thinks.
- It writes a checked report. Every claim points to a real place in your code, like
file.ts:42. A result with no evidence stops instead of passing through.
The model is fuel. CW is the black-box recorder, the dashboard, and the gearbox — never the engine. It never calls a model API, never holds your keys, and never uploads your code.
npm install -g cool-workflowOr install with Homebrew
brew tap coo1white/cool-workflow https://github.com/coo1white/cool-workflow
brew install coo1white/cool-workflow/cool-workflow
cw versionUpgrade later with brew update && brew upgrade cool-workflow.
You need: Node.js v22.13 or newer. No agent yet? Step 1 below still works — CW never runs a model itself.
Runs on: Linux, macOS and Windows through WSL. Native Windows is not yet supported: CI runs it to measure what still fails, and that work is going on.
| Agent | Flag | Status |
|---|---|---|
| Claude Code | -claude |
✅ works |
| Codex CLI | -codex |
✅ works |
| Muse Code | -muse |
✅ works |
| OpenCode | -opencode |
✅ works |
| Gemini | -gemini |
✅ through opencode |
| DeepSeek | -deepseek |
✅ through opencode or an HTTP endpoint |
| Cursor | — | ⬜ not yet |
| GitHub Copilot CLI | — | ⬜ not yet |
| Aider | — | ⬜ not yet |
| Qwen Code | — | ⬜ not yet |
| Kimi | — | ⬜ not yet |
Not sure what you have? cw doctor checks your setup and cw fix prints the commands that put it right.
cw demo tamper
# → builds a real signed ledger, forges it three ways, catches all three offline
# → VERDICT: tamper-evidence holds ✓cw -q "How does auth work end-to-end here?"CW uses the current repo and the first agent it finds on your PATH. Want a specific agent? Add a flag from the table above, such as -claude.
A full review takes about 4 minutes on a real repo (14 workers; the Map and Assess stages run at the same time). One focused question? Add --fast: 6 workers in place of 14, the same cited answer for fewer agent calls.
The report opens in your browser by itself when the run ends. It starts with the answer, then the evidence behind it. Later, open it again with:
cw report --openWant to see one first? A real run's Workbench and report, rebuilt on every push: coo1white.github.io/cool-workflow (the report is at /report.html).
An agent that says "all tests pass" has only said it. Run the tests through CW and keep a receipt:
cw check -- npm test
# → ✓ passed: npm test (exit 0 at 1a2b3c4) — receipt rc-…. Cite it as receipt:rc-…CW runs your command (never a model) and saves what happened: the commit, the exit code, a digest of the output. A result that cites receipt:rc-… is checked again before it counts: a failed run, a missing receipt, or code that changed since the run is turned down, with the one command to fix it. cw check list shows your receipts.
These steps are the core path. Everything else is kept working, not grown.
CW does not run the model — it keeps the books. Your agent signs its findings (ed25519), and cw report verify-bundle checks — offline, with only the public key — that every signed finding is in the report unaltered. CW holds no private key: the agent signs, CW only verifies. This proves the signed findings reached you unaltered — not that nothing else was added, and not that none were left out. See the Trust Model.
| Problem | Fix |
|---|---|
| No agent found | cw doctor — shows which agents are on your machine |
status: blocked |
Set CW_AGENT_COMMAND=builtin:claude or pass -claude |
claude: command not found |
Install Claude Code and run again |
| Where is my report? | <repo>/.cw/runs/<id>/report.md, or run cw report --open |
Missing required input: question |
Add -q "<question>" |
| Run stopped before the end | Fix the cause, then cw --resume --run <id> takes it to the end; a worker that stopped gets fresh tries (inside the project, or add --repo <path>) |
... is not a git project |
Run it inside the project, or pass --repo |
Run <id> was made for <folder> |
The run belongs to another folder (a copied or moved repo): pass --repo <that folder>, or move it with cw run export and cw run import |
- User Guide — your first ten minutes
- Why Cool Workflow
- How it works
- What you can run
- From your editor
- Trust & Audit
- Repo Map
- Wiki home
- Contributing — to change CW itself: where to start for each job, the rules, and how to report a security problem
CW dogfoods its own release: every cut runs release-cut against this repo.
BSD-2-Clause. Built by COOLWHITE LLC.