Claude Code Mods: install and build your first extension

What a Mod changes

A Mod packages executable event handlers in a Claude Code plugin. The event system lets a handler observe an action, pass a modified event onward, or return its own result. For example, a tool-call handler can record which tools run, while a prompt handler can transform input before the model receives it.

The interface API adds panes, buttons and text fields, and can change tool rows or the spinner. That makes Mods useful for a local task dashboard or a custom review interface. A small counter is a better first project than replacing your entire coding workflow.

Install an existing Mod

Check your version first:

claude --version

Use the plugin installation flow: add the author’s marketplace, open the plugin’s details, review its components, and choose local, project or user scope. Local scope limits the installation to you in this repository. The following names are placeholders; replace both with the author’s documented values:

/plugin install YOUR_MOD@YOUR_MARKETPLACE

Read the activation message. If you install from your shell while Claude Code is open, run /reload-plugins in that session or start a new one. In /plugin, inspect Installed to confirm the plugin is enabled. Disable or uninstall it there later.

Create a small Mod with Claude Code

The official authoring workflow uses the built-in /plugin-authoring skill. Try this request in an interactive session:

Create a Mod that counts tool calls and adds a /tool-count command.
Keep existing tool behavior unchanged. Validate it and explain its hooks.

Review the generated files before approving execution. Claude Code asks whether to enable session hot reloading; approved changes load when the turn ends. Generated session Mods are temporary, so copy a Mod you want to keep to your own directory. For a saved directory, the development commands are:

claude plugin validate ./my-mod
claude --plugin-dir ./my-mod

The example directory ./my-mod must already contain your plugin. A directory loaded with --plugin-dir supports hot reloading. Use the generated TypeScript declarations for your installed Claude Code version when checking API names.

Test before depending on it

Add tests that simulate tool calls and check your counter or command result. The Mod test runner can fire events and stub responses without a live session, sign-in or network. From the plugin directory, run:

claude plugin test

A test should confirm your intended behavior and that unrelated calls still pass through. Stub model and tool responses explicitly; a test result does not demonstrate that a real API integration works.

Where the interface appears

Check the official surface matrix before choosing an interface-heavy Mod. Cloud sessions do not automatically inherit your locally installed plugins.

Permissions and a clean troubleshooting session

A Mod runs with your user account’s access. It can reach files, environment secrets, processes and network services. Mods are not sandboxed; Claude Code’s Bash sandbox does not isolate programs a Mod starts. The organization controls describe the managed guard and its limits, including how Mod API calls differ from ordinary tool permissions.

Read the source and use validation to inspect its hooks and calls. Validation checks structure; it does not certify that an author is trustworthy. To investigate a regression, start a session with installed customizations disabled:

claude --safe-mode

For a Mod that does nothing, follow the troubleshooting guide: check its loaded status, validation output and debug log. A missing pane can be a surface limitation. A hook can also be skipped after an error, so confirm the expected behavior rather than relying on installation alone.

Choose the extension that fits the task

Use a Skill for reusable instructions, a settings hook for an existing event-driven script, and an MCP server for external tools. Choose a Mod when you need Claude Code runtime handlers or custom UI. A plugin can bundle several of these components.

This guide is Claude Code-specific because its Mod runtime belongs to that application. For a hosted bot, start with Hermes Agent skills or OpenClaw skill installation; a Claude Code Mod does not install directly into either framework.

Claude Code Mods FAQ

Related guides

• Hermes Agent skills
• Install OpenClaw skills
• Hermes Agent vs Claude Code
• 中文：Claude Code Mods 安装与开发指南