Understand unfamiliar code, change it, and review the change with evidence — in the agent session you already use.
columbo turns a large or repetitive git diff into a smaller reading diff, and
carries explicit intent, evidence and decisions between sessions. It runs locally:
no server, no hooks, no background agent. TypeScript in src/ is the active
implementation. The upstream Go tree was removed; frozen conformance vectors
preserve its verified baseline.
For the architecture, document authority and proposed improvements, start with system design and the current roadmap. The agent workflow describes the commands available today, and the CLI reference documents every command and JSON contract.
Formerly Thread and Meat. The package is columbo-review; the columbo
and meat commands launch the same CLI. The meat engine protocol and wire
kinds are unchanged.
Requires Git and Node 22.18+; Node 24 is recommended (nvm use if you use
nvm). The source CLI and tests use Node's built-in TypeScript support.
columbo runs on Linux, macOS and Windows; the
test suite is checked on Linux and Windows. Set up once from this checkout:
npm ci
npm run setupsetup builds the CLI, links columbo and meat onto your PATH (npm link),
installs the meat skill for Codex and Claude Code, and finishes with
columbo -doctor. The doctor lists which review workflows work on this machine
and how to fix the others. It asks installed agent CLIs for their login status
but makes no model call, reads no diff and prints environment variable names,
never values. Run it again after signing in or adding a key. To remove the
commands, run npm unlink -g columbo-review.
On Linux, npm link fails with EACCES when Node was installed system-wide.
Use a version manager such as nvm, or give npm a user prefix with
npm config set prefix ~/.local (with ~/.local/bin on your PATH), then rerun
npm run setup. On Windows, npm creates meat.cmd and meat.ps1; PowerShell
runs the latter under the default RemoteSigned policy.
Without the link, use node /path/to/columbo-review/dist/cli/main.js wherever this page
says columbo, or npm start -- inside this checkout. columbo -h lists all flags.
Ask your agent:
Use columbo to implement this change. Understand the relevant code first, run the appropriate checks, and review consequential changes before finishing.
columbo prime <activity> --json loads local guidance for the current agent and
prints it; it does not run another model, install hooks, or perform the task.
| Activity | Use it when |
|---|---|
columbo prime understand |
Explain behavior from real source, without changing it |
columbo prime work |
Implement a change, check it, then review the final diff |
columbo prime review |
Review a selected diff with evidence |
columbo prime audit |
Investigate a whole repository and report coverage |
columbo prime converge |
Fix evidenced findings through Work |
For work that must survive a session restart, record intent and evidence explicitly:
columbo snapshot --file src/importer.ts --file test/importer.test.ts --json
columbo record --file intent.json
columbo status --jsonRecords live in worktree Git metadata (columbo-state-v1), are immutable, and
change to needs_recheck when their supporting bytes change. They are attributed
assertions, not proof, test receipts, or permission to act. columbo status --details shows claims and decision history. columbo help record-schema
documents the input contract.
columbo setup previews project-local skills for Codex and Claude Code; --yes
installs columbo, meat and show-me without overwriting existing files.
Run columbo from the repository you want reviewed. Pick the row that matches what you already have:
| You have | Run | You get |
|---|---|---|
| Claude Code or Codex open | /meat HEAD in Claude Code, $meat explain HEAD in Codex |
The open session explains the change |
| A Codex or Claude subscription | columbo -agent codex HEAD or columbo -agent claude HEAD |
A fresh read-only review in your terminal |
| Another agent or chat, such as Grok | columbo -prompt -o review.md HEAD |
A review packet to attach or paste |
| Nothing set up yet | columbo -look HEAD |
The change's shape, size and full diff, offline |
| An API key | columbo HEAD |
A compiled, abridged reading diff (API abridging) |
Only the last row needs an API key. Run without one, columbo says so and lists the commands that need none for the same change.
In Claude Code type /meat HEAD; in Codex type $meat explain HEAD. You
can also ask “Use columbo to explain my staged changes.” The skill collects a
packet and explains it in your current session, using that session's
subscription allowance. Packet creation needs no API key and launches no
additional agent. When a visual helps, the skill adds a small call tree, code
sketch or diagram.
npm run setup installs the skill. To install only the skill, run
npm run skill:install -- all, or codex or claude instead of all. The
installer writes a personal skill to ~/.agents/skills/meat/ and/or
~/.claude/skills/meat/, binding it to this checkout's absolute source entry.
The personal launcher reads the canonical skill on each use, so instruction
updates apply without reinstalling. Keep the checkout and its dependencies
available; rerun after moving it or changing discovery metadata. Open a new CLI
session, then invoke meat from the repository you want reviewed. This installer
runs from the source checkout, not an npm package installation.
The installer refuses linked personal meat directories/files to avoid altering
their targets. Use a regular personal skill directory.
A plugin can distribute a skill with other components. This repository ships the standalone skill and installer; it does not yet ship a plugin package.
Sign in once with codex login (using ChatGPT) or claude auth login, then:
columbo -agent codex HEAD
columbo -agent claude main...HEADInside this checkout, npm run review -- HEAD and npm run review:claude -- HEAD
do the same. This launches a fresh review and prints the finished explanation in
your terminal, with a small call tree, code sketch or diagram where one helps.
While it runs, columbo shows the elapsed time and hides the agent's own log, which
includes its session header and the echoed packet. Add -verbose to stream
that log; if the review fails, columbo prints the end of it. -o review.md saves
the explanation instead of printing it.
Meat checks the CLI's subscription login before sending the diff. It removes API credentials and provider-routing variables from the child environment and never falls back to its API backend. Codex runs with a read-only sandbox and without user configuration; Claude loads no user/project settings or MCP servers and is limited to Read/Grep/Glob. Login storage stays with the agent CLI. These fresh reviews use your subscription allowance and require network access. The result is an agent-written explanation, not an engine-compiled reading diff.
Requires CLI versions supporting the flags in src/cli/agent.ts (Codex 0.153.4
was live-tested). Update older CLIs if they report an unsupported option. Grok
native subscription execution is not implemented; use the packet instead.
Plain columbo HEAD still selects the original API abridger: use -agent codex
for subscription execution.
-prompt exports the full diff with review instructions:
columbo -prompt -o review.md HEADThen ask the agent: “Read review.md, inspect relevant source, and explain
the important changes and review risks.” For Grok chat, attach or paste the
file. -prompt does not call an agent, use a login, or incur a model call
itself. It exports the full diff with review instructions, not an abridgment.
The resulting explanation is agent-authored and does not use columbo's edit-plan
compiler. A relative -o path lands in the current directory, which is usually
the reviewed repository; write it elsewhere if you don't want it there.
Prefer -o to shell redirection. Windows PowerShell 5.1's > adds a byte-order
mark and converts line endings, and npm run prints banners unless invoked
with --silent. -o writes exactly the bytes stdout would carry, only after
the command succeeds. It works with every output: -look, -json, the
abridged diff, observation JSON and -agent.
Flags go before the revision. If one comes after, columbo stops and shows the
corrected command. Use explicit HEAD in agent shells and CI; with no source
argument, redirected stdin may be selected instead.
columbo -look HEAD # latest commit
columbo -look main...HEAD # branch changes since merge base
columbo -look -staged # index
columbo -look -w # unstaged tracked files
git diff | columbo -prompt # stdinReplace -look with -prompt to export a packet, or remove it to abridge.
-staged and -w cannot combine with each other or with a revision.
-prompt cannot combine with -look or -json.
For bounded offline inspection, use the versioned observation commands:
columbo -inventory -page-size 20 HEAD
columbo -evidence h:123 -snapshot <snapshot-sha256> -max-bytes 8192 HEAD
columbo -plan HEAD
columbo -capabilitiesChoose an actual entry ID and snapshot SHA-256 from the inventory before
expanding evidence. -cursor <page.next> continues the same source, operation
and page limit; changed evidence is rejected. Inventory and plan optionally
accept -snapshot too. Flags precede the revision. Inventory/plan pages default
to 20 entries (maximum 100); evidence pages default to 8192 bytes (maximum
16384). Each success writes one meat.observe version 1 JSON document. Evidence
uses base64 to preserve exact raw bytes, with original diff ranges whose ends
are exclusive. Runtime diagnostics go to stderr and exit 1; flag errors exit 2.
These commands make no model, login, gateway or cache call. Capabilities probes
no source. Committed snapshots resolve objects once and identify before/after
trees; their controlled diff omits commit messages. Mutable inputs retain diff
bytes with unavailable context and unverified consistency; stdin provenance
stays unknown. Snapshot-bound context tools remain future work. Planning applies
API partitioning to the captured observation bytes, with unknown model calls,
tokens and cost. It does not promise the same partitions for legacy execution of
the same Git selector, whose commit envelope can differ; current
execution tools still read the live checkout. Observation flags cannot combine
with legacy output, agent, model or cache flags. See the
observation contract for source identity and pagination.
Untracked files are not included by git diff. Empty input exits 1; it is not
a successful review. Help exits 0; flag parsing errors exit 2. Source-selection
conflicts and other runtime failures exit 1.
From another repository without npm run setup, use an absolute CLI path and
keep the shell in the repository being reviewed:
cd /path/to/your-repo
node /path/to/columbo-review/dist/cli/main.js -prompt -o review.md main...HEADThe built-in providers read OPENAI_API_KEY, ANTHROPIC_API_KEY, or
XAI_API_KEY. They do not read Codex/Claude Code/Grok subscription logins.
Choose an API model available to your account using -model or MEAT_MODEL:
claude-* routes to Anthropic, grok-* to xAI, and other IDs to OpenAI.
Set a Claude model explicitly when using an Anthropic key.
The CLI does not load .env automatically. To use a local .env containing
your provider key and MEAT_MODEL:
node --env-file=.env dist/cli/main.js HEADAbridging sends the diff and potentially requested surrounding source to the selected provider. Large diffs are chunked; each chunk can require model calls. Engine limits apply per chunk; the CLI currently exposes no aggregate time, call or token budget. Results do not identify fallback or chunk validation coverage. Repository tools read the current checkout, even for historical or staged inputs; inspect the appropriate revision when that difference matters.
Results are cached in ~/.meat; MEAT_CACHE=/some/path relocates the cache and
MEAT_CACHE= disables it. -no-cache skips reads but still updates the cache.
Neither -look nor -prompt contacts providers or uses this cache. Its key
covers rubric/compiler protocol, model and diff text, but excludes surrounding
source and provider routing. Use -no-cache to recompute when those have changed.
Cached token totals describe the original computation.
Use columbo when large diffs recur and a repeatable, compiled reading diff saves
review time. It has a deterministic compiler and offline conformance fixtures,
but abridging remains selective: keep the original diff available for review.
For occasional explanations, your existing agent plus -prompt is a simpler
starting point. Try a few real changes before adding API automation.
Visual explanations are built in. The columbo and meat skills and -agent reviews add the
smallest useful pseudocode, call tree, before/after sketch or Mermaid diagram,
using no platform-specific commands, so they behave the same on Linux, macOS
and Windows. A separate visual skill, such as HumanLayer's
show-me,
can be installed from its upstream source; columbo neither bundles nor requires it.
See the agent workflow for GitHub/GitLab use and durable
project knowledge. Codex discovers AGENTS.md; Claude Code loads it through
CLAUDE.md. The canonical meat skill lives in .claude/skills/meat/; synchronize
the tracked .agents/skills/ and .grok/skills/ copies with npm run skill:sync
after editing it. Grok skill discovery depends on your client; plain chat can
use the exported packet. The installer supports Codex and Claude Code.
npm run check # strict source type-check + tests and conformance vectors
npm run build # distributable JavaScript, declarations, source maps
npm pack # rebuilds before packaging; does not publishTests use local mock HTTP servers and need no live API keys. A sandbox must
allow loopback listeners for the full suite. See AGENTS.md for the
module map and invariants, and decisions for maintained
knowledge. The roadmap owns proposed work.
Git attributes preserve the raw bytes of conformance fixtures and corpus diffs
across checkouts, including Windows with core.autocrlf=true.
TODO.md and migration/ retain historical porting context.
columbo-review is licensed under the Apache License, Version 2.0; see
LICENSE. The Go implementation this project was ported from is meat
by Bold Software, Inc. (boldsoftware/meat),
also Apache-2.0. The TypeScript engine and ported CLI modules carry a derivation
notice, and NOTICE records the upstream copyright and the changes made
here. The meat command, wire kinds and cache variables exist for compatibility;
this project is independent and is not affiliated with or endorsed by Bold
Software. Apache-2.0 does not grant trademark rights, so do not present columbo
as the upstream meat product.