snappy-statusline

A one-line readout of the substrate's live state, rendered under the Claude Code prompt. Answers the moment-to-moment question: "is the autopilot still swinging? was the last push recent? did doctor go red?"

What it shows

▲ autopilot:on 2m  recipes:4  goals:1  push:13m  doctor:20/21  ● smoke-ubuntu
                                                                ^^^^^^^^^^^^^
                                                                "tail slot"

Base fields:

• ▲ / △ green / dim triangle - autopilot engaged vs. disengaged
• autopilot:on - recipe engaged and a tick has fired recently
• autopilot:stale - recipe engaged but no tick for >20 min (cron missing?)
• autopilot:OFF - disengaged in state/engaged.json
• <N>m after the icon - age of the last autopilot tick
• recipes:N - how many recipes are engaged
• goals:N - how many goal files open in state/goals/
• push:Xm - how long since last successful push (mtime of sync-manifest)
• doctor:P/T - lints passing from the last doctor run (cached)

Tail slot (at most one; priority order):

• ● tick 42s (cyan) - an autopilot subagent is currently running; elapsed

seconds count up in real time as its transcript gets written

• ● <area> (red) - a p0/p1 friction was logged in the last 10 min; shows

the area tag so you know what jammed (e.g. smoke-ubuntu, worker-deploy)

• ✎ <skill> <score> (magenta) - the last eval row: what was run, what it

scored. Idle-state signal: "the system is alive, here's what it just did"

• blank - nothing happening worth surfacing

Why it exists

The substrate is mostly invisible in a terminal. You can go an hour without knowing the autopilot died, or that doctor dropped from 21/21 to 15/21 because someone edited a skill and forgot to push. The statusline surfaces those signals without you having to ask.

It's also a self-check: if the line stops updating, Claude Code isn't calling the hook, which means something upstream is broken before you've even typed.

Files

• state/bin/statusline.sh - the renderer. Pure bash, no node, reads only

local files (state/engaged.json, state/log/goals/*.ndjson, state/log/sync-manifest.json, state/log/doctor-last.json). Never hits the network; a slow statusline is worse than a missing one.

• state/log/doctor-last.json - cache written by bin/cli.js doctor. Shape:

{ts, pass, fail, fails: string[]}. Atomic write via .tmp + rename.

Wiring

Claude Code:

// ~/.claude/settings.json
{
  "statusLine": {
    "type": "command",
    "command": "~/projects/snappy-os/state/bin/statusline.sh",
    "padding": 0
  }
}

Codex CLI, Gemini CLI, OpenClaw - no native statusline hook observed. If they grow one, point it at the same script. Same output is valid anywhere.

Do not emulate the byline in Codex with UserPromptSubmit. Codex treats that output as per-turn developer context, and repeated prompt-visible context is the exact failure mode this statusline is supposed to avoid.

Eval

The statusline succeeds if:

• Render time <100ms (measured with time state/bin/statusline.sh).
• Every field either shows a value or - / ?/? (never blank).
• doctor:P/T matches the last doctor run's actual pass/total.
• autopilot:stale triggers within 20-25 min of the last tick age.

Log eval rows to state/log/evals.ndjson with skill: "snappy-statusline".

Known edge cases

• Fresh machine: no doctor-last.json yet → shows doctor:?/?. Resolves on

first snappy-os doctor run.

• Fresh machine: no sync-manifest.json → shows push:-. Resolves on first

snappy-os push.

• Autopilot recipe engaged but cron not installed: shows autopilot:stale

after 20 min. Treat that as the signal to run crontab -l and check.

Rubric

criteria:
  - name: render_time_under_100ms
    kind: deterministic
    check: "The execution time of `state/bin/statusline.sh` must be less than 100ms when measured with `time`."
  - name: no_blank_fields
    kind: judge
    check: "Every field in the status line output, including base fields and the tail slot, must show a value (e.g., 'on', '4', '13m', '20/21') or an explicit placeholder character like '-' or '?/?', never an empty space where a value is expected."
  - name: doctor_score_accuracy
    kind: deterministic
    check: "The 'doctor:P/T' output must accurately reflect the 'pass' and 'total' values from the most recent `state/log/doctor-last.json` file."
  - name: autopilot_stale_trigger
    kind: judge
    check: "If a recipe is engaged but no tick has fired for 20-25 minutes, the status line must display 'autopilot:stale' to indicate a potential issue."

snappy-statusline - loader

Per-turn rules for the snappy-statusline skill. Full reference: state/skills/snappy-statusline/SKILL.md. Do not skip these.

Critical Rules

• NEVER make the statusline hit the network. Reads only local files. A slow statusline is worse than a missing one (<100ms render).
• ALWAYS show - or ?/? for unknown fields, never blank - the line being parseable matters more than completeness.
• ALWAYS write state/log/doctor-last.json atomically (.tmp + rename). A torn write blanks the doctor field.
• The script is state/bin/statusline.sh - pure bash, no node, no npx tsx.

Commands

| ui dashboard | state/skills/snappy-statusline/resources/ui.openui | |invoke: state/bin/statusline.sh (called by Claude Code via settings.json statusLine.command) |verify: time state/bin/statusline.sh - must complete <100ms |wire: ~/.claude/settings.json → statusLine: {type:"command", command:"~/projects/snappy-os/state/bin/statusline.sh", padding:0} |eval log: state/log/evals.ndjson (skill: "snappy-statusline")

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/snappy-statusline/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Fresh machine has no doctor-last.json → field shows ?/? until first snappy-os doctor run. Do not panic; do not synthesize a value.
• Fresh machine has no sync-manifest.json → push:-. Resolves on first push.
• autopilot:stale triggers when last tick age >20min. That's the signal to check crontab -l - the recipe is engaged but cron isn't firing.
• Tail slot priority: tick > friction > last-eval > blank. Do not show two.
• Other runtimes (Codex, Gemini CLI, OpenClaw) have no statusline hook today - point them at the same script if/when they grow one.

Self-Test

An agent reading this should correctly:

1. [ ] Refuse to add a network call inside the renderer
2. [ ] Use .tmp + rename when updating doctor-last.json
3. [ ] Know the statusline script path is state/bin/statusline.sh

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] snappy-statusline: <what was missing>" >> state/log/loader-feedback.log

<!-- kernel-ok: historical attribution for the PID-loader pattern. -->

Self-correcting loader (PID feedback)

This is the rule that makes loaders learn. Ported from snappy-kernel, where it demonstrably worked: the snappy-dom-cartographer skill mapped Skool admin UI once, every later ship-agent inherited the full map for free.

Before you finish, do two things:

1. Fix gaps (P - proportional). MANDATORY. If this loader didn't cover your case - if you had to read another file, run an undocumented command, work around a wrong selector, or discover a quirk - you MUST attempt an Edit to this AGENTS.md before you log.

• Default action: edit this file. Surgical. Add the missing line, table

row, or code example where it belongs. No restructuring.

• Only LOGGED is allowed when: the fix needs >10 lines, spans multiple

files, or requires a structural rewrite. In that case the state/regen/drain.sh queue picks it up asynchronously.

• "I didn't have time" / "it's minor" / "the next agent will figure it out"

are NOT valid reasons. Minor gaps compound - that's the whole point of this loop.

• Concrete example of a valid P-fix: discover agent-browser screenshot

takes path positionally not as --output <path>. One line in a table. Edit it in. Do not just log it.

• The goal: the next agent never has to leave the loader.

2. Log the result.

echo "[$(date -u +%FT%TZ)] snappy-statusline: <what was missing or fixed> [FIXED|LOGGED]" >> state/log/loader-feedback.log

• FIXED = you patched this loader inline (P-fix).
• LOGGED = too large for inline; the PostToolUse enqueue + Stop-hook drain

will rewrite the loader from scratch on next session-end.

Do not skip this. Every agent run must leave the system better than it found it. The loader is the setpoint; you are the sensor; the gap is the error signal; closing the gap is the correction.