How to drive Claude Code headless in CI with structured JSON

FlowAgent

❯_

Do this with Claude CodeCopy a prompt that links the cckit docs so Claude learns the CLI, then follows these steps.

Copy as Markdown

Before you start

Install cckitQuickstart: your first lifecycle

This tutorial

Advanced6 min readNeedscckit installed & initializeda CI runner or scheduled job

What you’ll do: run cckit with no human watching — a CI bot or scheduled run that reads state as structured data instead of scraping human output. Every verb that reports state takes --llm, so the agent reasons over JSON (and TOON), picks the highest-priority unblocked issue, and drives it start to finish.

Steps

1. Prime the headless agent. Tell it there’s no human and to consume data, not prose.

   Prompt to paste

   You're running headless — no human watching. Work the board through to merged on your own: read
   state as structured data, pick the highest-priority unblocked issue, and drive it start to finish.
   Keep token use lean when you hand context to sub-agents.

2. Consume every verb as data.

   cckit sync --llm          # board state + what's unblocked, as TOON
   cckit scan --llm          # repo stack + kit state, as JSON
   cckit plan --llm          # the session-fit wave plan, as TOON

3. Compact context for sub-agents. Pipe uniform arrays through encode-context so hand-offs stay token-lean:

   echo "$json" | cckit encode-context   # compact uniform arrays into TOON for sub-agents

How it works

cckit is agent-operable by design: every verb has a machine-readable mode and the repo ships an AGENTS.md contract, so an agent reasons over structured data instead of scraping human output. Point the agent at AGENTS.md once and it knows the grammar; --llm then gives it the board, the stack, and the plan as JSON/TOON it can act on without a human in the loop.

TOON keeps hand-offs cheap

encode-context compacts uniform arrays into TOON — a denser encoding than raw JSON — so passing context to sub-agents costs fewer tokens.

Troubleshooting

A verb printed human output in CI. Add --llm. Only the reporting verbs take it; if one still prints prose, you’ve hit a verb that doesn’t report state (it just acts) — that’s expected.

The agent doesn’t know the verbs. It hasn’t read the contract. Have it read AGENTS.md and cckit.config.json once at the start of the run.

Hand-offs are burning tokens. Pipe the JSON through cckit encode-context before handing it to a sub-agent; TOON is materially smaller than the equivalent JSON.

Related tutorials

Run Claude Code unattended The attended-but-hands-off sibling of a headless run.

Set up cckit in a repo Get the config the --llm verbs resolve against.

Run issues in parallel with a wave Fan out work once the board is read as data.