Ryuu's Skills

Overview

The hooks that run on agent events, what they share, and how to switch them off.

The hooks are skills hook verbs run from the checkout and need Bun. Claude Code and Codex run the same commands: the stdin payloads and the block JSON match for these events. The CLI reads Codex's apply_patch command where Claude Code sends content or new_string.

HookEventWhat it does
session-briefSessionStartInjects the delivery mode, the branch, the matching plan row and the recent trail.
no-em-dashPostToolUseBlocks em and en dashes in a file the agent wrote.
no-commentsPostToolUseLists every full-line comment an edit added and asks whether it earns its place.
commit-guardPreToolUseLets through only the commits, pushes and PR comments the delivery mode allows, and lists new comment lines before a commit ships.
reply-guardStopChecks the final reply for dashes, filler and labels, and the tree for new comment lines.

Wiring is on the agent pages: Claude Code for settings.json, Codex for hooks.json, and OpenCode for the plugin that runs all five through the same verbs.

Heartbeats

The PostToolUse and Stop hooks also leave a pulse for a live plan. When the current branch is a DOING row's branch, they record a heartbeat event on that plan, and on every other DOING row a batch shares the branch with, at most once every 5 minutes per session, or per checkout when the host passes no session id. A small state file next to the reply guard's is the throttle, so most tool calls read one file and run no git or store call. A busy store skips the write and never slows or fails the tool call. The event names the branch and the session id, unless the project's transcript policy is off or the session was withheld under another project's off; OpenCode passes none. /plans and the session brief mark a DOING row whose newest heartbeat or start is more than 30 minutes old as (<label>, stale <n> min), naming the machine holding its lease or, without one, the machine that wrote it.

Recorded Blocks

Each time the PreToolUse, PostToolUse or Stop hook blocks, it records one hook-block event in the store holding every rule id it reported, the host (claude, codex or opencode), and the project and plan when the branch maps to a row. A rule id is <guard>/<finding>, such as reply-guard/dash or commit-guard/commit-shape. Recording is best effort and never changes what the hook does: with no plans directory, a store busy for more than 100 ms, or any other error, the block stands and no event is written. The dashboard's stats view counts blocks per rule, and skills digest names each rule id that blocked 3 times or more in a week. Both leave out the blocks of a project whose transcript policy is off, so a rule can block more often than they show.

Turning Them Off

With AGENT_HOOKS=0 set, every hook but the commit guard exits at once. The commit guard ignores it and keeps enforcing the delivery mode, and only its comment sweep is skipped. AGENT_HOOKS_SKIP lists the path fragments the comment, dash and reply guards skip, vendored and generated directories by default. Both are described in Configuration.

The Comment Detector

packages/cli/src/hooks/comment-scan.ts is the detector the comment hooks share: a per-extension marker table with block-comment state, so a JSDoc body counts line by line. It knows full-line comments only. A trailing // note after code passes, as does a marker inside a string. Semantic judgment (is this line a why the code cannot show) stays with /no-comments and comment-sicko.

The detector drops shebangs, lint and type pragmas and license headers, and skips files with no marker table (prose, for one) and paths matching AGENT_HOOKS_SKIP. Both hooks that use it stay silent on those.

On this page