Claude Code Mods: A Beginner's Guide to Customizing Your AI Coding Agent

Claude Code mods are small TypeScript modules that hook into Claude Code's internal events to change how it behaves. Launched by Anthropic on October 1, 2026, a mod can rewrite a prompt before it reaches the model, block or retry a tool call, approve or deny a permission request, redact secrets from tool output, add slash commands, or redraw parts of the interface. Mods ship inside plugins, so you install them with /plugin, and you can write one in a few lines of TypeScript, or ask Claude to write it for you.

Mods turn Claude Code from a tool you configure into a runtime you can program. This guide explains what that means for vibe coders, with a working example. For the wider news context, see our October 2026 AI news roundup.

What can a mod do?

A mod registers handlers for events, such as a tool call, a submitted prompt, a slash command or a piece of the UI being drawn. Each handler can observe the event, rewrite it, or answer it directly. That enables things like:

• Guardrails: block edits to .env files, or refuse destructive commands like rm -rf and force-pushes.
• Secret redaction: strip API keys from command output before the model sees them.
• Prompt tweaks: automatically append your team's conventions to every request.
• Custom UI: panes, a status line, a band above the prompt, restyled tool-call rows.
• New commands: slash commands that run without a Claude turn.
• Model routing: send certain requests to a different model.

Anthropic converted three of Claude Code's own built-in features into mods at launch: the /diff view, AGENTS.md loading, and telemetry. That's a strong signal mods are a core part of the product, not an experiment.

Mods vs hooks vs skills vs MCP

Claude Code has several ways to extend it, and they're easy to confuse:

They work together. A team might use an AGENTS.md file for project context, a skill for their release process, an MCP server for their database, and a mod to enforce safety rules.

Installing a mod

Mods are distributed inside plugins, so you install them like any plugin:

/plugin install some-mod@some-marketplace

Mods work in the CLI and the desktop app's Code tab. Update Claude Code first (claude update); mods need a recent version.

Install mods carefully

Mods are not sandboxed. They run with the same permissions as Claude Code itself: they can read your files and secrets, and they can approve tool calls on your behalf. A malicious mod is as dangerous as any malicious software you run. Only install mods from sources you trust, read the code of anything small enough to read, and prefer mods with many users and visible maintainers. This matters even more after this month's coding agent security disclosures, which included attacks on plugin updates.

Your first mod: a safety guardrail

Here's a small mod that does two useful things for vibe coders: it stops the agent from editing .env files, and it blocks a few destructive shell commands. A mod is a plugin folder with three files:

safety-guard/
├── .claude-plugin/
│   └── plugin.json
└── hooks/
    ├── hooks.json
    └── register.ts

.claude-plugin/plugin.json describes the plugin:

{
  "name": "safety-guard",
  "version": "0.1.0",
  "description": "Blocks .env edits and destructive shell commands"
}

hooks/hooks.json points to the module:

{ "modules": ["./register.ts"] }

And hooks/register.ts contains the logic:

import type { Register } from 'claude-code';

const PROTECTED_FILE = /(^|\/)\.env(\.|$)/;
const DANGEROUS = [/\brm\s+-rf\b/, /\bgit\s+push\b.*--force\b/, /\bgit\s+reset\s+--hard\b/];

export const register: Register = (on) => {
  // Refuse edits to environment files
  on('tool.call', { tool: 'Edit' }, ($, e, next) =>
    PROTECTED_FILE.test(e.file_path)
      ? { deny: `${$.plugin.name}: ${e.file_path} is protected.` }
      : next(e),
  );

  // Refuse destructive shell commands
  on('tool.call', { tool: 'Bash' }, ($, e, next) =>
    DANGEROUS.some((pattern) => pattern.test(e.command))
      ? { deny: `${$.plugin.name}: blocked a destructive command. Ask the user to run it manually.` }
      : next(e),
  );
};

How it works:

• on('tool.call', { tool: 'Edit' }, ...) runs whenever Claude tries to use the Edit tool.
• Returning { deny: '...' } blocks the call, and Claude sees the reason.
• Calling next(e) lets the call continue normally. You could also pass a modified event to next to rewrite it.

You can validate a mod with claude plugin validate <folder> and test it with claude plugin test <folder>. Anthropic's Claude Code docs↗ (opens in a new tab) cover the full event list and the UI APIs.

The easiest way to write a mod? Ask Claude Code: "Write a mod that redacts anything that looks like an API key from Bash output." It knows the API.

Mod ideas for vibe coders

• Cost meter: show token usage for the session in the status line.
• Commit reminder: nudge you to commit after several successful edits.
• Test gate: block "I'm done" summaries until tests have passed in the session.
• Secret scrubber: redact keys from tool output so they never reach the model.
• Project rules injector: append your security rules to every prompt touching auth or payments.

Within days of launch the community had published dozens of open-source mods, from token usage charts and CI status overlays to, inevitably, a playable game of Tetris inside a session pane.

Frequently asked questions

When did Claude Code mods launch?

Anthropic launched mods on October 1, 2026.

Do I need to know TypeScript to use mods?

Not to install them. Writing one takes a little TypeScript, but Claude Code can write mods for you from a plain-English description.

Are Claude Code mods safe?

They're as safe as the code inside them. Mods aren't sandboxed and run with your permissions, so only install mods you trust.

Do mods work in VS Code or headless mode?

Mods run in the CLI and the desktop app's Code tab. Hook-based behavior also runs in headless mode (claude -p), the Agent SDK and the VS Code panel, but UI elements depend on the surface.