Cool Workflow

CI npm downloads provenance release license

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?

You may already use an AI coding agent — a tool like claude, codex, or gemini that reads your code and answers questions about it. The answer comes back as a chat message. Chat is easy to lose, and hard to check.

Cool Workflow (cw) is a small command-line tool that fixes that. 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 does the reading and the thinking.
• It keeps a record. Every step is saved as plain JSON files on your own disk, under .cw/. You can read them, compare them, and pick a run up again later.
• It checks the results. A result with no evidence does not get through — it stops in a clear unexplained state instead.
• It writes a report. Every claim points to a real place in your code, like file.ts:42. Click it and see for yourself.

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. Your agent spends the tokens; CW keeps the books — as plain JSON on your own disk.

Install

npm install -g cool-workflow

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

You need: Node.js v18 or newer, and one agent CLI on your machine — claude, codex, gemini, or opencode. CW finds them by itself. No agent yet? Step 1 below still works — CW never runs a model itself.

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 ✓

This is CW's trust check working on itself: it makes a signed record, breaks it on purpose in three ways, and catches all three breaks.

2 · Ask a question about your code — one command

Go to any project folder and run:

cw -q "How does auth work end-to-end here?"

Any question works — "how does X work", "is it safe to change Y", "what would break if Z rotated". CW uses the current repo and the first agent it finds on your PATH. Want a specific agent? Add a flag (-claude, -codex, -gemini, -opencode, -deepseek). Note: the -gemini and -deepseek flags reach their models through opencode, so those two need opencode installed and its provider signed in. DeepSeek also has no auto-detect, so -deepseek is the only way to get it. (A native gemini CLI found on your PATH is used directly.) You can point CW at any folder, or at a repo on the web by URL — CW clones it and reviews the copy:

cw -q "What are the security risks?" -dir /path/to/project
cw -q "Is it safe to swap this queue for Redis?" --link https://github.com/owner/repo

Not just code. Point CW at a folder of docs, notes, or papers and it reads them as sources for the same saved report:

cw quickstart research-synthesis --repo /path/to/papers \
  --question "What do these papers conclude?"

3 · Open the report

The command prints the path when it is done. Every finding has a clickable file.ts:42 pointer:

cat .cw/runs/<run-id>/report.md

While it runs you get a calm live view — a small rolling window of tool calls that updates in place, not an endless wall of text — and a clean findings table at the end.

Why Cool Workflow

Most agent tools run a whole task as one long prompt, then hand you a chat message. When the work is long, parallel, or high-stakes, you cannot tell what happened or trust the result. CW treats that as a runtime problem — like an operating system keeping processes safe and visible — and rests on four commitments:

What CW is not. CW is not the model — it never calls a model API and never holds your keys; your agent does that work in its own process. It is not a CI system or a build tool — it keeps and checks the record of agent work; it does not take the place of your tests or your release pipeline. And it is not a big framework to build on — it is a small set of commands over plain .cw/ files on your own disk, not a library your code has to wrap itself around.

How It Works

CW is a small TypeScript tool with zero runtime dependencies. It drives your agent over a repo — or any folder — in saved stages that you can replay, writing everything to disk as files you can open and read. It never imports a model SDK or stores an API key.

ask simple → run simple → verify simple → resume simple

What You Can Run

Every app writes the same thing: a saved report you can check again offline, with every claim tied to its source. These four are the main lanes; cw app list shows all eight installed apps.

cw app list            # see everything installed
cw doctor              # check your setup    →    cw fix   shows the fix commands

Multi-agent, when you need it. Fan work out across agents with built-in topologies (ready-made team shapes), compose flows (a task can run a whole child workflow with subWorkflow, or a loop() phase can go round until a condition or a token budget says stop), and re-run fast — cw run <app> --drive --incremental reuses every step whose inputs did not change.

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 nothing but the public key — that every signed finding is in the report unaltered. Edit a finding, in the report or in the agent's own result, and the check fails. CW holds no private key: the agent signs, CW only verifies.

cw demo tamper                                  # proves it in 30s — edits a signed result, watch it fail
cw -q "…" --bundle                              # seal a run into one portable file
cw report verify-bundle report.cwrun.json       # anyone can re-check it offline, with just the file

This proves the agent's signed findings reached you unaltered — not that nothing else was added, and not that nothing was left out. For exactly what is and is not proven, see the Trust Model.

Use It From Your Editor

CW offers the same runtime over MCP — a standard way for editors to call tools. Claude Desktop, Cursor, and VS Code call CW as a tool, so your agent can plan a run, drive it, and verify a report without leaving the editor. CLI and MCP share one registry and are parity-checked. See the Wiki.

The MCP server is scripts/mcp-server.js inside the installed package. After npm install -g cool-workflow, its full path is:

<output of `npm root -g`>/cool-workflow/scripts/mcp-server.js

Put that path in the configs below where you see /path/from/npm-root-g/….

/plugin marketplace add coo1white/cool-workflow
/plugin install cool-workflow@cool-workflow

claude mcp add cool-workflow -- node "$(npm root -g)/cool-workflow/scripts/mcp-server.js"

{
  "mcpServers": {
    "cool-workflow": {
      "command": "node",
      "args": ["/path/from/npm-root-g/cool-workflow/scripts/mcp-server.js"]
    }
  }
}

{
  "mcpServers": {
    "cool-workflow": {
      "command": "node",
      "args": ["/path/from/npm-root-g/cool-workflow/scripts/mcp-server.js"]
    }
  }
}

{
  "servers": {
    "cool-workflow": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/from/npm-root-g/cool-workflow/scripts/mcp-server.js"]
    }
  }
}

Once connected, your agent sees the cw_* tools — cw_plan, cw_status, cw_report, and the rest — the same registry the CLI uses, parity-checked. More on the MCP surface — parity, manifests, vendor targets — is on the wiki page MCP And Manifests.

Troubleshooting

Repo Map

What every top-level folder and file is for, one line each. Most of these places are fixed by a tool, a test, or the release chain — they are where they are for a reason.

Docs & Wiki

New here? Start with the Wiki → Getting Started · Mental Model · Glossary · Trust & Audit

Building on CW? See the Getting Started doc, Project Index, and CLI ↔ MCP Parity.

CW dogfoods its own release process — it runs its own tool on itself, and every cut runs the release-cut workflow against this repo.

License

BSD-2-Clause. Built by COOLWHITE LLC.