OR Key
drop another .md file to compare - side-by-side diff against hooks

hooks

Sets up automatic actions that fire at the right moments.
description: "Triggers on prompt mention of 'hooks'."
personal 2 files 10 recent evals
Export

What it does for you

Sets up automatic actions that fire at the right moments.

What it produces

A recent result, so you can see the kind of work it returns.

loading…

How to get it

These run inside the Snappy workspace. Want this working in your business? I set skills like this up with you, in one focused week.

Work with me
For developers how this skill is built, graded, and how it runs

at a glance- the short version

actorExported functions in state/lib/hooks.ts.
auditorNone wired yet - eval is manual (Robert review).
eval modeshape
categorySystem
stages3

what's inside - the parts that make up a skill 3/4 present

A skill is just a few plain-text files. Only the main one is required. The rest are optional, added as the work needs them. This is what the skill is made of; how it runs is just below.

The skill
state/skills/hooks/SKILL.md present
the skill itself, in plain text
The main file. It says what the skill is and lays out the steps in plain English.
Code
state/lib/hooks.ts present
code the skill can run
Reusable code this skill can call when it needs to.
Scripts
state/bin/hooks/ not present
helper scripts
Optional. Added when a skill has a few commands to run.
Loader
state/skills/hooks/AGENTS.md present
what the AI loads on the fly
Loaded automatically the moment this skill is needed. Kept short on purpose.

how it's graded - what counts as a good run 4 criteria · 3 deterministic · 1 judge

Each row is one thing a good run has to get right. deterministic means a quick check decides, pass or fail. judge means the AI reads the result and rates it. Grading each piece on its own (instead of one overall score) shows exactly where a run fell short, so the fix is obvious.

name
kind
check
list_hooks_availability
deterministic
The `listHooks()` function from `state/lib/hooks.ts` is callable and returns a parsable JSON array.
get_hook_status_availability
deterministic
The `getHookStatus()` function from `state/lib/hooks.ts` is callable and returns a parsable JSON object.
codex_hooks_configuration
judge
Codex-specific hooks (`UserPromptSubmit`, `SessionStart`, `Stop`) are correctly configured per the Gotchas section, preventing output repetition and ensuring silence where required.
log_entry_on_run
deterministic
A `state/log/pending-eval.ndjson` row is filed after each execution of the skill.

how it runs - the shared frame every skill uses 5/5 present

Every skill runs the same way. One part does the work, a separate part checks it, and a short loader hands the AI exactly what it needs for the job. Anything this skill doesn't use shows a one-line note saying why, on purpose, not by accident.

makes the work The worker
present
Exported functions in state/lib/hooks.ts. the worker
Does the actual work. Whatever it produces is what gets checked next.
checks the work The reviewer
present
None wired yet - eval is manual (Robert review). the checker
A separate checker grades the work, so the part that made it can't approve its own work.
frame
learns Self-correction
present
fixes itself learns from gaps
When a run hits a gap, the skill gets edited on the spot [FIXED] or queued for a bigger rewrite [LOGGED], so it keeps getting better.
tidies up Background fixes
present
queued for rewrite runs in the background
Bigger fixes that can't be made on the spot get queued and rewritten in the background later.
remembers Run history
present
state/log/pending-eval.ndjson pending runs
Every run is written down here, then reviewed by hand each week.
Critical rules the things this skill must not get wrong
  1. Hook entries in ~/.claude/settings.json MUST be wrapped — bare {command} rejects whole settings.json silently. (feedback_settings_hooks_must_be_wrapped.md, killed byline 2026-04-17)
  2. Claude Code keeps the reference snappy-os-inject.sh on UserPromptSubmit and PreToolUse:Task|Agent; it fetches program.md + state/index.md and mention-triggered state/skills//AGENTS.md loaders.
  3. Codex MUST NOT use snappy-os UserPromptSubmit for normal context. Codex adds that output every turn and suppressOutput is not implemented, so it creates visible repeated blocks. Use SessionStart via state/bin/codex-session-start-context.sh and quiet Stop via state/bin/codex-stop-hook.sh.
  4. Cron jobs, hooks, and slash-command-invoked skills all log exactly one eval row per run via score() — score 0 with a notes field on defect, positive score on success. Never two rows for the same run. (CONSTITUTION invariant #4)

what it has learned - fixes written back in over time sample

When a run hits something this skill didn't handle, the fix gets written back into the skill so it doesn't happen again. FIXED means it was corrected on the spot. LOGGED means it's queued for a bigger rewrite. Either way, the skill gets a little better and never makes the same mistake twice.

  1. Loading feedback rows…

how the work flows- who makes it, who checks it

actor Exported functions in state/lib/hooks.ts.
1 generator
invoke
actor = Exported functions in state/lib/hooks.ts.
import from `state/lib/hooks.ts` — `listHooks()`, `getHookStatus()
+ eval for this step
auditor None wired yet - eval is manual (Robert review).
2 auditor
inspect
auditor = None wired yet - eval is manual (Robert review).
getHookStatus()` after any settings.json edit to confirm no silent rejection
+ eval for this step
3 data
eval log
`state/log/pending-eval.ndjson` (manual eval — skill: "hooks")
+ eval for this step

SKILL.md- the skill, written out in plain English

hooks

Hook management for the Claude Code harness.

Ported from kernel snappy-hooks in Phase 0.5. See state/lib/hooks.ts for the full API surface.

Steps

  • listHooks() - see state/lib/hooks.ts
  • getHookStatus() - see state/lib/hooks.ts

Eval

Actor: the exported functions in state/lib/hooks.ts. Auditor: none wired yet - eval is manual (Robert review). File a state/log/pending-eval.ndjson row on each run.

Score convention:

OutcomeScore
Pass on first try1.0
Failed first, auto-fix applied, re-check passed0.5
Still failing or unrecoverable0.0

Gotchas

  • Claude Code and Codex use similar hook JSON wrapping, but not the same user experience.
  • Claude Code supports statusLine, UserPromptSubmit, PreToolUse, PostToolUse, Stop, and SessionStart. The snappy-os reference loader stays there.
  • Codex UserPromptSubmit adds context on every turn. Do not wire snappy-os there; it visibly repeats large blocks and suppressOutput is not implemented.
  • Codex snappy-os context belongs in SessionStart through state/bin/codex-session-start-context.sh. It should stay compact and point to files on disk instead of embedding program.md or state/index.md. Any startup maintenance such as pull --auto must run inside that adapter with stdout/stderr redirected; separate CLI SessionStart entries can print prose/errors and break Codex's JSON parser.
  • Codex Stop hooks must be silent. Use state/bin/codex-stop-hook.sh, which routes normal CLI output into ~/.codex/logs/snappy-os-stop.log.
  • See the kernel SKILL.md for original long-form hook API guidance only as a read-only reference.

Graduation

This skill is prose. Graduate by defining a deterministic auditor and flipping eval: auto.

Rubric

criteria:
  - name: list_hooks_availability
    kind: deterministic
    check: "The `listHooks()` function from `state/lib/hooks.ts` is callable and returns a parsable JSON array."
  - name: get_hook_status_availability
    kind: deterministic
    check: "The `getHookStatus()` function from `state/lib/hooks.ts` is callable and returns a parsable JSON object."
  - name: codex_hooks_configuration
    kind: judge
    check: "Codex-specific hooks (`UserPromptSubmit`, `SessionStart`, `Stop`) are correctly configured per the Gotchas section, preventing output repetition and ensuring silence where required."
  - name: log_entry_on_run
    kind: deterministic
    check: "A `state/log/pending-eval.ndjson` row is filed after each execution of the skill."

AGENTS.md- what the AI loads when this skill comes up

hooks - loader

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

Critical Rules

  • Hook entries in ~/.claude/settings.json MUST be wrapped - bare {command} rejects whole settings.json silently. (feedback_settings_hooks_must_be_wrapped.md, killed byline 2026-04-17)
  • Claude Code keeps the reference snappy-os-inject.sh on UserPromptSubmit and PreToolUse:Task|Agent; it fetches program.md + state/index.md and mention-triggered state/skills/*/AGENTS.md loaders.
  • Codex MUST NOT use snappy-os UserPromptSubmit for normal context. Codex adds that output every turn and suppressOutput is not implemented, so it creates visible repeated blocks. Use SessionStart via state/bin/codex-session-start-context.sh and quiet Stop via state/bin/codex-stop-hook.sh.
  • Cron jobs, hooks, and slash-command-invoked skills all log exactly one eval row per run via score() - score 0 with a notes field on defect, positive score on success. Never two rows for the same run. (CONSTITUTION invariant #4)

Commands

| ui dashboard | state/skills/hooks/resources/ui.openui | |invoke: import from state/lib/hooks.ts - listHooks(), getHookStatus() |verify: getHookStatus() after any settings.json edit to confirm no silent rejection |eval log: state/log/pending-eval.ndjson (manual eval - skill: "hooks")

OpenUI Resource

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

  • Settings.json silent reject: malformed entry kills the whole file's behavior - verify with getHookStatus after edits
  • Default sync scope is state/; pushing program or sources requires explicit --scope flag (program.md sync)

Self-Test

An agent reading this should correctly:

  1. [ ] Wrap hook entries properly, never bare {command}
  2. [ ] Verify with getHookStatus() after settings.json edits
  3. [ ] Log a friction (not an eval) when a hook fires but its skill defects

Self-report

If this loader fell short, append a line:

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

api.ts- the code it can call

#!/usr/bin/env npx tsx
/**
 * snappy-hooks/api.ts -- Hook management for the Claude Code harness.
 *
 * Reads hook configuration from ~/.claude/settings.json and checks
 * hook scripts in ~/.claude/hooks/ for existence and executability.
 *
 * Usage:
 *   npx tsx api.ts list                # list all configured hooks
 *   npx tsx api.ts status              # check hook script health
 *
 * Or import as module:
 *   import { listHooks, getHookStatus } from "./hooks.ts";
 */

import { existsSync, readFileSync, realpathSync, statSync } from "fs";
import { join } from "path";
import { env } from "./env.ts";

const SETTINGS_PATH = join(process.env.HOME!, ".claude/settings.json");
const HOOKS_DIR = join(process.env.HOME!, ".claude/hooks");

interface HookEntry {
  type: string;
  command: string;
  timeout?: number;
}

interface HookGroup {
  matcher: string;
  hooks: HookEntry[];
}

interface HookConfig {
  [event: string]: HookGroup[];
}

/** Lists all hooks configured in ~/.claude/settings.json. */
export function listHooks(): { event: string; matcher: string; command: string; timeout?: number }[] {
  if (!existsSync(SETTINGS_PATH)) {
    throw new Error(`settings.json not found at ${SETTINGS_PATH}`);
  }

  const settings = JSON.parse(readFileSync(SETTINGS_PATH, "utf-8"));
  const hookConfig: HookConfig = settings.hooks || {};
  const results: { event: string; matcher: string; command: string; timeout?: number }[] = [];

  for (const [event, groups] of Object.entries(hookConfig)) {
    for (const group of groups) {
      for (const hook of group.hooks) {
        results.push({
          event,
          matcher: group.matcher,
          command: hook.command,
          timeout: hook.timeout,
        });
      }
    }
  }

  return results;
}

interface ScriptStatus {
  name: string;
  path: string;
  exists: boolean;
  executable: boolean;
  sizeBytes: number;
}

/** Checks all .sh scripts in ~/.claude/hooks/ for existence and executability. */
export function getHookStatus(): ScriptStatus[] {
  if (!existsSync(HOOKS_DIR)) {
    return [];
  }

  const { execSync } = require("child_process");
  const files: string[] = execSync(`ls ${HOOKS_DIR}/*.sh 2>/dev/null || true`, { encoding: "utf-8" })
    .split("\n")
    .filter(Boolean);

  return files.map((filePath) => {
    const stat = statSync(filePath);
    const executable = !!(stat.mode & 0o111);
    return {
      name: filePath.split("/").pop()!,
      path: filePath,
      exists: true,
      executable,
      sizeBytes: stat.size,
    };
  });
}

// --- CLI ---

if ((() => { try { return import.meta.url === `file://${realpathSync(process.argv[1])}`; } catch { return false; } })()) {
  (async () => {
    const [, , cmd] = process.argv;

    switch (cmd) {
      case "list": {
        const hooks = listHooks();
        if (!hooks.length) {
          console.log("No hooks configured in settings.json");
          break;
        }
        for (const h of hooks) {
          console.log(`${h.event}\t${h.matcher}\t${h.command}${h.timeout ? `\t(${h.timeout}s)` : ""}`);
        }
        break;
      }
      case "status": {
        const scripts = getHookStatus();
        if (!scripts.length) {
          console.log("No hook scripts found in ~/.claude/hooks/");
          break;
        }
        for (const s of scripts) {
          const status = s.executable ? "OK" : "NOT EXECUTABLE";
          console.log(`${status}\t${s.name}\t${s.sizeBytes}b`);
        }
        break;
      }
      default:
        console.log("Usage: npx tsx api.ts [list|status]");
    }
  })();
}

scripts- helper scripts it can run

prose-only skill - 1 inline code block live in SKILL.md above (no state/bin/ sidecar yet).

how we check it- the checks, plus the last 10 runs

rubric shape schema-shape check (no inline rubric)
recent mean 1.00 · 10 runs actor/auditor: unverifiable
deps none declared
timestamp verb score primary_issue artifact
2026-04-25 04:11Z - 1.00 - -
2026-04-21 15:58Z - 1.00 - -
2026-04-21 15:56Z - 1.00 - -
2026-04-21 03:53Z - 1.00 - -
2026-04-19 00:02Z - 1.00 - -
2026-04-18 23:53Z - 1.00 - -
2026-04-18 23:41Z - 1.00 - -
2026-04-18 23:37Z - 1.00 - -
2026-04-18 23:21Z - 1.00 - -
2026-04-18 23:18Z - 1.00 - -