Reference
Running it headless and in CI
One task in, one JSON object out, and an exit code your pipeline can gate on.
csc run --json -- "fix the failing test in internal/auth"No TTY and no approval prompts. A task goes in, one result comes out, and the exit code says whether the run met its contract. In the default permission mode, operations that would need confirmation fail closed instead of waiting for input.
What comes back
--json emits one terminal object. Its top-level contract is:
| Field | Meaning |
|---|---|
ok | Whether the run satisfied the terminal success contract |
run_id, agent | Run identity and selected agent |
final | Final answer, omitted when none exists |
files | Paths changed by the run |
images | Attached image metadata: path, media type, bytes, width, and height |
tools | Sorted distinct tool names used |
tool_calls, tool_call_count | Per-tool counts and total dispatch count |
duration_ms | Wall-clock duration |
error | Terminal error text, omitted when none exists |
summary | Evidence about what actually happened |
What the summary proves
| Field | Meaning |
|---|---|
stopped_reason | Precise terminal cause, such as completed, budget_exhausted, or tool_loop |
budget | Effective wall-clock budget and whether the manifest or an explicit override supplied it |
steps | Number of model calls |
tool_calls | Dispatch count by tool name |
tool_errors | Failure count by tool and error code, with a redacted sample when available |
disabled_tools | Tools withdrawn during the run and the reason |
memory | ContextStream preflight status: ok, degraded, unavailable, or unknown |
edits_attempted, edits_applied | Requested workspace mutations versus mutations that landed |
commits | Successful git commit invocations made through the shell tool |
verification_requested | Whether the task explicitly asked for tests, a build, or linting |
verification_succeeded | Whether recognized verification finished successfully |
verification_commands | Successful commands counted as verification evidence |
This lets automation distinguish “no edit was attempted” from “edits were denied” without reading a journal.
Collections are present as empty arrays when there is nothing to report.
tool_calls entries contain name and count; image entries contain path,
media_type, size_bytes, width, and height.
--stream-json emits journal events as JSON lines and then the same terminal
result object.
The process exits zero only for a successful completed run. A blocked result, denied edits, an exhausted budget, a failed requested verification, or another non-completed stop reason exits non-zero. Gate automation on the exit code and use the JSON for the explanation.
Useful flags
csc run --agent prototyper \
--permission-mode bypass \
--image reference.png \
--timeout 30m \
--json -- "build this screen"| Flag | What it does |
|---|---|
--json | Emit one result object |
--stream-json | Emit journal events as JSON lines, then the result |
--agent <name> | Pick a specialist explicitly |
--permission-mode <mode> | plan, default, auto, or bypass |
--image <path> | Attach a PNG/JPEG reference; repeat up to three, 5 MiB total |
--timeout <duration> | Override the run budget, clamped from 30 seconds to 24 hours |
--no-timeout | Remove the wall-clock limit; the repeated-loop guard still applies |
--quiet | Suppress progress on standard error |
--timeout and --no-timeout are mutually exclusive. An omitted timeout uses
the selected agent's manifest budget. The task can also arrive on standard
input, up to 1 MiB:
printf '%s\n' "review this checkout" | csc run --jsonAuthenticating in CI
Provision ContextCode credentials through the supported dashboard setup flow
and store them as CI secrets; do not copy a developer's whole home directory.
There is no interactive login in an unattended job. Run csc doctor as a
preflight so authentication, project scope, and connectivity failures are
reported before the agent starts.
Delegating from another agent
csc mcpExposes ContextCode as a tool server over stdio, so another agent — Claude Code, Cursor, anything MCP-aware — can hand it work and get the result back. The delegated work still has your project's memory behind it.
Where this earns its keep
- A pipeline step that fixes a lint failure and pushes the fix.
- A nightly job that runs
/reviewover the day's merges. - A scripted migration across many repositories.
- Another agent delegating the parts that need project context.
If it doesn't work
A tool was blocked instead of asking. Headless mode cannot ask. Choose
auto for routine workspace work, add a narrow approval, or use bounded
bypass only in a disposable environment.
Auth fails in CI but works locally. Credentials didn't carry. csc doctor
as the first pipeline step tells you exactly which link broke.
The JSON has an empty field. Collections such as files, images, and
tools are present even when empty. final and error are omitted when they
do not apply.