Mods
The plugin's in-process module for Claude Code. Instant commands, queued prompts, this conversation's reports, repo manuals on first touch, sync progress, the heartbeat's clock, and notices above the prompt.
In short
In Claude Code, the plugin's mod adds instant slash commands, queued prompts, repo manuals on first touch and notices above the prompt, with nothing to set up. Try /today first; every feature except /queue has another way to do the same in Codex.
A mod is a module that runs inside Claude Code itself, where a hook runs a program at a fixed moment. It registers commands, sees tool calls as they happen, and draws above the prompt. The plugin ships one module, mods/hooks/register.ts, loaded beside its hooks. There is nothing to configure.
| Requires | The Claude Code version the plugin needs. See Claude Code |
| Runs in | An interactive Claude Code session. claude -p and the Agent SDK have no prompt to type into or draw above |
| Not in | Codex. Every feature except /queue has a path that works there, in the last column below and in each section |
Commands
None of these takes a model turn, so each answers at once.
| Command | Does | Without the mod |
|---|---|---|
/capture <text> | Drops the text into the inbox for the next compile. Text already there answers Already captured and points to the first file. See Capture | The CLI's capture, or ask |
/lesson <text> | Appends a correction to the feedback log. See Self-evolution | The CLI's capture --kind=feedback, or ask |
/task <id> | Shows the task as a card | The CLI's task get |
/task <id> done | Closes a task that is open, active or blocked | The CLI's task close |
/task <id> cancel | Cancels one; archive means the same | Ask |
/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) | Ask, or open the dashboard |
/reports | The reports this conversation produced | reports/index.md |
/reports attach <path> … | Adds existing files to that list by hand | |
/session | This conversation's session id, with a Copy button. Nothing reaches the clipboard until you press it | |
/manuals | Lists the repo manuals attached to this conversation | |
/queue <prompt> | Holds a prompt until the current task ends | None: Claude Code only |
/queue clear | Drops every prompt still waiting and says how many | |
/heartbeat [15m | 2h | off | now | status] | Makes this session the home's heartbeat, which looks for proposals at once and then on its interval (55 minutes unless set); off stops it, now looks right away, status says who has it | $proposals by name in Codex |
/proposal <start|later|skip> <id> | Starts a proposal in a fresh session, puts it off until 08:00, or drops it | The CLI's proposals decide |
Only a command's one-line reply lands in the conversation. /task <id>, /today, /reports and /session draw a row above the prompt, which stays until you press Dismiss or run /clear.
/today always shows the Hijri date. Briefings add it only when you keep that calendar.
Task cards and links
The card /task <id> draws has the task's status, priority, project and due date, the first paragraph of its description, checklist progress, an Open link to its file and a Done button. See Tasks.
- Finding the task. Type the start of the id or a word of the title for suggestions, then a space for the actions that task can take.
ab-42reads asab-042. - Links in replies. In the terminal, every task id in a reply is a link to that task's file, so a click opens it in whatever app opens
.mdfiles. Only ids of real tasks are linked, never inside code blocks or existing links, and the reply is stored as written. - In the desktop app replies are drawn unchanged, since it opens no
file:link.
Queue a prompt
In Claude Code, a message you send while a task runs reaches Claude as soon as the current tool calls finish, inside that same task. /queue <prompt> holds it until the task is over instead.
| When | What happens |
|---|---|
| A task is running | The prompt waits, then goes out as its own turn, in your words. Several go out one per turn, in the order you queued them |
| Something is waiting | A dim ⏳ 2 queued · /queue clear to drop row above the prompt counts it |
You run /queue clear | Everything still waiting is dropped. A prompt already sent stays sent |
| A turn fails, or you stop it with Esc | The queue pauses and the row says paused. It resumes once a turn you send ends normally |
| Nothing is running and the queue is not paused | /queue sends the prompt at once |
| You press Ctrl+Enter | The message goes right away, and the queue keeps its place |
A queued prompt is plain text: @file mentions and pasted images are not expanded.
Reports from this conversation
Skills save their output as reports: briefings, PR reviews, plans, explainers. /reports gathers the ones this conversation produced into a 📎 row above the prompt, newest first, each with its path and its title when a skill gave it one. A report with an HTML page beside it shows the page.
The row picks up new reports as they land, scrolls with the mouse wheel once it outgrows the space, and stays until you press Dismiss. Claude gets the full list too, so you can ask about any of them.
| Counts as a report | Does not |
|---|---|
| Every report a skill saves, including one saved by a subagent | Knowledge files and other state, so a sync adds the reports it saves and none of its bookkeeping |
A markdown or HTML file the conversation writes or edits under reports/ | The reports index and the pins |
| One inside a project folder | The project's README.md and its tasks |
The home's roadmap.html | |
Anything you add with /reports attach |
Attaching by hand. /reports attach <path> … takes several paths at once: relative to the folder the session started in, under ~/, or absolute. Quote a path that has spaces ("My Docs/plan.md"), or escape each space with a backslash. A path that names no file is listed in the reply, and the rest still attach.
How long the list lasts. It belongs to the conversation, so a resumed one still has it, and /clear starts a new one. The lists of the 50 most recently active conversations are kept.
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. It attaches a repo's instructions to the tool result the first time a turn does one of these in a granted folder:
- reads or writes a file there;
- runs a shell command that names an absolute path inside it.
| Attached | Rule |
|---|---|
| Which folders | Every folder from the repo's root (its .git) down to the touched one, so a package's manual comes with the repo's. The root must be the granted folder or inside it |
| Which files | In each folder, CLAUDE.md, .claude/CLAUDE.md and CLAUDE.local.md, in the order Claude Code reads them. AGENTS.md when a folder has none of those |
| Imports | @-imports are followed up to four levels deep, as long as an import stays inside a granted folder |
| How often | Once per conversation, and again after a compaction or /clear drops it from context. A subagent gets its own copy |
| Never | A folder outside any git repo, and an agent home, which loads its own manual through its bridge |
A dim 📎 line above the prompt names what the current turn attached. 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, and its steps with the current one marked;
- how long it has been running, with the average run once it finishes;
- what is waiting: sessions, feedback and inbox items to compile, stale and overdue tasks;
- what it has compiled, fixed and closed so far.
A brain refresh gets the same band under its own name, with only its own steps; it stays out of the run times the notice reads, and its band clears when it ends, since nobody types in the heartbeat's tab to clear it.
When sync hands work to a background agent, the band counts that agent's work too. It stays on the same run until the agent hands back and the session that started sync finishes.
The mod also gives sync a sync_stats tool. 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.
The heartbeat's clock
Once a session runs /heartbeat, the mod keeps its clock: each tick checks the proposals list and wakes the session with the proposals skill only when this session is the heartbeat, no turn is running, and another session in the home wrote to its transcript within the interval. A session that keeps no transcript can't tell, so it wakes on every tick. When a brain refresh is due and a session has written since the last one, the wake clears the conversation and runs sync brain before the look. A tick that doesn't wake costs no model turn, and after each look or refresh the mod rebuilds the dashboard and the sidebar, which costs none either.
The mod draws the heartbeat's band above its prompt and redraws it each minute so the countdown stays true (What the heartbeat shows). The heartbeat is the session's process, so /clear and /resume keep it; leaving the session gives it up, and /heartbeat in another session takes it over, which both sessions say. See Proposals.
Agent rows
Each subagent running under the prompt gets a row with its type, its description and a context bar coloured like the footer's (green under 50%, yellow under 80%, red above). It draws in the terminal only, and a row body from your own settings wins over the plugin's.
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. It is also the Tab suggestion in an empty prompt. Without the mod, the same notices go in the session banner. See Notices.
Setting up a new folder
In a folder that isn't an agent home yet, a row above the prompt says so, with a Set up button that runs init, and /agentlayer:init is the Tab suggestion. A folder in or under a home, or one holding a SOUL.md, never shows it. Without the mod, the session banner says the same.
What a mod can reach
A mod runs inside Claude Code with your permissions, outside the shell sandbox, the same as the MCP server. The rules it supports stay in the manual, so a home that loses the mod loses convenience, never a rule.
The 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;
- draws above the prompt, and adds manuals to tool results;
- keeps each conversation's list of reports in the plugin's own store;
- answers its own
sync_statstool, and adds one paragraph to sync's prompt asking for that tool's numbers; - sends the prompts you queued with
/queue; - wakes the heartbeat session with the
proposalsskill (andsync brainwhen a refresh is due), lists the cmux workspaces for it, rebuilds the dashboard after a look, gives the heartbeat up when its session exits, and records your Start, Later and Skip through the CLI.
It never approves or edits a tool call.