Pointing an agent at Kichma

An agent with a prompt invents context. An agent with Kichma reads the brief, the requirement it implements, and the decisions already taken — then builds against a definition of done it did not have to guess.

Any agent that can run a shell command can use Kichma: Claude Code, Cursor, Codex, CI, your own harness. Every command takes --json, so the same surface serves an agent, a person and a pipeline. There is nothing to install beyond npx.

The loop, in three commands

Most of an agent's session is this. The first command is run once; the other two repeat per task.

$npx -y kichma@1 context            # read the project once, at session start$npx -y kichma@1 tasks --available  # what can be claimed, ranked$npx -y kichma@1 pickup T-42        # claim it, cut task/T-42-…, print the brief

context and brief are both generated live from the graph at read time, which is the point: there is nothing to keep in sync, and a committed copy of either is the drift this product exists to kill. Read them per session rather than caching them in a file.

Teach it once, in AGENTS.md

Rather than instructing an agent every session, commit the loop to the repo. Kichma maintains a section of AGENTS.md between two markers and never touches the rest of the file — connect a repo and it opens a pull request adding this:

<!-- kichma-cli: v1 grammar -->## KichmaWork in this repo is planned in Kichma — **Acme Web**: https://kichma.ai/p/acme-webBefore you start:1. `npx -y kichma@1 context` — what we're building, who it's for, the architecture, and what's in flight. Live; read it once per session.2. `npx -y kichma@1 tasks --mine` — what's assigned to you (`--available` for work you can claim).3. `npx -y kichma@1 pickup <KEY>` — claims the task, creates its `task/…` branch, and prints the brief. Build to its Definition of Done.One task = one branch = one PR; merging the PR completes the task. Don't start work that has no task.If you have to decide something the documents don't answer — a language, a library, a tradeoff —record it: `npx -y kichma@1 decide "<what you chose>" --why "<why>" --instead "<what you rejected>"`.It is queued for review, not written: the plan changes only when someone here accepts it.If you find something the codebase has been doing all along that no document records — a language,a framework, a convention — record it with the commit that established it:`npx -y kichma@1 decide "<what it is>" --why "<why>" --since <commit-sha>`. The date is read from thatcommit, so the entry says when it took effect AND when it was finally written down. Never guess adate; there is no flag for typing one.If something in scope can't be built now — no device to test on, a date that moved — don't drop itand don't quietly build around it:`npx -y kichma@1 defer "<what>" --to "<milestone>" --move <KEYS> --constraint "<what the work now must not foreclose>"`.Also queued for review. A deferral moves the plan, never the promise: the requirement keeps askingfor it, so it stays outstanding until the deferred work ships.If you find work no task covers — a bug on the way, a backend nobody planned, a follow-up a fixleaves behind — propose it rather than doing it unplanned or leaving it in a comment:`npx -y kichma@1 propose "<task>" --implements <R-KEY> --size <S|M|L> --acceptance "<what done means>"`.It lands in the milestone of the task you're on unless `--milestone` names another, and it isqueued for review like the rest. It needs a requirement that already asks for the work; if nonedoes, say so to whoever drives the plan instead._Kichma maintains this section — edits between these markers are overwritten. The rest of this file is yours._<!-- /kichma-cli -->

Everything outside the markers is yours and is preserved byte for byte. The opening marker carries the grammar version, so a section written against an older CLI is detectable rather than silently stale.

What an agent is allowed to change

An agent can record anything and decide nothingEvery write from the terminal is parked as a pending proposal for a human to accept or discard.

This is the asymmetry the whole integration rests on. decide, defer and propose all look like writes and none of them reach the graph: they return 202 pending_review and wait. So an agent can record a decision it took, flag scope it could not build, and propose work it found — and still cannot rewrite the plan, move a date or alter a requirement.

What it can do unsupervised is the low-blast-radius half: reading, logging, claiming a task, and cutting a branch. Status comes from merged pull requests rather than from anyone asserting it, including an agent.

Agents authenticate as themselves, acting on behalf of a named person, and appear in the audit trail that way — not as the person. A write with nobody behind it is recorded as unattributed rather than attributed to a guess.

The HTTP API

A harness that would rather not shell out can call the same endpoints the CLI calls. They are the only programmatic surface today, and the CLI is a thin client over them.

Authenticate with the device credential kichma login writes to ~/.kichma/credentials (mode 0600), as a bearer token:

$TOKEN=$(jq -r .accessToken ~/.kichma/credentials)$$curl -s https://kichma.ai/api/v1/tasks/T-42/brief \$  -H "Authorization: Bearer $TOKEN"

GET /api/v1/context: The project: thesis, who it is for, requirements and their status, architecture decisions, constraints, and what is in flight. What kichma context prints.
GET /api/v1/tasks?filter=mine: Tasks assigned to the credential holder and not yet finished. filter=available gives the ranked claimable queue instead.
GET /api/v1/tasks/:key/brief: One task's brief: what to build, the definition of done, the Why-trace, components touched, dependency status. Markdown by default — add ?format=json for a parsed shape.
POST /api/v1/tasks/:key/pickup: Claim a task. Returns the brief and the branch name to cut.
POST /api/v1/decisions: Record a decision taken while building. Parks a proposal; returns 202 pending_review.
POST /api/v1/task-proposals: Propose a task found while building. Parks a proposal.
POST /api/v1/deferrals: Propose moving scope to a later milestone. Parks a proposal.

Scope works as it does in the CLI: pass ?repo=owner/name to narrow to the project a checkout belongs to, ?project=<id> to name one outright, or neither to span your org. A project you are not a member of answers 404, never 403 — so a probe cannot confirm that another org's project exists.

In CI

kichma scan runs with nobody signed in, authenticated by a KICHMA_SCAN_TOKEN set as a CI secret. It reads the checkout and queues a status verdict per imported task — confirmed by the code, contradicted by it, or settled neither way. Like every other write, the verdicts are queued for review; a scan cannot set a status by itself.

Pin the major version

kichma@1 is the frozen v1 command grammar. An agent instruction, a committed AGENTS.md or a CI job that pins the major keeps working across releases; one that floats will eventually read a changed grammar in the middle of a task — and an agent has no way to notice that the command it was taught no longer means what it meant. The published AGENTS.md section pins it for this reason, and so should anything you write by hand.

The loop, in three commands#

Teach it once, in AGENTS.md#

What an agent is allowed to change#

The HTTP API#