convez.ai
MCP ServerDevOps & InfraestruturaIntermediário
coo1white

Cool Workflow

coo1white/cool-workflow

Transforme análises de IA em relatórios auditáveis, citados e repetíveis

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP 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-workflow

1 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

Estrelas
2
Forks
0
Acompanhando
0
Saúde
71%
Último commit
há 6 dias
Versão
v0.5.0
Issues abertas
0
Contribuidores
2

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.

CI npm downloads provenance release license

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

  1. Node.js (v18+). Check with node --version.
  2. An AI agent on the command line. The easiest is Claude Code — after installing it you'll have a claude command. Check with claude --version. (CW also works with codex, or any command/HTTP agent — but start with claude.)

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. Install claude and 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):

CommandWhat it does
architecture-reviewMap a repo's structure and rank its real risks, with evidence.
pr-review-fix-ciReview a pull request, propose fixes, check CI.
research-synthesisGather and synthesize an evidence-backed answer to a question.
release-cutDrive 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

ProblemFix
status: blocked, agentConfigured: falseNo agent is set up. Install claude (or pass --agent-command).
claude: command not foundInstall Claude Code so the claude command exists, then re-run.
Want to see the plan without running the AIAdd --preview — it shows the steps and spawns nothing.
Live agent trace is too noisySet 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.

Ver o original no GitHub

Bom para

Relacionados