Claude Code mods are plugins made of JavaScript or TypeScript functions that run inside Claude Code. They can add your own panels to the screen and intercept Claude's tool calls. What they draw only shows up in the terminal claude and the Code tab of the desktop app. In the desktop app, mods work from Claude Code 2.1.286.
What a mod does
The official docs describe a mod as "a plugin that changes how Claude Code looks and behaves." Inside, it is a set of functions keyed by event, and Claude Code calls the matching function every time an event happens. Events are things like:
- Claude is about to use a tool (Bash, Read, and so on)
- The user sent a prompt
- Claude Code is about to draw some part of the screen
The function that gets called can just observe the event, rewrite it, or answer it itself and stop the default behavior.
Claude Code already had "hooks" (shell commands written in settings.json). Mods differ in that they run as functions inside Claude Code. The official pages call a mod's function a "hook" and the settings-file kind a "settings hook."
What mods can do
A short summary of what the official overview lists:
| Capability | Example |
|---|---|
| Draw your own UI | A pane next to the conversation, a band above the prompt. Tabs, buttons, and inputs are allowed |
| Redraw Claude Code's own UI | Tool call rows, the spinner, the question dialog |
| Intercept tool calls and requests | Stop a dangerous command and confirm, route to another model |
| Add your own commands |
/xxx runs a function without using a Claude turn |
| Share values between hooks | One hook counts something, another draws it |
The difference from existing tools is whether you can draw. Settings hooks, skills, and MCP servers cannot draw on the screen. Use a mod when you want a pane or a band, a skill when you keep pasting the same instructions, and an MCP server when you want to connect an external service.
Where mods can draw
The official docs call the places a mod can draw "render sites." This series covers four: the pane and the band, plus the status line and toast, which you show by just calling an API.
| Name | Where it appears | Article in this series |
|---|---|---|
Pane (Pane) |
A panel next to the conversation. A frame above the prompt when space is tight | Part 3 |
Band (AbovePrompt) |
The strip right above the prompt. Shared by all mods | Part 4 |
Status line ($.ui.status) |
One line below the prompt | Part 4 |
Toast ($.ui.toast) |
A small notification that disappears after a few seconds | Part 4 |
You can also redraw the spinner (Spinner), messages (UserMessage, AssistantMessage), tool rows (ToolUse and others), and the question dialog (AskUserQuestion). The only thing you cannot redraw is the permission prompt. That is so a mod cannot disguise what you are being asked to approve.
Where mods run
This is the most commonly misunderstood part. Where the functions (hooks) run and where the drawn UI is visible are two different things. Here is the official table:
| Where Claude Code runs | Hooks run | Drawn UI is visible |
|---|---|---|
Terminal claude (including terminals inside editors and JetBrains) |
Yes | Yes |
| Desktop app Code tab (except WSL sessions) | Yes | Yes (except terminal-only components) |
| Desktop app WSL sessions | No (plugins are not available in WSL) | No |
| VS Code extension chat panel | Yes | No |
claude -p and the Agent SDK |
Yes | No |
| Remote Control from a phone or claude.ai | Yes (in the session on your local PC) | Only in the local terminal |
| Cloud sessions | Yes, if the plugin was delivered | No |
In other words, mod panels do not appear in the mobile app or on claude.ai/code. They are not drawn in the VS Code extension either. If you build a mod that draws, assume it will be used in the terminal or the desktop app.
What the desktop app needs
According to the official docs, mods are enabled by default. The version requirement depends on where you run:
-
Terminal: Claude Code 2.1.287 or later. Check with
claude --version -
Desktop app: the app bundles its own Claude Code, and mods work from 2.1.286. Type
/statusin a local session in the Code tab and look at the version on the "Claude Code" line
The Claude Code inside the desktop app is separate from the one you installed for the terminal. Even if your terminal is up to date, the bundled desktop version may be older. When you use a new event or component, check first that the desktop version supports it. (Part 5 covers a case where registering an event that did not exist in that version made the whole mod disappear.)
Components available in the desktop app
Available UI components also differ by surface.
| Component | Terminal | Desktop |
|---|---|---|
Box, Text, Button, Link, Code, Markdown
|
Yes | Yes |
Input, Select
|
Yes | Yes |
Svg (SVG graphics) |
No | Yes |
Client (a region drawn by your own separate file) |
Yes | Yes |
Raster (a grid of colored cells), Image
|
Yes | No |
On the desktop, Svg is the most expressive component. You can draw charts and diagrams across the whole panel. Conversely, a mod built in the terminal with Raster cannot draw on the desktop (Part 6).
How to turn mods off
The official docs give three levels:
-
Turn off one mod: disable or remove that plugin in the Installed tab of
/plugin -
Turn off everything for one session: start with
--safe-mode(other settings are disabled too) -
Turn off everything permanently: add
"disableAllHooks": trueto~/.claude/settings.json
For the desktop app, the official install page says you can disable a plugin from the plugin management screen (+ → Plugins → Manage plugins). A later article in this series comes back to this.
Look at real mods
Seeing real mods is the fastest way to understand them. Anthropic keeps sample mods in claude-code/mods of anthropics/claude-code-playground (token-weather, blast-radius, replay-theater, and others). Claude Code's own /diff is built as a mod.
To browse public mods on GitHub in one place, you can use the modscode gallery. It read 1,383 public mods on GitHub and lists the 49 (as of 2026-10-06) that target the desktop app, run on Windows, and passed review, each with a reproduction of its actual UI. A gentler explanation of the mods concept is in What are mods. The official overview is at code.claude.com.
How this series is organized
Parts 2 to 4 are the minimum steps to build one mod for the desktop app. Parts 5 to 10 answer commonly searched problems. If you have a specific symptom, start with that part.
| Part | Topic |
|---|---|
| 2 | The minimal three files, and branching on e.surface
|
| 3 | Building a pane |
| 4 | Band, status line, toast |
| 5 | Nothing is drawn and there is no error |
| 6 | A mod built in the terminal breaks in the desktop app |
| 7 | It does not work on Windows |
| 8 | Asking Claude from a button does not work the first time |
| 9 | Distributing and installing through a marketplace |
| 10 | Telling whether a mod is safe |
Tested with Claude Code 2.1.286 to 2.1.288 (October 2026, Windows 11). Mods are brand new and change from version to version. Anything I could not confirm in the official docs is marked "not verified."
This article was written with AI assistance (Claude) and checked against the official Claude Code docs; anything marked "not verified" could not be confirmed there.
Top comments (0)