Mods
The plugin's in-process module for Claude Code. Instant commands, repo manuals on first touch, sync progress, and notices above the prompt.
Hooks run a program at four fixed moments. Mods go further. Since Claude Code 2.1.287 a plugin can load a module that runs inside Claude Code itself: it registers commands, sees tool calls as they happen, and draws above the prompt. agent-kevin ships one module, mods/hooks/register.ts, loaded beside its command hooks. There is nothing to configure.
| Requires | Claude Code 2.1.287 or newer. init and upgrade stop below it with claude update, and the session banner warns until the host is updated |
| Runs in | Claude Code. The commands, the sync band and the notices row need an interactive session, since claude -p and the Agent SDK have no prompt to type into or draw above |
| Not in | Codex. Every feature below has a path that works there, noted in its section |
Instant commands
These run without a model turn, so they answer at once; only their one-line reply lands in the conversation.
| Command | Does |
|---|---|
/capture <text> | Drops the text into the inbox for the next compile. See Capture |
/lesson <text> | Appends a correction to the feedback log. See Self-evolution |
/done <task-id> | Closes the task. See Tasks |
/today | Overdue work with how many days late, what's due today, today's date with the Hijri date, and the last sync (yellow after three days) |
/manuals | Lists the repo instruction files attached to this conversation |
/capture with text already in the inbox says Already captured and points to the first file. Under Codex, or anywhere a mod doesn't run, the same operations are kevin capture, kevin capture --kind=feedback, kevin task close, or just asking.
Repo manuals on first touch
Claude Code grants file access to the code folders in permissions.additionalDirectories but by default doesn't load their instructions. The mod closes that gap. The first time a turn reads or writes a file in a granted folder, or runs a shell command that names an absolute path inside one, it attaches that repo's instructions to the tool result:
- every folder from the repo's root (its
.git) down to the touched one, so a package's manual comes with the repo's, as long as that root is the granted folder or inside it; - in each,
CLAUDE.md,.claude/CLAUDE.mdandCLAUDE.local.mdin the order Claude Code reads them, with their@-imports followed up to four levels deep, as long as an import stays inside a granted folder; AGENTS.mdwhen a folder has none of those.
Each file is attached once per conversation, and again after a compaction or /clear drops it from context. A subagent gets its own copy. A dim 📎 line above the prompt names what the current turn attached. A folder outside any git repo gets nothing, and an agent home is skipped, since it loads its own manual through its bridge.
Without the mod, the operating manual's rule does the same job: read a repo's AGENTS.md, and its bridge when it has one, before touching its code. See Coding rules.
Sync progress
While sync runs, a band above the prompt shows its status, the twelve steps with the current one marked, how long it has been running (with the average run once it finishes), and counters for what it is clearing: sessions, feedback and inbox items waiting to compile, stale and overdue tasks, plus what it has compiled, fixed and closed so far.
The mod also gives sync a sync_stats tool, and the closing report quotes its counted numbers (the compile backlog, the 🧹 Brain counts, task health, timing) instead of a tally the model adds up. Each finished run's duration is kept, which is where the sync notice's typical time comes from. Without the mod, sync runs the same steps and reports from the files on disk.
Notices above the prompt
The top upgrade or sync nudge sits above the prompt as a row with a button that runs it and a Tomorrow button that snoozes it, and it is the Tab suggestion in an empty prompt. Without the mod, the same notices go in the session banner. See Notices.
What a mod can reach
A mod runs inside Claude Code with your permissions, outside the shell sandbox, the same as the MCP server. agent-kevin's module calls the plugin's CLI and its brain-audit script from the home, reads the home's files and the instruction files in granted code folders, and draws. It never approves or edits a tool call. It adds manuals to tool results, answers its own sync_stats tool, and adds one paragraph to sync's prompt asking for that tool's numbers. The rules it supports stay in the manual, so a home that loses the mod loses convenience, never a rule.