Status Line

The Guild status-line shows you where you are in the lifecycle at a glance — active phase, current loop round, cap, loops mode, and restart count — as a single line beneath your Claude Code prompt.

The script is opt-in — with default flags it never runs.

When to enable it

Enable the status-line when you want at-a-glance visibility into:

• Which lifecycle phase the orchestrator is in.
• How many loop rounds the active lane has consumed against the cap.
• Whether a restart fired.

Keep it disabled if you don’t run with --loops=... or don’t need per-lane visibility.

Wire-up

Claude Code reads its status-line config from ~/.claude/settings.json. Add a statusLine block pointing at the script:

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

${CLAUDE_PLUGIN_ROOT} resolves to the Guild plugin directory at runtime. Substitute an absolute path to your Guild checkout if you prefer.

Then export the two operator-side environment variables before invoking /guild:guild:

export GUILD_STATUSLINE=1
export GUILD_RUN_ID=<run-id>

• GUILD_STATUSLINE=1 opts into the status-line surface.
• GUILD_RUN_ID tells the script which run to read. The orchestrator exports it before each lifecycle phase, but exporting it manually in your shell ensures the status-line reads the correct run from the moment Claude Code spawns.

The --statusline CLI flag on the /guild:guild invocation is equivalent to GUILD_STATUSLINE=1.

Output modes

The script emits a single line to stdout, exit 0 always. Three modes fire depending on environment state at the moment the script runs:

Mode A is the steady-state output during a live run.
Mode B is what you see when the variable was never exported — the script does not guess which run is live.
Mode C is the transient state between run-init and the first counter write.

Field meanings (Mode A)

Verify the wiring

Before relying on the status-line, validate that one of the modes fires. The smoke tests below are portable across macOS and Linux.

Mode B (no run id)

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

Expected output:

phase: unknown

Mode C (run id set, run dir empty)

export GUILD_RUN_ID=run-smoke-test
mkdir -p .guild/runs/run-smoke-test
bash scripts/statusline-guild.sh </dev/null

Expected output:

phase: run-smoke-test (initialising)

Mode A (run id set, counters present)

export GUILD_RUN_ID=run-smoke-test
mkdir -p .guild/runs/run-smoke-test
cat > .guild/runs/run-smoke-test/counters.json <<'JSON'
{
  "schema_version": 1,
  "run_id": "run-smoke-test",
  "counters": {
    "l1_round": 2,
    "l2_round": 0
  }
}
JSON
bash scripts/statusline-guild.sh </dev/null

Expected output:

phase: unknown | round: 2 | cap: 16 | loops: none | restarts: 0

The leading phase: unknown is correct — GUILD_PHASE was not exported in the smoke. In a live run, the orchestrator exports GUILD_PHASE before each lifecycle phase.

Clean up after the smoke test:

rm -rf .guild/runs/run-smoke-test

Operator setup paths

Two supported ways to make GUILD_RUN_ID available to the status-line process:

1. Manual export. Before invoking /guild:guild:

export GUILD_RUN_ID="run-$(date -u +%Y-%m-%d)-mybrief"
/guild:guild --statusline "<brief>"

The orchestrator picks up the exported value and uses it as the run dir name.

2. Auto-export from the orchestrator. When GUILD_RUN_ID is unset at invocation, the orchestrator generates a run-id and writes it to .guild/runs/.current-run-id. Subsequent shells can cat that file and export GUILD_RUN_ID=<value> to pick up the same run.

The script reads GUILD_RUN_ID from the environment only — it does not consult .guild/runs/.current-run-id itself. The env var is the single source of truth.

Stdin handling

Claude Code passes a JSON input_json blob on stdin per its status-line convention. The script drains up to 32 KB of stdin (head -c 32768) but does not depend on the contents — env vars are the primary input. Reading stdin prevents Claude Code from blocking on a closed pipe.

What you do NOT need to install

The script is self-contained. It does not require jq. JSON parsing for counters.json runs through an inline node -e block — Node is already a Guild dependency because the hook handlers run on it. No additional installs.

Troubleshooting

Related

• Architecture & Lifecycle — lifecycle phases the status-line surfaces.
• Configuration Reference — settings.json for other runtime options.