Claude Code Mods: The Ultimate Guide

Updated October 5, 2026 · Covers Claude Code v2.1.287 and later · 9 min read

On October 1, 2026, Claude Code v2.1.287 shipped a feature called Mods — and within days, hundreds of developers were building them. Mods let you reshape Claude Code itself: the agent's behavior, and the terminal UI around it. This guide covers what mods are, how to install them, how to build your own, and the one safety question you must understand before installing any of them.

What Are Claude Code Mods?

Mods are TypeScript modules that hook into Claude Code's agent execution pipeline. Where slash commands and skills work at the prompt level — text in, text out — mods operate one layer deeper. They observe and modify what the agent does as it works, and they can draw their own UI in your terminal.

In practice, that means things like:

• Live lines above the prompt — progress bars, stock tickers, pixel pets, plan trackers that update in real time while the agent works.
• Guards — code that intercepts requests or responses: redacting secrets before the model sees them, filtering topics, enforcing project rules.
• Panes and dashboards — a live view of context usage, cost, background tasks, or your session's prompt history, navigable with hover and click.

The defining trait: mods run inside the Claude Code process, not beside it. That is what makes them powerful, and it is also what makes the safety section of this guide non-optional.

How Mods Work (Under the Hood)

A mod is a TypeScript module inside a Claude Code plugin. The module exports a register function, which subscribes to events in the agent's execution pipeline — requests going out, responses coming back, tool calls being made. When an event fires, your code runs, and it can observe, transform, or block what happens next.

For UI, mods get a dedicated $ API covering rendering, state, files, HTTP, and tools. The rule of thumb from early mod authors: use $ for everything; do not reach for Node or the DOM. UI updates hot-reload inside a live session, so iterating on a mod feels closer to web development than to plugin development — change the code, watch the terminal update.

Mods are distributed as plugins: a repository (or folder) containing a marketplace.json, with each mod defined by a plugin.json, a hooks/hooks.json, and the module file itself. The type definitions for your installed Claude Code version live in .claude-plugin/types/ — read those before you guess at the API.

How to Install Claude Code Mods

Installation goes through the plugin system. Inside Claude Code (CLI or desktop app):

/plugin marketplace add your-org/my-mods
/plugin install token-weather@my-mods
/reload-plugins

The same thing works from the shell, which is handy for scripting your setup:

claude plugin marketplace add ./my-mods
claude plugin install token-weather@my-mods --scope user

A few notes worth knowing:

• Anthropic's official marketplace, anthropics/claude-plugins-official, is already added — you only need marketplace add for third-party sources.
• --scope user installs the mod for your user account rather than a single project.
• Developing a mod? Skip the marketplace entirely and load a local folder: claude --plugin-dir ./my-mod.
• Before sharing a mod, validate and test it: claude plugin validate ./my-mod and claude plugin test ./my-mod.

(Install mechanics summarized from the excellent Claude Code Mods guide at pjfp.com — worth reading alongside this page.)

How to Build Your Own Mod

The shortcut: ask Claude Code. Describe the mod in plain language — which event to watch, what to draw, what should happen on Proceed or Cancel — and let Claude Code scaffold the plugin and the module. Iterate with hot reload until it behaves, then copy the folder out to keep or share it. This is genuinely the fastest path; the model knows the mod API well.

The manual path, for when you want full control:

1. Create the skeleton: plugin.json, hooks/hooks.json, and the module file.
2. Export register and subscribe to the pipeline events you care about.
3. Use $ for UI, state, files, HTTP, and tools. Do not reach for Node or the DOM.
4. Read the types in .claude-plugin/types/ for your installed version — they are the ground truth.
5. Run it with claude --plugin-dir while you iterate, then claude plugin validate and claude plugin test.

Good first mods: a live line showing something you check compulsively (CI status, token spend, time), or a guard that enforces a rule you keep forgetting (never commit without running the linter, never paste secrets). Small, visible, immediately useful.

Are Claude Code Mods Safe? Are They Sandboxed?

That does not mean you should avoid mods. It means you should install them the way you install anything with full access to your machine:

• Install from authors and repositories you trust. Prefer repos with history, stars, and readable code over a zip file from a forum.
• Read the code. Most mods are small TypeScript files. Skim the module before you install — look for network calls and shell execution you did not expect.
• Start with a safety mod. claude-code-redact redacts secrets and PII before the model reads them. If you run mods at all, run this one first.
• Keep production secrets out of reach. Do not run untrusted mods in a shell whose environment holds production API keys.

The ecosystem is four days old as of this writing. Norms around signing, review, and trusted marketplaces do not exist yet. Until they do, your own judgment is the sandbox.

Mods vs Plugins vs Skills: What's the Difference?

One plugin can ship several mods. Think of it as: plugins are how mods travel, mods are what runs, skills are what the model reads.

Where to Find Mods

That is what this site is for. Browse the full directory of 22 mods — searchable, filterable by category, each with its source repository. If you want a shortcut, start with our Best Claude Code Mods list: the ten mods worth installing first, updated as the ecosystem grows.

Two more resources worth bookmarking: awesome-claude-code-mods, the community catalogue this directory is partially built from, and the pjfp.com mods guide for a second opinion on the mechanics.

Guides & References

Deeper dives for specific needs:

• How to Install Claude Code Mods — marketplace add/install, scopes, local folders, OS notes, troubleshooting.
• Claude Code Mods vs Plugins — what each term actually means, and where skills fit in.
• Build Your First Claude Code Mod — scaffolding, the file skeleton, hot-reload iteration.
• Best Mods for Code Review — what reviewers install while dedicated review mods do not exist yet.
• Best Mods for Testing — xcode-mods and the building blocks of test automation.
• Claude Code Mods FAQ — sandboxing, cost, safety, and the other questions everyone asks.

Frequently Asked Questions

What are Claude Code mods?

TypeScript modules that hook into Claude Code's agent execution pipeline, changing agent behavior and terminal UI. They launched with Claude Code v2.1.287 on October 1, 2026.

How do I install Claude Code mods?

Run /plugin marketplace add <owner>/<repo> then /plugin install <mod>@<marketplace> inside Claude Code, or the equivalent claude plugin shell commands with --scope user.

Are Claude Code mods sandboxed?

No. Mods run with the same permissions as Claude Code itself and can read environment variables including API keys. Only install mods from sources you trust, and read the code first.

How do I build my own mod?

Describe it in plain language and let Claude Code scaffold it — fastest path. Or manually create plugin.json, hooks/hooks.json and the module, export register, build UI with the $ API, then validate and test.

What's the difference between a mod and a plugin?

A plugin is the distributable package (marketplace entry); a mod is the TypeScript module inside it that hooks the agent pipeline. One plugin can contain multiple mods.