Headless modes

Headless integrations select json, rpc, or acp with --mode: a JavaScript Object Notation (JSON) event stream, JSON remote procedure call (RPC), or the agent client protocol (ACP). Each mode has a different framing contract; consumers must parse that protocol rather than decorated terminal text.

How do I start with the smallest surface?

xcsh --mode json --no-session --no-tools -p "Return one sentence"

Capture stdout as protocol data and stderr as diagnostics. Pin the xcsh version in automation and test framing against the exact release.

How do I retain and resume a JSON-mode session?

Use a dedicated session directory when the JSON stream must survive process loss:

xcsh --mode json --session-dir /var/lib/my-controller/xcsh-sessions -p "Return one sentence"

The first stdout line is a SessionHeader. Its id is a 16-character lowercase hexadecimal xcsh session ID. With --session-dir, xcsh atomically writes and fsyncs the matching <timestamp>_<id>.jsonl file before emitting that header. The header’s persisted cwd, id, and timestamp are the resumable record. Keep the path discovered in the session directory (or resolve the ID there), then continue through the documented resume argument:

xcsh --resume /var/lib/my-controller/xcsh-sessions/<timestamp>_<id>.jsonl "Continue the task"

--no-session deliberately produces no resumable file or session header. The stream’s wire-only model, provider, and thinking fields describe the launch; they are not additional persisted session-header fields.

When do I use the software development kit (SDK) instead?

Use the SDK when the host process needs in-memory session control, tool registration, or provider events. See SDK automation.

Choose the boundary by ownership: JSON is a one-way event transcript, RPC supports a controlling client, ACP integrates an editor or agent host, and the SDK shares a process. Never parse progress text as protocol data. On shutdown, wait for the protocol’s terminal event, close the input stream, and verify the child exits. Remove the dedicated session directory only when its retained transcript is no longer needed.