# cool-workflow [Health: Active]

**Category:** 💻 Developer Tools  
**Repository:** https://github.com/coo1white/cool-workflow  
**GitHub Stars:** 2  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/cool-workflow

## Description
Signed, cited, replayable workflows for Claude, Codex, Gemini, DeepSeek, and other agents.

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "cool-workflow": {
    "command": "npx",
    "args": ["-y","cool-workflow"]
  }
}
```

## Documentation & README

<div align="center">

<img src="https://raw.githubusercontent.com/coo1white/cool-workflow/HEAD/plugins/cool-workflow/project/docs/assets/cw-hero.png" alt="Cool Workflow hero image: the CW name over a line reading ask, plan, dispatch, verify, report — the stages of a saved, cited run." width="100%">

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

[![CI](https://img.shields.io/github/actions/workflow/status/coo1white/cool-workflow/ci.yml?branch=main&style=flat-square&label=CI&color=EC6516)](https://github.com/coo1white/cool-workflow/actions/workflows/ci.yml) [![npm](https://img.shields.io/npm/v/cool-workflow?style=flat-square&label=npm&color=cb3837)](https://www.npmjs.com/package/cool-workflow) [![downloads](https://img.shields.io/npm/dm/cool-workflow?style=flat-square&label=downloads&color=EC6516)](https://www.npmjs.com/package/cool-workflow) [![provenance](https://img.shields.io/badge/npm-provenance-3178C6?style=flat-square)](https://www.npmjs.com/package/cool-workflow) [![release](https://img.shields.io/github/v/tag/coo1white/cool-workflow?style=flat-square&label=release&color=brightgreen&sort=semver)](https://github.com/coo1white/cool-workflow/tags) [![license](https://img.shields.io/badge/license-BSD--2--Clause-blue?style=flat-square)](LICENSE)

</div>

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

```bash
npm install -g cool-workflow
```

<details>
<summary>Or install with <b>Homebrew</b></summary>

```bash
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`.
</details>

**You need:** Node.js v18 or newer. No agent yet? Step 1 below still works — **CW never runs a model itself.**

## Works with your agent

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

## Quick Start

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

```bash
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

```bash
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`.

### 3 · Open the report

The report opens in your browser by itself when the run ends. Later, open it again with:

```bash
cw report --open
```

Want to see one first? A real run's Workbench and report, rebuilt on every push: **[coo1white.github.io/cool-workflow](https://coo1white.github.io/cool-workflow/)** (the report is at [/report.html](https://coo1white.github.io/cool-workflow/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](https://github.com/coo1white/cool-workflow/blob/HEAD/plugins/cool-workflow/docs/trust-model.md)**.

## Troubleshooting

| 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 | `cw --resume --run <id>` takes it to the end (inside the project, or add `--repo <path>`) |
| `... is not a git project` | Run it inside the project, or pass `--repo` |

## Learn more

- **[User Guide](https://github.com/coo1white/cool-workflow/wiki/User-Guide)** — your first ten minutes
- **[Why Cool Workflow](https://github.com/coo1white/cool-workflow/wiki/Mental-Model)**
- **[How it works](https://github.com/coo1white/cool-workflow/wiki/Architecture)**
- **[What you can run](https://github.com/coo1white/cool-workflow/wiki/Workflow-Apps)**
- **[From your editor](https://github.com/coo1white/cool-workflow/wiki/MCP-And-Manifests#from-your-editor)**
- **[Trust & Audit](https://github.com/coo1white/cool-workflow/wiki/Trust-And-Audit)**
- **[Repo Map](https://github.com/coo1white/cool-workflow/wiki/Repo-Map)**
- **[Wiki home](https://github.com/coo1white/cool-workflow/wiki)**

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

## License

BSD-2-Clause. Built by COOLWHITE LLC.