corpus-cli
Optional command-line help for the corpus workflow. The framework is just markdown and conventions; the CLI does the chores — checks your specs, isolates each task in its own git worktree, reconciles a finished run against the diff, and prints the board.
It handles the chores around the work, not the judgment. Skip it entirely if you would rather drive by hand.
# not on npm yet — clone, build, and link from source; the binary it provides is called corpus
$git clone https://github.com/jcosta33/corpus-cli.git && cd corpus-cli && npm install && npm run build && npm link
# then run commands as
$ corpus --help
# scaffold a workspace first — see Get started
$ corpus check # lint a spec or the whole workspace; exit 0/1/2
$ corpus worktree create auth-refresh --task TASK-12 # isolate the task on its own branch
$ corpus review TASK-12 # reconcile the finished run — diff vs report vs spec
$ corpus status -i # the board — specs, tasks, reviews, gaps
Commands that already dispatch
Every command that ships, listed below. In the CLI, “advertised equals dispatchable” is a tested invariant — what the help prints, the binary runs. The two worth knowing first: corpus check drops into pre-commit and CI on its exit code, and corpus reviewreconciles a finished run — the agent's self-report against the real diff against the spec — and routes the mismatches to a human, without deciding whether the change is done.
corpus init [dir]
Scaffold the workspace into a new or existing repo, conflict-safe — walked through on Get started.
corpus update [--check|--write]
--check tells you whether your workspace drifted behind the latest starter kit (read-only). --write refreshes the kit-owned guidance — templates, skill guides, hooks — conflict-safe (a customized file is backed up, never lost). Your specs, tasks, reviews, board, and AGENTS.md are yours; --write never touches them.
corpus check [file]
Lint a spec, or print the whole-workspace check summary. Exit 0 clean / 1 warnings / 2 blocking — so it drops straight into pre-commit and CI.
corpus worktree
Create / list / remove / prune isolated git worktrees — one per task on corpus/<slug>, so parallel agents never trample each other.
corpus status
Print the workspace board — specs, tasks, reviews, and the gaps between them. --json for scripts, -i for an interactive board.
corpus review <task>
Reconcile a finished run — the agent's self-report against the actual git diff against the spec. Surfaces omitted edits, out-of-scope changes, and unbacked claims.
corpus new <task|spec>
Cut a task packet from a spec (scope never invented), or scaffold a fresh spec from the template.
corpus pull <ref>
Snapshot an external ticket into intake/ — verbatim, never a spec or the board. Turning a ticket into requirements is your call, not transcription.
corpus promote <task>
Scaffold a candidate finding from a finished task, source pre-filled. It asserts no lesson — you decide what was learned.
corpus run <task> --agent <name>
Launch a prepared task on your own coding agent in its worktree and record the launch. It runs the agent; it never becomes one — no model loop, no edits of its own.
corpus show <task|spec|review|checks>
Project a parsed artifact as JSON. It is how editors, CI, and corpus-mcp read your workspace.
corpus agents emit --codex
Generate Codex .codex/agents/*.toml from your Claude Code agent definitions — one source, generated for a second runner. Only the prose discipline ports; tool-scoping and hooks are Claude-Code-only, and every emitted file says so.
Why a CLI if corpus is markdown-only?
The workflow itself is just conventions and files — you can run all of corpus with a text editor. The CLI is optional: it scaffolds the workspace, runs the checks in CI, and keeps one worktree per task so parallel agents do not trample each other. It is a helper, not an orchestrator. Use it for less typing; ignore it if you would rather orchestrate by hand.
One worktree per task
No more agents rewriting your main checkout while you are halfway through something else.
Markdown is the source of truth
The spec, the task, the evidence, the review — plain files you can read, diff, and grep. The CLI reads them; it does not replace them.
It reports checks, not decisions
corpus check tells you what is malformed or unverified. Whether the code is done is still a review decision.
Don't need the CLI yet?
The whole workflow runs in plain markdown. Copy the starter kit and write a spec — add the CLI later, if and when the typing starts to annoy you.
Reference repository
The CLI is developed in the open. Issues, feature requests, and adversarial review are all welcome.
Read the full reference on GitHub →
Using an MCP-capable client? corpus-mcp exposes the same read and reconcile facts without adding verdict authority.