Skip to content

Input/Output Contract

  • Date: 2026-08-02
  • Status: Approved (2026-08-02, ADR-0009)

Invocation

Claude Code invokes the statusline command per event (session start, resume, new message, /compact, permission change), debounced to ~300 ms, and writes a JSON payload to stdin. The statusline is a short-lived process per invocation; it is stateless across invocations (04-caching-timeout-policy.md).

Input (stdin)

One line of JSON. The statusline consumes only the fields below; all other fields are ignored.

Field Used for Notes
model.display_name \|\| model.id Requested model — fallback display only Verified present; equals the configured ANTHROPIC_MODEL (auto/cheap) in this installation
transcript_path Read the transcript tail for the resolved model Verified present (path to the session JSONL)
cwd Git branch segment Verified present
context_window.used_percentage Context usage segment Verified present after the first API call
context_window.context_window_size Window-size segment Verified present after the first API call
context_window.current_usage.input_tokens / output_tokens Token segment Verified present after the first API call
session_id Diagnostics only; never displayed Verified present

Unparseable or empty stdin → write an empty string and exit (baseline behavior preserved).

Transcript read (the resolved-model source, ADR-0005)

  • Open transcript_path and read a bounded tail of the file (bounded I/O, as the architecture requires; the concrete window size is an implementation constant — currently 256 KB; the current transcript is ~396 KB and grows per session).
  • Walk backward from the end; find the last type: "assistant" message object.
  • Read the resolved model at message.model, falling back to top-level model (ADR-0008: the field relocated between Claude Code versions).
  • Malformed JSON lines are skipped; the last parseable assistant message is used.
  • A line whose assistant message lacks both message.model and model is treated as "no resolved model" on that message; the walk continues to the previous assistant message, then falls back to the requested label.
  • No assistant message found in the tail → resolved route unknown → display the requested label.

Output (stdout)

  • A single line, no trailing newline, bounded length.
  • Segments joined by two spaces in the order defined in 01-display-requirements.md.
  • Any runtime error in a segment omits that segment; any total failure writes an empty string.
  • Timeout/cancellation: Claude Code cancels over-budget scripts and nothing is rendered (documented Claude Code behavior; the design must complete within budget — the transcript path is sub-ms).

Error contract (summary)

Condition Behavior
stdin unparseable empty output; exit 0
transcript_path missing or unreadable requested label from the payload; no crash
no assistant message in transcript tail requested label
malformed transcript line skip it; use the last parseable assistant message
message.model absent (and no top-level model) previous assistant message; then requested label
provider enrichment unavailable or times out model-only display (03-provider-model-naming.md)
script exceeds the cancellation timeout Claude Code cancels; nothing rendered