Mods in Claude Code: change how Claude Code works

Summary

Claude Code includes a modding system that allows developers to customize how the application functions, what it renders, and how it handles internal operations. Mods can modify prompt payloads, intercept tool calls, add custom commands, and render custom user interface components.

Three concrete examples demonstrate the scope of what mods can achieve. The first is a context bar rendered above the terminal input that provides a live visual breakdown of token allocation across system prompts, tools, Model Context Protocol tools, agents, skills, and memory files. The second is an agents panel that lists all declared agents in a project sidebar, enabling users to run any agent with a single click. The third is an email masking tool designed for screen recording, which redacts email addresses appearing in output until a user hovers over them.

Architecturally, a mod is a Claude Code plugin with a plugin.json file and a hooks.json configuration file. The hooks.json file includes a modules key that specifies a TypeScript file, such as register.tsx, containing the mod logic. Within this script, developers register handlers against dozens of internal Claude Code lifecycle events, including ui.render, prompt.submit, session.start, engine.create, and tool execution checks.

Every event handler receives three parameters: a dollar sign helper object, an event payload, and a next function. The dollar sign helper provides access to core Claude Code operations such as rendering UI components, issuing model queries, and reading files. The event payload delivers the incoming data for that specific lifecycle stage, which can be modified before being passed forward. The next function works as a standard middleware callback. If the mod invokes next, Claude Code proceeds with the modified or original data. If the mod returns a custom component or value without calling next, it handles the event entirely and bypasses the default behavior.

Mods run inside an isolated sandbox and only interact with the application through the provided event parameters and helpers. For instance, modifying rendered text in a ui.render handler alters only the display presentation on screen, ensuring the underlying language model continues to receive unmodified text during subsequent tool runs or message generation.

To run mods in the terminal, users start Claude Code with the plugin directory flag pointing to the mod folder. In desktop applications, the folder path can be configured within the settings.json file using environment variables alongside a watcher flag that reloads mods automatically on file save. Mods can also be registered in a marketplace manifest and installed across environments with the plugin install command.