Tech • AI • Robotics • Game
Mods in Claude Code: change how Claude Code works
5/10TL;DR
Claude Code now supports mods that can alter its interface and behavior by intercepting internal events, letting developers change rendering, prompts, tool calls, and add custom UI elements.
KEY POINTS
What mods can change
Mods function as plugins that run inside Claude Code and can directly modify core behavior. They can change what the app renders, alter data sent into prompts, influence which tool calls are made, and add custom interface elements, skills, and commands. The system allows developers to reshape both workflow and presentation rather than merely extending external features.
Examples of customizations
Early examples show how broad that flexibility is. One mod displays a live breakdown of context above the prompt, giving users more visibility into what the system is using. Another adds a side pane listing every agent in a project rather than only the active one, with single-click launching. A third hides email addresses on screen until the cursor hovers over them, designed to reduce accidental exposure during recordings.
How the mod system is structured
A mod uses the same plugin.json and hook.json structure as a standard plugin, with one important addition: hook.json includes a modules key pointing to a TypeScript file. That file contains the mod’s logic. In practice, the change turns a standard plugin package into one that can run code within Claude Code’s own event system.
Middleware-style event handling
Claude Code exposes dozens of internal events, including tool calls, permission checks, message execution, prompt emission, and rendering. A mod registers functions on those events, and each function runs whenever its event fires, immediately before Claude Code performs its normal action. The design closely resembles middleware, allowing developers to inspect, modify, or replace behavior at the point where it happens.
Three-part mod function model
Each event handler receives three inputs. The first is a $ object, which provides access back into Claude Code for actions such as rendering UI, calling the model, and reading files. The second is the event data itself, containing the specific information tied to that moment. The third is next, which determines what Claude Code does afterward by receiving the possibly modified event payload.
Ability to override default behavior
Developers can edit event data before passing it to next, and those changes become the action Claude Code executes. If a mod changes a command, the altered command is what runs. Calling next is optional: a mod can instead return its own result and fully handle the event, replacing Claude Code’s default behavior for that case.
How the email-hiding mod works
The email privacy example uses the render event, which fires just before a reply appears on screen. The mod scans reply text for email addresses and builds a replacement display block that reveals the address only on hover. Because it returns its own rendered version instead of calling next, Claude Code shows the modified output while keeping the underlying reply intact.
Display changes do not alter model context
The email-hiding example highlights a key distinction between presentation and model state. A render-only modification changes what appears on screen, but it does not change what the model used internally. As a result, a hidden email address can remain available for follow-up tasks such as drafting a message, even though the visible interface masks it from view.
Loading, reloading, and distribution
Mods can be loaded by starting Claude Code with a plugin dir flag pointing to the plugin folder. In the desktop app, where flags are unavailable, the same folder can be added through the global settings file. The folder is watched for changes, allowing a running session to pick up updates immediately after a file is saved. Because a mod is still packaged as a plugin, it can also be shared through a marketplace repository for installation by other users.
CONCLUSION
The new mod system turns Claude Code into a middleware-driven platform where developers can customize internal behavior as well as the user interface. Its combination of event hooks, sandboxed execution, and shareable packaging opens the way for deeper personalization and workflow control.
Ask a question