snappy-face

One job: get the operator console on-screen with one command. Starts the head-screen server on port 3147, spawns the snappy-menubar status-bar icon, and opens the console in a Chrome --app window. Idempotent - each step is skipped if its process is already running.

Usage

/snappy-face

Steps

1. Run:

   HEAD_SCREEN_ONCE=1 state/bin/head-screen/launch.sh

1. The script will:

• Start state/bin/head-screen/server.ts on 127.0.0.1:3147 if /healthz doesn't respond.
• Spawn state/bin/head-screen/snappy-menubar if pgrep doesn't find it.
• Open the console in Chrome --app mode (menubar handles this on first launch; otherwise launch.sh opens it directly).

1. Confirm the ⚡ icon is visible in the Mac status bar and the console

window is on-screen.

Why

Three things need to coexist for the console to work: the HTTP server, the menubar health indicator, and the browser window. Running them independently means forgetting one. This wraps all three.

Eval

Shape-gate:

• curl -fsS http://127.0.0.1:3147/healthz returns 200.
• pgrep -f snappy-menubar returns a PID.

Score = 1 if both pass; else 0.

Gotchas

• Requires the menubar binary to have been built once:

bash state/bin/head-screen/build-menubar.sh. The repo ships the binary at state/bin/head-screen/snappy-menubar, so this is only needed if it's missing or stale.

• HEAD_SCREEN_ONCE=1 is important - without it, launch.sh stays

foregrounded waiting on the server; with it, the launcher exits once the window is up and the server keeps running in the background.

• To stop everything: pkill -f "tsx.*head-screen/server" and

pkill -f snappy-menubar.

Rubric

criteria:
  - name: server_healthz_responds
    kind: deterministic
    check: "The command 'curl -fsS http://127.0.0.1:3147/healthz' returns a 200 OK status code."
  - name: menubar_process_running
    kind: deterministic
    check: "The command 'pgrep -f snappy-menubar' returns a Process ID (PID)."
  - name: console_window_visible
    kind: judge
    check: "The operator console window is visibly displayed on the screen as a Chrome --app window."

snappy-face - loader

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

Critical Rules

• Idempotent: if server is up (/healthz 200) and menubar is running (pgrep snappy-menubar), just confirm the window is visible and stop.
• Always pass HEAD_SCREEN_ONCE=1 so launch.sh returns after the window opens.
• Do not start the server in the foreground - it blocks the turn.
• For window-targeted screen capture of non-cockpit apps from headless / SSH / claude --dangerously-skip-permissions chains, direct osascript / screencapture / cliclick silently fail TCC because the responsible client at runtime resolves to claude.exe (no Screen Recording grant). Use peekaboo from its canonical /opt/homebrew/Cellar/peekaboo/3.0.0-beta3/bin/peekaboo install (TCC granted to the canonical path). Pattern:

  # 1. find window id by app name + bounds
  /opt/homebrew/bin/peekaboo list windows --app "<App>" --json
  # 2. capture by window id
  /opt/homebrew/bin/peekaboo image --app "<App>" --window-id <id> --retina --path /tmp/cap.png

No Peekaboo.app/Claude.app MCP bridge socket exists at ~/Library/Application Support/{Peekaboo,Claude,clawdis}/bridge.sock; CLI is the only reachable surface. (writeback 2026-04-29T01:18:10Z)

Commands

| ui dashboard | state/skills/snappy-face/resources/ui.openui | |invoke: HEAD_SCREEN_ONCE=1 state/bin/head-screen/launch.sh |capture-window (TCC-safe): /opt/homebrew/bin/peekaboo image --app "<App>" --window-id <id> --retina --path <out> |find-window: /opt/homebrew/bin/peekaboo list windows --app "<App>" --json |eval log: state/log/evals.ndjson (skill: "snappy-face")

Self-Test

An agent reading this should correctly:

1. [ ] Know the backing script is state/bin/head-screen/launch.sh
2. [ ] Know what to write to state/log/evals.ndjson after invoking (shape-gate on /healthz + pgrep snappy-menubar)
3. [ ] Know the eval mode is auto-shape

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] snappy-face: <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-face: <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.

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/snappy-face/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.