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, 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 |
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.
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.
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.
It never approves or edits a tool call.