Getting started

chit runs under Bun. The day-to-day surface is MCP inside Claude Code: you register chit once, then ask for a routine in the conversation. The CLI ships in the same package for inspection, audits, and running the loop from a terminal.

Install

Requires Bun.

bun install -g @chit-run/cli@latest

Upgrade later with the same command: bun install -g @chit-run/cli@latest. During 0.x, bun update -g will not cross a minor version, so re-running the install is the reliable way to get the latest.

Check your setup

chit doctor

chit doctor is a preflight. It checks Bun, the chit binary on PATH, the codex and claude CLIs, the agent registry, MCP registration, the audit directory, and whether the current directory is a git repo, and reports each as pass, warning, or failure with a fix. It runs no agents; it writes and removes one probe file in the audit dir to confirm that dir is writable, and changes nothing else. Agent authentication is confirmed on the first real run, not here.

Register the MCP server

claude mcp add chit --scope local -- chit mcp

chit mcp launches the stdio MCP server from the installed binary. Reconnect in Claude Code (/mcp) and the chit_* tools are available.

Run your first check

In a Claude Code conversation, in a git worktree:

Use chit to start a run that converges on this task: <a small, scoped change>. Run a couple of iterations and show me the audit trail.

chit opens the run with chit_start (a bare task uses the built-in loop), then each chit_next runs one iteration: the implementer makes the slice, the reviewer checks the diff, and chit reads the verdict. By default the implementer is a write-capable Claude and the reviewer is a read-only Codex, but the roles are assigned in the chit, not fixed to a vendor (see self-hosting). Inspect with chit_status and chit_trace; read a transcript back with chit_audit_list / chit_audit_show. You see what ran, what the reviewer said, and the token usage. No copy-paste between terminals.

This first run is in foreground mode: one iteration per chit_next, with you reading each diff, holding one run_id the whole way. The same run goes unattended with mode: "background" (a detached worker drives it to completion; chit_wait blocks until it finishes, or chit_status for a snapshot, and chit_cancel stops it), and several tasks run at once as a batch (one git worktree each, with dependencies). See the MCP surface.

The implementer edits files, so run this against a git worktree, not your main checkout. For a read-only fan-out instead of the loop, run a manifest like examples/consult.json: chit_start with a manifest_path (its one-shot policy is a single DAG pass), then chit_next advances the ready wave.

Inspect a chit before it runs

A chit is a JSON manifest. show renders one without executing it, in any of four views.

chit show examples/consult.json            # ASCII graph
chit show examples/consult.json --json     # JSON
chit show examples/consult.json --mermaid  # Mermaid

Run a chit from the terminal

The CLI runs the same runtime as the MCP surface. From a source checkout with the example manifests:

git clone https://github.com/caiopizzol/chit
cd chit
bun install
bun run cli run examples/consult.json --scope work-session --input question="..."

The run prints what ran: the resolved manifest, the adapters, the validation result, and the execution order. No chat log.

Next

• Surfaces for MCP, the CLI, the Claude Code skill, and Studio.
• MCP surface for the authoritative tool reference.
• Self-hosting for the implement/check loop.
• Concepts for the model behind agents, chits, and surfaces.