Docs

Install

Pick one. The install script runs on macOS and Linux; the CLI needs Node 22 or later.

Then run cowpath init (npx cowpath runs it for you). It adds the hooks to Claude Code, and the MCP server too if claude is on your PATH. If codex is on your PATH, it does the same for Codex; trust the new hooks once in Codex with /hooks. cowpath starts in local mode: no account, everything on your machine.

To share with a team, run cowpath login. Your processes, runs and playbooks sync to your workspace, including what you kept locally before. cowpath status shows the mode, the workspace and the last sync.

How capture works

Claude Code and Codex: hooks.

When a session ends, cowpath queues it. The agent CLI that ran the session (claude -p or codex exec, on your plan) reads the transcript and cuts out the run: the input, your corrections and the final version. Sessions with no file changes and no long reply are skipped. Only the run is stored or uploaded; cowpath never receives the transcript.

When you send a prompt that matches a process with a playbook, cowpath puts the playbook in your agent's context. You don't call anything.

The local MCP server has three tools, processes, playbook and run, for the things you ask for by name: rate this run, move it to another process, edit the playbook. It works on your local records.

claude.ai, ChatGPT and Claude Desktop: MCP.

Add cowpath as a connector and sign in. From then on your agent does the work:

1. 1Before work that ends in a deliverable, it finds the matching process, or creates one.
2. 2It starts a run and follows the playbook it gets back.
3. 3When the deliverable is final, it finishes the run with the final version and your corrections.
4. 4When you approve or reject the result, it records your thumb. It never rates on its own.

One-off questions are skipped. The full chat is never stored, only what the agent passes.

The playbook updates itself.

The first finished run of a process writes its first playbook. After that, once five runs have finished since the last version, the playbook is rewritten from them: keep what thumbs-up runs did, drop what corrections reversed, change at most a fifth. With hooks, your agent CLI does the rewrite; in claude.ai and ChatGPT, your agent gets the instruction when it finishes a run. cowpath runs no model of its own.

Processes

A process is a path of one to three levels: sales/decks/discovery. A playbook is read together with the playbooks above it, so sales can hold what every sales process shares. Your agent creates processes as it goes and reuses a close match when there is one; when it creates one by name, cowpath shows it similar ones first. Rename and move any process later.

MCP tools

The hosted server, for claude.ai and ChatGPT, has six tools. Each takes an action.

Errors come back as {code, message, hint}. The hint says what to do next.

A write from an outdated version fails. The agent reads the latest one and tries again.

Commands

Wondering why a session was skipped? tail ~/.cowpath/log says why.

Privacy

• cowpath never receives a transcript. The run is cut by your own agent CLI, on your plan, so the transcript goes only where your sessions already go.
• A run holds the input, the corrections, the final version and the rating, plus the client and model.
• In local mode nothing is uploaded.
• Signed in, runs and playbooks are stored in your workspace, visible to its members only.
• Every playbook version records who wrote it and through which agent, client and model.
• cowpath export writes your local playbooks as Markdown.

Uninstall

• Homebrew: brew uninstall cowpath
• Hooks and MCP in Claude Code and Codex: cowpath uninstall. Add --purge to delete ~/.cowpath.
• claude.ai, Claude Desktop and ChatGPT: remove the cowpath connector in the app's settings.
• Export your playbooks as Markdown first if you want to keep them.