snappy-run

One job: fire a snappy-os agent immediately, on demand. The byline points the operator here when an agent is overdue or broken.

Usage

/snappy-run <abbr-or-name>

<abbr-or-name> matches either the 3-letter abbr (swp, brk, fix, ...) or the pretty name (inbox-sweep, breaker, fixer, ...) from state/bin/byline/agents.sh.

If invoked with no argument, list every agent + its abbr + cadence so the operator can pick.

Steps

1. Source ~/projects/snappy-os/state/bin/byline/agents.sh to load the AGENTS

catalog.

1. Match the argument case-insensitively against abbr (field 1) or pretty

(field 3). On no match, list all 12 agents and exit.

1. Extract run_cmd (field 5) and spawn it in the background with output

redirected to /tmp/snappy-run-<label>-<ts>.log. Use nohup ... & and capture the PID.

1. Append a row to state/log/notify.ndjson:

{ts, label, kind:"run-start", note:"manual via /snappy-run pid=<pid>"}.

1. Report back to the operator:

• the agent that was launched (emoji + pretty name)
• the PID
• the tail command they can paste: tail -f /tmp/snappy-run-<label>-<ts>.log
• a one-liner to check if it's still alive: ps -p <pid>

1. Log eval row to state/log/evals.ndjson:

{ts, skill:"snappy-run", verb:"run", score: 1 if spawn-succeeded else 0, label}

Why

The byline names overdue/broken agents but the byline can't run anything - it's read-only. Operator needs a one-prompt verb to fire the agent without leaving Claude Code or memorizing 12 different cron paths.

Eval

Shape-gate:

• Spawn returns a non-empty PID.
• Background process is alive 1s after spawn (ps -p $pid exits 0).
• /tmp/snappy-run-*.log was created.

Score = 1 if all three pass else 0. Append to state/log/evals.ndjson with skill: "snappy-run", verb: "run", label: <agent label>.

Gotchas

• Do NOT run the agent inline (bash ... blocking) - Claude Code waits for the

bash tool to return, but cron agents run for minutes. Always background.

• Use nohup so the process survives Claude Code session end.
• Some agents have their own lockfile (/tmp/claude-cron-<label>.lock); a

duplicate spawn is a no-op, not an error. Treat that as score=1.

• inbox-sweep writes to $HOME/.claude/logs/linkedin-sweep.log not

/tmp/...; the catalog's live_log field (7th column) tells you which. Tail that one if non-empty.

Rubric

criteria:
  - name: agent_spawned_correctly
    kind: deterministic
    check: "Verify `ps -p <PID>` returns 0 for the reported PID 1 second after skill execution and a log file was created at `/tmp/snappy-run-<label>-<ts>.log` or the `live_log` path if specified."
  - name: notification_logged
    kind: deterministic
    check: "Verify `state/log/notify.ndjson` contains an entry `{ts, label, kind:\"run-start\", note:\"manual via /snappy-run pid=<pid>\"}` matching the executed agent and PID."
  - name: operator_report_complete
    kind: judge
    check: "The skill's output to the operator includes the agent's pretty name, PID, `tail -f` command, and `ps -p <pid>` check."
  - name: eval_log_written
    kind: deterministic
    check: "Verify `state/log/evals.ndjson` contains an entry `{ts, skill:\"snappy-run\", verb:\"run\", score: 1, label: <agent label>}` if agent spawn was successful."

snappy-run - loader

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

Critical Rules

• NEVER run cron agents inline (bash state/bin/<agent>) - Claude Code's bash tool blocks until completion; cron agents run for minutes; a 5-minute block looks like a hang
• ALWAYS spawn with nohup ... & and capture the PID - agents must survive Claude Code session end
• Lockfile collision is SUCCESS, not failure - /tmp/claude-cron-<label>.lock collisions return immediately as a no-op; the agent IS running, score it 1 (filing as failed spawn pollutes the eval log)
• ALWAYS read live_log (field 7) from state/bin/byline/agents.sh - do not assume /tmp/snappy-run-<label>-<ts>.log. Examples: inbox-sweep → $HOME/.claude/logs/linkedin-sweep.log. If field 7 is non-empty, tail THAT
• ALWAYS log a notify row + eval row after spawn - without these, byline can't see manual runs and the PID loop can't credit the skill

Commands

| ui dashboard | state/skills/snappy-run/resources/ui.openui | |invoke: prose skill - follow steps in state/skills/snappy-run/SKILL.md |catalog: state/bin/byline/agents.sh (source it, match arg case-insensitively against abbr field 1 or pretty field 3) |notify log: state/log/notify.ndjson - append {ts, label, kind:"run-start", note:"manual via /snappy-run pid=<pid>"} |eval log: state/log/evals.ndjson (skill: "snappy-run", verb: "run") |append helper: state/lib/log.ts (TS) or printf '%s\n' '<json>' >> <file> (shell)

OpenUI Resource

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

• Inline bash instead of nohup ... & looks like a hang to the operator
• Defaulting to /tmp/snappy-run-<label>-<ts>.log for inbox-sweep is wrong - agent writes to $HOME/.claude/logs/linkedin-sweep.log; operator tails the wrong file and sees nothing
• Skipping the notify+eval log rows means the byline shows the agent as overdue even though you just ran it

Self-Test

An agent reading this should correctly:

1. [ ] Always background with nohup ... & and never block on the agent process?
2. [ ] Score a lockfile-collision spawn as success (1), not failure?
3. [ ] Read field 7 of the catalog to determine the correct tail target?
4. [ ] Append to BOTH notify.ndjson and evals.ndjson after every spawn?

Self-report

If this loader fell short, append a line:

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