Cool Workflow
coo1white/cool-workflow
Transforme análises de IA em relatórios auditáveis, citados e repetíveis
Ver no GitHubMCP server que transforma perguntas descartáveis sobre repositórios em relatórios salvos e auditáveis. Funciona como um gerenciador de projetos que orquestra agentes de IA externas (Claude, Codex) para executar análises estruturadas, registrando cada achado com citações exatas de arquivo e linha. Gera relatórios à prova de adulteração usando atestação ed25519.
Instalação
npx convez-ai coo1white/cool-workflow1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Auditar riscos de segurança em repositórios com provas imutáveis
- Documentar reviews arquiteturais com rastreabilidade completa
- Automatizar análises de código multiagente com fail-closed gates
- Manter histórico repetível de investigações técnicas
Veredito

Ferramenta sólida para equipes que precisam de auditoria e repetibilidade em análises de código. Preenche um gap real entre chats descartáveis de IA e relatórios profissionais rastreáveis, com suporte nativo a MCP e CLI zero-dependência. Ideal para contexts de segurança e compliance.
README
A tradução para o português deste README ainda está na fila.
Cool Workflow
Point an AI coding agent at a repo, get a saved report with real citations — not a chat message you lose.
What is this, really?
You ask an AI coding agent a question, it answers in the chat, and then it's gone. Next week you ask again and start from scratch.
Cool Workflow (CW) turns that throwaway question into a saved job. You point
it at a code repository with a question like "what are the security risks here?"
It runs your AI agent over the whole repo in organized steps and writes a
report file to disk — every finding backed by an exact file.js:42 citation.
You can re-run it, share it, and even prove the report wasn't tampered with.
you ask once CW gives you
"what are the risks in my repo?" → a saved report.md with
cited findings, repeatable
It does not run the AI model itself. You bring your own agent (e.g. the
claude command line) and CW drives it, records what happened, and checks the
result. Think of CW as the project manager, and your agent as the worker.
New to this? You're in the right place — this README is a step-by-step start. Deeper/advanced docs live in the wiki.
What you need
- Node.js (v18+). Check with
node --version. - An AI agent on the command line. The easiest is Claude Code — after
installing it you'll have a
claudecommand. Check withclaude --version. (CW also works withcodex, or any command/HTTP agent — but start withclaude.)
No agent yet? You can still see CW work (next section, step 1) without one. The full report needs an agent, because CW never calls a model itself.
Quick start (3 steps)
1. See it run — no install, no agent, no API key
npx cool-workflow demo tamper
This proves CW's headline trick in 30 seconds (more on that
below). If you see VERDICT: tamper-evidence holds ✓,
everything works.
2. Run a real review on your own repo
npx cool-workflow quickstart architecture-review \
--repo /path/to/your/project \
--question "What are the main risks in this codebase?" \
--agent-command builtin:claude
--repo— the folder you want reviewed.--question— what you want to know.--agent-command builtin:claude— use the bundled Claude wrapper (read-only; it never edits your code).
CW plans the work, drives claude over your repo in steps, and prints where it
saved the report. While each step runs you'll see the agent working live in
your terminal — which files it reads, what it's writing — so a long step never
looks frozen. (That trace goes to stderr only; the recorded result is unchanged.)
No agent configured? CW stops safely and tells you so (
status: blocked) — it never makes up an answer. Installclaudeand re-run.
3. Read the report
cat /path/to/your/project/.cw/runs/<run-id>/report.md
You'll get a summary, ranked findings, and clickable citations like
src/server.js:18 for every claim — so you can check each one yourself.
Install it (optional)
npx always works without installing. To get the short cw command everywhere:
npm install -g cool-workflow # then use: cw … instead of npx cool-workflow …
What else can it do?
CW ships several ready-made "jobs" (run cw list to see them all):
| Command | What it does |
|---|---|
architecture-review | Map a repo's structure and rank its real risks, with evidence. |
pr-review-fix-ci | Review a pull request, propose fixes, check CI. |
research-synthesis | Gather and synthesize an evidence-backed answer to a question. |
release-cut | Drive a gated, reviewed release. |
It also exposes the same actions over MCP, so editors like Claude Desktop / Cursor / VS Code can call CW as a tool. See the wiki for that and for multi-agent runs.
Can I trust the report?
This is what makes CW different. Because CW only delegates to your agent, it keeps a tamper-evident record of every step: each agent's reported token usage is cryptographically signed and hash-chained, so editing the record after the fact breaks the chain — and anyone can re-verify it offline with only a public key.
See it for yourself — the demo tamper from step 1 forges a record two ways and
catches both:
▶ LEDGER tamper
after: ✗ DETECTED — the hash chain caught it: chain-link[2]: telemetry-chain-broken
▶ SIGNATURE tamper
after: ✗ DETECTED — signature does not match reported usage
VERDICT: tamper-evidence holds ✓ — every forgery caught offline, with only the public key.
On a real run, verify any run's record yourself:
cw telemetry verify <run-id>
CW dogfoods this on its own codebase — see the committed live-run proof in
plugins/cool-workflow/docs/dogfood/.
The plain-English point: the thing that spends the tokens is not the thing that keeps the books. That separation is normal in accounting — CW brings it to AI agents.
Troubleshooting
| Problem | Fix |
|---|---|
status: blocked, agentConfigured: false | No agent is set up. Install claude (or pass --agent-command). |
claude: command not found | Install Claude Code so the claude command exists, then re-run. |
| Want to see the plan without running the AI | Add --preview — it shows the steps and spawns nothing. |
| Live agent trace is too noisy | Set CW_NO_STREAM=1. (Piped output and CI runs are silent automatically.) |
| Where did my report go? | The command prints reportPath; it's under <your-repo>/.cw/runs/<id>/report.md. |
How it works (one paragraph)
CW is a small, zero-dependency TypeScript/Node runtime. It records the agent loop
explicitly — plan → dispatch → record → verify → commit → report — as durable
files on disk, so a run is inspectable and replayable instead of a disposable
chat. It never embeds a model SDK and holds no API key; your configured agent does
the thinking, CW does the bookkeeping and the checking. For the architecture,
multi-agent coordination, execution backends, and the full CLI/MCP surface, see
the wiki and
plugins/cool-workflow/docs/.
License
BSD-2-Clause. See LICENSE. Built by COOLWHITE LLC.