The tools developers love longest tend to share one trait: they ship with the means to change them. Emacs is extended in its own Lisp. Spreadsheets became platforms when users could write macros. VS Code’s extensions turned an editor into whatever each team needed. When a tool ships with the tools to change it, its users invent things its makers never planned for.
Claude Code now ships with those tools.
Claude Mods are code that runs inside Claude Code itself. A mod can draw a pane beside the conversation, add a band above the prompt, register a command that runs instantly, step into a tool call, call a model, or start a process. It is the difference between extending what Claude knows and changing the tool Claude runs in.
From the outside to the inside
Claude Code has been extensible for a while, but always from the outside. Skills give Claude instructions. MCP servers give it tools. Settings hooks run a shell script when something happens. Each one feeds Claude text or tools, or reacts from a separate process.
A mod is a plugin made of JavaScript or TypeScript event handlers that Claude Code calls in its own process. When something happens — a tool call, a submitted prompt, a part of the interface being drawn — Claude Code runs the mod’s hook first, and the hook decides what happens next. It can observe the event, rewrite it, or answer it so the default behavior never runs.
That model is simple and remarkably far-reaching. According to the docs, a mod can:
- Draw an interface you can use: a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields.
- Redraw Claude Code’s own interface: restyle parts Claude Code draws itself, such as a tool call’s row, the spinner, or the question dialog.
- Step into a tool call or a request: hold a tool call while asking the user a question, answer it without running the tool, or send a request to a different model.
- Run code on a command: a
/commandthat runs a function immediately, with no Claude turn, even while Claude is working. - Share data between hooks: what one hook records, another can show.
Mods run in the Claude Code CLI, the Code tab of the Desktop app, and the VS Code extension, and install from a plugin marketplace like any other plugin.
A mod in ten lines
The example from the docs captures the model well. Two hooks share one variable: one counts tool calls, the other shows the count beside the spinner.
let calls = 0
export function register(on) {
on('tool.call', async ($, e, next) => {
calls += 1
$.ui.invalidate('ui.render')
return next(e)
})
on('ui.render', { component: 'Spinner' }, async ($, e, next) => {
return next({ ...e, props: { ...e.props, suffix: ' · tool calls: ' + calls + '…' } })
})
}Every hook receives the mods API ($), the event (e), and next, which runs everything beneath it, including Claude Code’s own behavior. Calling next(e) lets the event continue. Calling it with a changed event rewrites it. Returning without it takes the event over. It is middleware for a coding agent.
With a manifest and a one-line hooks.json, that is a complete mod.
While Claude works, the spinner now keeps score:
A developer experience built for agents
The tooling around mods is as notable as the API itself.
Claude writes mods. Claude Code ships with a plugin-authoring skill. Describe the mod you want in a session and Claude writes it, with the types for the exact build you are running.
Edits reload live. claude --plugin-dir ./my-mod loads a mod for one session and reloads it as files change.
Mods are testable. claude plugin test runs a mod’s tests against a mocked engine, with no session required.
Mods are reviewable before they run. claude plugin validate reads a mod without executing it and lists every event it handles and every call it makes — files, processes, network, models. Because a hook can only reach the outside world through the mods API, that list is complete. It also flags gating hooks, the ones that can refuse an action.
That last point matters, because mods are powerful by design. A mod runs with the user’s permissions and is not sandboxed. The platform answers this with transparency rather than restriction: validate a mod before installing it, install only from trusted marketplaces, and, for organizations, use managed settings to control which mods load.
Put together, these properties make mods unusually well suited to agentic development. A testable API, a static report of every side effect, and live reload give an agent everything it needs to build, check, and iterate on its own.
Learning Mods by Building Questline
To explore how far mods can go, Very Good Ventures built Questline: an idle ASCII role-playing game that lives inside Claude Code and is built entirely from a developer’s own sessions.
The premise is that Claude Code transcripts are already a game log. Every session records each prompt, tool call, error, plan, compaction, and token. Read as data, those records reveal habits: contexts that compact because they were never cleared, the same failing command run four times, a pull request merged without checking CI, and also the good patterns — a plan approved before the first edit, a search delegated to a subagent.
Questline turns that record into a hero. Its six attributes are habits such as planning before building and keeping contexts focused. Anti-patterns are monsters, each paired with its remedy. Every Claude Code feature is a spell, and the ones a developer has never used appear as runes with a hint on how to learn them.
Each day brings three quests targeted at the habits that need work, and Sonnet writes a short chronicle of the previous day from its numbers alone. An Opus research agent, the Loremaster, reads the Claude Code changelog after each update and adds spells and quests for new features. A single line above the prompt opens each day, then gets out of the way.
The game exercises almost the entire mods surface: a pane with six tabs, a band above the prompt, toasts, a slash command, model calls, a background agent, files, and processes. It also had to meet a strict rule — outside the moments it is opened, it must be invisible. Meeting that rule shows how the mods API rewards careful design:
- Few hooks, all non-blocking. Questline listens only to session start, turn start and end, its own command, and its own drawing. It never hooks tool calls or prompts, calls
next()before doing its own work, and every hook fails open. - Context stays clean. A command’s reply enters the model’s context, so
/questreturns one line of about five tokens. Everything else lives in the pane. - Zero-token reading. Transcripts are parsed with plain code, never sent to a model. Model calls are capped and shown in the pane as a monthly budget.
- Self-imposed sandboxing. Every file and process call goes through one module with read and write allow-lists, and a build check fails if anything goes around it.
- Verified end to end. Beyond 172 unit tests, a gate script drives the mod in a real Claude Code through a pseudo-terminal and checks every screen. The screenshots in this post come from the same harness.
That gate is what let Claude build Questline largely on its own, in a loop of implement, verify, and fix, in about a day. A game that teaches Claude Code, built by Claude Code, running inside Claude Code.
Questline is internal to VGV for now. If you want to try it, get in touch or ask us on LinkedIn or X.
What mods make possible
Questline is a game, but the pattern is general: read what Claude Code already records, compute something useful locally, and show it where developers already work. That opens several directions:
- Coaching without surveillance. Measure planning, delegation, and CI discipline locally, and share only aggregates.
- Guardrails that teach. Hold a risky command, explain the habit behind it, and track whether it recurs.
- Team-specific onboarding. A spellbook for a team’s own stack, with quests for its skills, commands, and conventions.
- Workflow surfaces. Views across every running session and repository — VGV’s Switchboard mod, for example, shows which sessions are waiting on a permission prompt and which two are about to commit each other’s work.
For most of software history, changing how a development tool behaves meant waiting for its vendor. Mods move that power to the people who use the tool every day.
Getting started
The fastest way in is to look at what already exists. Claude Code’s own /diff pane is a built-in mod, and its source is public. Anthropic also publishes sample mods: token-weather draws a forecast of the context window above the prompt, blast-radius holds a risky shell command and shows what it would change, and replay-theater steps through the edits Claude made in the last turn.
From there, the Claude Mods documentation covers panes, events, the full API, testing, and organization controls. Or open Claude Code and describe the mod you wish existed.
One detail from Questline seems fitting. Its spellbook includes a spell called Modcraft, learned the first time a developer writes a mod. Learning it drops a Cat of Curiosity into the inventory.
It is a good time to earn one.
