agent-statusline

agent-statusline

A fast, single-line status renderer for command-backed agent statusline payloads, written in Zig. It reads one JSON snapshot on stdin and prints one formatted status line on stdout.

Behavior

• Reads statusline JSON from stdin and ignores unknown fields.
• Crash-free by design: any error in a segment degrades to hiding that segment, falling back to ~ in the worst case. A return code of 0 is always produced.
• Empty segments emit zero bytes (no stray separators).
• Renders host/working-directory and git segments from the current workspace, plus an rl loop segment.
• The rl loop segment is delegated to rl statusline (a PATH dependency); the statusline does not read .rl/ state directly.
• --debug or STATUSLINE_DEBUG=1 appends diagnostics to /tmp/statusline-debug.log and shows the numeric context percentage inline.
• STATUSLINE_DEBUG_LOG=/absolute/path.log appends diagnostics to that file without changing visible output.
• STATUSLINE_CAPTURE_DIR=/absolute/dir writes replay artifacts for every render: statusline-*.input.json and statusline-*.output.ansi.
• Claude Code and Codex-style status payloads are supported. Claude models render with their existing glyphs; the GPT-5.6 family renders with model-specific glyphs (gpt-5.6-sol ☀️, gpt-5.6-terra 🌍, gpt-5.6-luna 🌙). Previous-generation Codex glyphs remain supported, with ⌘ as the generic GPT/Codex fallback. Kimi models (kimi-code/*, k3[1m], Kimi K2) render as 🌑.
• Codex goal payloads render active goal attention as 🎯; when tokens_used and token_budget are present, the segment renders compact progress such as 🎯12.5k/50k.
• Reasoning effort renders as an emoji dot dial after the model glyph, graded by compute burn: ⚫ minimal, ⚪ low, 🔵 medium, 🟡 high, 🟠 xhigh, 🔴 max, 🟣 ultra. An emoji badge aligns with the emoji model glyph beside it (partial-height block glyphs read as floating next to baseline-bound text). Claude Code's structured effort.level field is preferred; Codex effort is read from the model-with-reasoning display name (gpt-5.6-sol xhigh). Unset (none/default) or unknown effort hides the badge.
• Activity display is hook-owned: the agent-statusline plugin records UserPromptSubmit as 💬 MM/DD HH:MM and Stop as 💤 MM/DD HH:MM under STATUSLINE_STATE_DIR, XDG_STATE_HOME/agent-statusline, or ~/.local/state/agent-statusline.

See SPEC.md for the full contract (requirements, invariants, segment rules).

Build

Requires Zig 0.16.0+ (the renderer uses the 0.16 std.Io API). The project has no external dependencies.

zig build                          # build -> zig-out/bin/statusline
zig build run                      # run (reads JSON from stdin)
zig build run -- --debug           # run with debug diagnostics
zig build test                     # run unit tests
zig build -Doptimize=ReleaseFast   # optimized build

Quick check:

zig build && ./zig-out/bin/statusline < test/opus.json
zig build && ./zig-out/bin/statusline < test/codex.json
zig build && ./zig-out/bin/statusline < test/codex-goal.json

Use with Claude Code

Build a release binary and point your Claude Code statusLine setting at it (~/.claude/settings.json):

{
  "statusLine": {
    "type": "command",
    "command": "/absolute/path/to/zig-out/bin/statusline"
  }
}

Claude Code pipes the status JSON to the command on stdin and renders its stdout.

Install or enable the bundled plugin in plugins/agent-statusline so activity hooks can update prompt/idle state. The hook wrapper must be able to find the same binary through one of:

• AGENT_STATUSLINE_BIN=/absolute/path/to/zig-out/bin/statusline
• statusline on PATH
• this checkout's default plugins/agent-statusline to ../../zig-out/bin/statusline layout

Claude marketplace metadata lives at ./.claude-plugin/marketplace.json.

Use with Codex

With a Codex build that supports command-backed custom status lines, configure the renderer as the command:

[tui.custom_status_line]
type = "command"
command = "/absolute/path/to/zig-out/bin/statusline"

Codex pipes a JSON snapshot to the command on stdin. Empty, failing, or timed-out renderer output is hidden by Codex.

When the payload includes a goal object with status = "active", the renderer shows an active-goal marker. The Codex fork payload shape is:

{
  "goal": {
    "objective": "...",
    "status": "active",
    "token_budget": 50000,
    "tokens_used": 12500,
    "time_used_seconds": 120
  }
}

The same plugins/agent-statusline plugin supports Codex hooks. A Codex marketplace entry is provided in marketplace.json. The plugin listens for SessionStart, UserPromptSubmit, and Stop and writes neutral activity state consumed by the renderer; no Codex CLI changes are required.

Updating the local Codex plugin