io.github.coo1white/cool-workflow

Get a saved report from your AI agent, with every claim tied to a line of code — not a chat answer you lose.

What is this?

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.

Install

npm install -g cool-workflow

Or install with Homebrew

brew tap coo1white/cool-workflow https://github.com/coo1white/cool-workflow
brew install coo1white/cool-workflow/cool-workflow
cw version

Upgrade 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.

Works with your agent

Not sure what you have? cw doctor checks your setup and cw fix prints the commands that put it right.

Quick Start

1 · See it work — 30 seconds, no agent needed

cw demo tamper
# → builds a real signed ledger, forges it three ways, catches all three offline
# → VERDICT: tamper-evidence holds ✓

2 · Ask a question about your code — one command

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.

3 · Open the report

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 --open

Want 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).

These three steps are the core path. Everything else is kept working, not grown.

Can You Trust the Report?

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.

Troubleshooting

Learn more

• 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

CW dogfoods its own release: every cut runs release-cut against this repo.

License

BSD-2-Clause. Built by COOLWHITE LLC.