Claude Code status line

The Guild Stack status line is a short, opt-in Claude Code prompt readout for active runs. Use it when you want pane-level loop visibility; use /guild:status, Observability, and Configuration for the main run and settings references.

Status linestrip_status_line_strip

Operational mapThe active run stays glanceable.

1. R-01RUN ACTIVE
2. R-02BUILDphase
3. R-03R2 / 3round
4. R-04NORMALloop
5. R-05RESTART 0recovery

This is intentionally narrow. It does not replace the dashboard, trace logs, or the lightweight /guild:status command.

Enable It

There are two pieces:

1. Tell Claude Code to invoke the script through user-level statusLine config.
2. Tell Guild Stack to allow output by enabling the statusline setting or exporting GUILD_STATUSLINE=1.

Claude Code config:

{
  "statusLine": {
    "type": "command",
    "command": "${CLAUDE_PLUGIN_ROOT}/scripts/statusline-guild.sh"
  }
}

Guild Stack config:

/guild:config set statusline true --scope project

Single-shell manual gate:

export GUILD_STATUSLINE=1

Without one of those Guild Stack gates, Claude Code may invoke the script, but the script exits quietly.

Output Modes

Mode	Triggered when	Output
Off	GUILD_STATUSLINE is not 1	no output
A	GUILD_STATUSLINE=1, GUILD_RUN_ID set, and run-dir/counters.json exists	phase, round, cap, loops, restarts
B	GUILD_STATUSLINE=1, but GUILD_RUN_ID is unset or empty	phase: unknown
C	GUILD_STATUSLINE=1 and GUILD_RUN_ID set, but run-dir/counters.json is missing	phase: run-id (initialising)

Mode A is the steady-state output during a live run. Mode B means the status line is enabled but no run id reached the status-line process. Mode C is the transient state between run start and the first counter write.

Field Meanings

Field	Source	Notes
phase	GUILD_PHASE env var	rendered verbatim when set; unknown when unset
round	run-dir/counters.json	lane round when GUILD_LANE_ID is set; otherwise orchestrator round
cap	GUILD_LOOP_CAP env var	defaults to 16
loops	GUILD_LOOPS env var	defaults to none
restarts	run-dir/counters.json	per-lane restart count, or 0 when no lane is active

GUILD_RUN_ID is generated by the Guild Stack runner when a run starts. For a separate shell, point it at the active run after the run has started:

export GUILD_RUN_ID="$(cat .guild/runs/current-run-id)"
export GUILD_STATUSLINE=1

The script reads GUILD_RUN_ID from the environment only; it does not consult .guild/runs/current-run-id itself.

Quick Verification

unset GUILD_STATUSLINE
bash scripts/statusline-guild.sh </dev/null

Expected output: nothing.

export GUILD_STATUSLINE=1
unset GUILD_RUN_ID
bash scripts/statusline-guild.sh </dev/null

Expected output:

phase: unknown

The script is self-contained and does not require jq. JSON parsing for counters.json runs through an inline node -e block.

Troubleshooting

Symptom	Likely cause	Fix
Status line is blank	Claude Code is not invoking the script, the path is wrong, or GUILD_STATUSLINE is not 1	Add the statusLine JSON block, verify the script path, and enable statusline.
phase: unknown while run fields show correctly	GUILD_PHASE is not set	Set GUILD_PHASE=label if you need a phase label.
phase: unknown and no run fields	GUILD_RUN_ID did not reach the status-line process	Set it from .guild/runs/current-run-id after the run starts.
phase: run-id (initialising) never advances	counters.json has not been written	Check .guild/runs/run-id/logs/v1.4-events.jsonl for run errors.
Script errors in Claude Code	Permission bit missing	chmod +x scripts/statusline-guild.sh

Source Truth

• docs/v2/config-surfaces.md - statusline is a closed boolean key with default false.
• docs/v2/observability.md - /guild:status remains the lightweight status run surface.
• docs/v2/architecture/modules/telemetry.md - trace and status/report context.

Related

• Observability - run traces, status/report surfaces, and dashboard links.
• Configuration Reference - .guild/settings.json, statusline, and other runtime options.