Overview

A chit is a small declared file that captures a routine you already run by hand: which agents take part, in what order, what context flows between them, and where a reviewer checks the work. The runtime reads the chit and runs it, primarily inside a Claude Code conversation over MCP. You stay in the loop and step in where judgment matters.

chit is built for the implement/check loop: one agent implements, another reviews, and chit records what happened. The roles are assigned in the chit, not fixed to a vendor: either Claude or Codex can implement or review, and the permission you grant a participant decides whether it can write. The bundled default pairs a write-capable Claude implementer with a read-only Codex reviewer. Three things you get: a versioned routine, cross-vendor agents, and an audit trail.

The manifest is the artifact. A shared runtime executes it. Surfaces (MCP tools, a CLI command, a Claude Code skill) are thin shims that call the runtime with a manifest and inputs. MCP is the primary surface; the CLI is support tooling.

What this is not

• Not a general workflow engine. No hosted scheduler, no cron, no SaaS connectors, no databases.
• Not a code generator. Manifests are interpreted, not compiled.
• Not an agent framework. We do not define how agents reason; we define how they hand work to each other.
• Not a chat tool. The word is chit, not chat.
• Not a dynamic router. Manifests are static DAGs: no loops, no conditionals. Iteration, when you want it, is driven by an orchestrator on top, never by the manifest.

The three layers

1. Agents. A registry of invocable participants (Codex CLI, Claude CLI, others via adapters).
2. Chits. JSON manifests wiring agents into handoff graphs for a task.
3. Surfaces. Shims that expose a chit as MCP tools, a CLI command, or a Claude Code skill.

Four ways to run it

The same runtime, four execution modes; you choose how much to watch.

• Foreground. Checkpoint every iteration. chit runs one round at a time (chit_start, then chit_next per iteration); you read the diff and the verdict, then advance.
• Background. Run one task unattended. chit_start with mode: "background" converges in a detached worker against a git worktree; check on it with chit_status and read the receipt.
• Plan. Run a reviewed sequence where each step sees the previous applied step's code. chit_plan_start is approval-gated: first dry-run and review the normalized plan plus base, then confirm with the returned approval_hash.
• Batch. Run several tasks in parallel, one worktree each, with declared dependencies. chit_batch_start is approval-gated the same way; the deliverable is a set of reviewable branches.

Safety model

• Codex is hard-sandboxed. Codex runs in an OS-level sandbox chosen by its declared permission: a read-only reviewer runs codex exec --sandbox read-only; a write-capable implementer runs --sandbox workspace-write.
• Claude read-only is permission-level. A read-only claude runs with --permission-mode plan, which blocks writes from inside Claude. It is a Claude plan-mode permission, not an OS sandbox.
• Strict MCP isolation. The chit-spawned claude is launched isolated from your MCP servers by default, so a run does not inherit ambient tools.
• Audit sensitivity. Audit transcripts hold full prompts and outputs and can contain secrets. They live under your local state dir; auditing is on for converge and opt-in elsewhere.
• Worktree discipline. Run autonomous, write-capable work against a git worktree, not your main checkout.

Known limits

• Manifests are static DAGs: no loops, no conditionals, no dynamic routing. Iteration lives in an orchestrator on top.
• Studio cannot run a chit; it is a live control tower for inspecting active foreground loops and background jobs.
• No client-facing token stream over MCP: a long step shows a latest-state heartbeat (best-effort UI), not the model's live tokens. The durable record an agent reads back is chit_status / chit_trace, not the heartbeat.
• chit is not a general workflow engine: no hosted scheduler, no cron, no SaaS connectors, no dynamic router.

Where to go next

• Getting started installs chit, registers the MCP server, and runs your first check.
• Surfaces covers MCP (primary), the CLI, the Claude Code skill, and Studio.
• MCP surface is the authoritative tool reference.
• Concepts explains agents, chits, and surfaces.
• Trigger layer covers what calls chit and when.
• Manifest schema is the reference for what a chit can declare.

Status

Early, and honest about it. The runtime, the CLI, the MCP surface (run tools, batch tools, and audit tools), the Claude Code skill, the Studio live control tower, the convergence log, and the audit log are shipped. Declared human-checkpoint and loop steps inside manifests are not: manifests are static DAGs by design, and iteration lives in an orchestrator on top.