How to Write a Claude Code Plugin: Commands, Hooks, and My First Mod
My notes on how to write a Claude Code plugin: a manifest, a custom command, a hook, then a mod. The first one I want to build is a handoff panel.

This is my working note on how to write a Claude Code plugin of your own, not a shopping list. If you only want ready-made stuff to install, I keep that over in the best Claude Code mods I’d actually install. Here it goes the other way: you write the thing. A plugin can be as small as one custom slash command. It can carry hooks. And since October it can carry a mod, which is JavaScript running inside Claude Code that can even draw a panel. That last part is what got me going, honestly, because Claude Code can now write the extension for itself and load it into the session you’re already in.
Working with AI means repeating a lot of the same instructions: “Keep the sources.” “Run the checks when you’re done.” “Tell me what’s still unfinished.” Now we can build some of those expectations into the tools themselves. What I want is to spend less time checking up on the AI.
Anthropic put it pretty neatly in its October 1, 2026 announcement:
“You can also use Claude Code to mod Claude Code.”
Anthropic · Customize Claude Code with mods
How Claude Mods change Claude Code
That can sound a little like AI evolving itself. The part Anthropic has opened up is the Claude Code application. The model hasn’t changed because you installed a mod; what you can customize is the surrounding tool use, workflow, and parts of the interface.
The mechanism is straightforward. Submitting a prompt, calling a tool, and rendering the interface all produce events. A mod registers handlers in JavaScript or TypeScript to observe, modify, or take over those events. It could inspect a tool call before it runs, organize the result afterward, and display the information you care about in a side panel. Mods ship inside regular plugins, so you can install them, share them, and ask Claude to help write them. The interfaces are covered in the official documentation.
Skills, MCP, and Claude Code hooks already let users give AI instructions, connect tools, and run scripts. Mods open up more of Claude Code’s internals, especially its interface and interactions. You can turn your own review process into a panel or a set of buttons that works alongside the session. Anthropic has an official comparison of these capabilities. If you’re working out how to write a Claude Code plugin, get this straight first: a mod is one kind of plugin, not a separate thing, and a single plugin can hold skills, hooks and a mod together.
If you’d rather start with ready-made plugins, Anthropic’s official skills set and the community picks are in our best Claude Code mods list.
How to write a Claude Code plugin: the smallest version that works
I went through the official plugin docs before touching anything, and the smallest plugin is smaller than I’d assumed. It’s a folder. Inside it goes .claude-plugin/plugin.json with a name (no spaces, it becomes the prefix on everything the plugin adds), and if you like a description and a version. That’s the manifest. Every other folder sits next to .claude-plugin/, not inside it. The docs repeat that point more than once, which tells me plenty of people put things in the wrong place.
The first thing I’d put in is a custom command. Claude Code custom commands were merged into skills, so now you make skills/handoff/SKILL.md: a few lines of YAML on top (a description, plus disable-model-invocation: true if it should only run when you type it) and plain instructions below. Inside a plugin it shows up namespaced, as /my-plugin:handoff. The old commands/ folder of flat Markdown files still loads, it’s just the older form. Mine would be the three sentences I keep pasting anyway, which is what most Claude Code custom commands end up being. Keep the sources. Run the checks. Tell me what isn’t done.
Claude Code hooks are for rules that have to hold every single time, not whenever Claude happens to remember. In a plugin they go in hooks/hooks.json, same shape as the hooks block in a settings file. The docs’ own example is a PostToolUse hook with a Write|Edit matcher that runs a linter after each edit. I’d steal that one almost word for word.
Then the mod. A mod is a plugin that also has a hooks module, a hooks/register.js exporting register(on) and listening for events like tool.call or ui.render. Anthropic’s sample counts tool calls and shows the number beside the spinner, about twenty lines. You need Claude Code v2.1.287 or later in the terminal for mods.
my-plugin/
├── .claude-plugin/plugin.json
├── skills/handoff/SKILL.md
└── hooks/
├── hooks.json
└── register.js
No marketplace needed while you’re poking at it. claude plugin validate ./my-plugin checks the manifest and the frontmatter, claude --plugin-dir ./my-plugin loads it for one session, and /reload-plugins picks up your edits without a restart. Or skip the typing and just describe what you want, since Claude Code ships a built-in plugin-authoring skill for writing mods. I’d still read every line it writes (more on why near the end). That’s pretty much the whole answer to how to write a Claude Code plugin. The hard part is deciding what’s worth putting in one.
So if someone asks me how to write a Claude Code plugin in one breath, it’s four steps: write the manifest, add a skill for your custom command, put Claude Code hooks in hooks/hooks.json for the rules that must always run, and only then reach for a mod if you actually need UI. Load it with --plugin-dir after each step, and you’ll always know which piece broke.
3 useful Claude Mods examples
The three official examples make this easier to picture. Token Weather surfaces context usage so you know when to clean things up. Blast Radius shows the expected impact of certain risky commands before they run, then lets you proceed or cancel. Replay Theater walks through the changes from the previous turn. Finding out what the agent actually changed gets a little less tedious.
Those small features don’t look like much on a feature checklist. But one person wants to watch context usage, another reviews every change, and someone else needs to read sources while pulling together a conclusion. A vendor is unlikely to build everyone’s habits into the product. Users can now fill in the gaps around their own tasks, then share the extensions that work well for them. The three samples double as a crash course in how to write a Claude Code plugin, too, since each README says how it was built.
Claude Mods vs. DeepSeek Harness
DeepSeek was exploring this direction earlier. In the Harness source code from August 2026, the model adapter, tool registry, session log, and agent execution loop were already plugins. Its dynamic plugin tool from the same period also let AI inspect and extend the running environment, including the web interface. The Creator mode DeepSeek describes today brings runtime inspection, experimentation, and extension building into one workflow.
The scope differs. Claude Mods let you customize the existing Claude Code application; DeepSeek Harness builds more of its core components out of plugins. The timeline establishes that DeepSeek had related implementations earlier. It doesn’t establish who borrowed from whom. The shared direction is more interesting to me: users can start changing the environment their AI works in.
What the research says about AI workflows
SWE-agent offers a concrete example of how tools and feedback affect what an AI can finish. The NeurIPS 2024 paper ran the same GPT-4 Turbo model on 300 SWE-bench Lite tasks. In a shell-only environment with demonstrations, it resolved 11% of them. With a purpose-built agent-computer interface, that rose to 18%, a gain of 7 percentage points. The paper also compared editing interfaces: adding linting raised the resolution rate from 15% to 18%. See Tables 1 and 3 in the paper.
Those results come from an older model on a particular benchmark. They aren’t a productivity estimate for today’s Mods. They do show that tool design and the feedback an agent gets when something goes wrong can affect how much it finishes. Giving the agent a useful check result, then letting it try again, deserves careful design.

Then there’s the question of what the human actually gains. A METR survey published in May 2026 covered 349 technical workers. The median self-reported task speedup was 3×. Across three questions about the value of their work, median self-reported gains ranged from 1.4× to 2×. These were respondents’ estimates, and the sample had selection bias; the gains weren’t measured with a stopwatch. Here’s the original survey. For me, the useful reminder is to assess speed, output volume, and the value of the finished work separately.
My test for a mod is simple: once it’s installed, do I need fewer follow-up prompts, less digging through logs, or one less round of rework? If the AI produces more activity every turn but leaves me spending longer cleaning up after it, I’m not particularly interested. When I judge an agent, I also count the work it leaves for me after it hands off. If it writes code quickly and leaves me an hour of cleanup, that hour still belongs in the calculation.
The plugin I’d write first: a handoff panel
This is where how to write a Claude Code plugin stops being abstract for me. The first mod I’d like to build is a handoff panel. It wouldn’t need anything fancy. It would just lay out three things:
- What changed: the files, links to the affected pages, and the actual diffs.
- What was checked: the checks that ran, their raw results, and anything that failed.
- What’s left: anything that hasn’t been checked and decisions I still need to make.

Say I ask AI to fix Binmage’s language switcher. I’d want to see whether it tried all three languages, looked at the mobile version, and reproduced the problem on the initial page load. The results should open for inspection. Anything it didn’t do should say so. That would give me a handoff I can follow up on, instead of a long list of “optimized,” “fixed,” and “done” that leaves me guessing about the actual state of the work.
Reviewing Claude Mods before you install
The panel’s summaries also need evidence I can check. The official docs say Mods can rewrite tool results and even modify session-log lines before they’re stored. For an important release, I’d still want checks run by CI with separate permissions or another protected checking process. The panel can bring those results into view. I wouldn’t trust a completion report and its sign-off to the same set of records that the system can rewrite. That worry isn’t hypothetical: Epoch AI found an AI research report that left out what its own working notes said about selecting among experiment runs.
Installing a mod also means installing code. Knowing how to write a Claude Code plugin yourself doesn’t make it safe just because it’s yours. Mods can use your account’s permissions to read and write files, start processes, and access the network. Anthropic explicitly says there is no security sandbox. Code written with AI still needs review. A nice-looking panel doesn’t mean the code behind it is safe.
For now, this handoff panel is an idea, and my answer to how to write a Claude Code plugin is still from the docs, not from my own repo. Once I build it, I’d test it on real website changes: whether it cuts down on follow-up prompts, helps me spot unfinished work sooner, and makes the checks easy to rerun. If it lets me spend less time watching the agent without missing problems, it’s worth keeping.
If you try this yourself, start smaller than you think. One skill, one hook, --plugin-dir, done. That’s my advice on how to write a Claude Code plugin: get the simple parts working first, and add the mod after that.
Update, October 24, 2026: geckobox runs your Claude Code plugin setup on several machines
Once you know how to write a Claude Code plugin, the next thing people usually want is to run the agent somewhere other than your laptop. geckobox (its CLI is called openspaces) is a new open-source tool for exactly that, released under the MIT license. According to its README, it runs Claude Code and other coding agents on the machine you’re on, on any box you can reach over SSH, or inside a Docker container, and one command fans the same job out to several of those machines at once. The README also says there’s no account and no relay: it connects to your machines directly (it suggests Tailscale for machines behind NAT).
Installing it is a single npm command (it needs Node 20 or newer). openspaces ui opens a local dashboard on 127.0.0.1; the same things work from the command line:
npm install -g github:migasrias2/geckobox
openspaces ui
# or from the CLI
openspaces computers add mini ssh:[email protected]
openspaces run --on local,mini,docker:ci "run the tests and summarize failures"
Keep expectations in line with its age. It’s version 0.1.0, and the repo was created on October 20, 2026. Per the README, only the claude-code and shell adapters have been tested live; the Codex, Gemini and OpenCode adapters haven’t been. I haven’t run it across my own machines yet either.
Who it suits: people who already have a spare Mac mini, a VPS or a Docker host and want to send the same task (run the tests, check a deploy, clean up disk space) to all of them without signing up for a hosted service. If you work on one laptop, you don’t need it.
The risk deserves its own paragraph. --auto-approve gives the agent full permissions: in geckobox’s source it maps to Claude Code’s --dangerously-skip-permissions (and Codex’s --dangerously-bypass-approvals-and-sandbox). Combine that with fan-out, and one bad prompt, or a web page that slips instructions into the agent, can run arbitrary commands on several machines at the same time. Per the README, the default skips prompts only on docker: and cua: targets, while local and ssh: get Claude Code’s acceptEdits mode. Leave it that way at first: try it in Docker or on a test machine, and keep it away from boxes that hold production keys or customer data.
The README positions it as an independent, unaffiliated alternative to the paid Cua Spaces. The verifiable difference: on Cua’s pricing page, the free plan includes 2 live sessions and 20 remote hours a month through Cua’s hosted relay and Pro costs $15 a month billed yearly ($18 monthly) for 5 sessions and 200 hours, though spaces reached on your own network skip the relay and don’t count; geckobox, according to its README, has no relay at all, so there’s nothing to meter.
The repo:
Sources checked October 3, 2026; plugin, skill and hook docs rechecked October 20, 2026. This article draws on official documentation, historical source code, and original research. I haven’t independently tested Mods or Creator. The handoff panel is my proposed use case.
Claude Code hooks: quick FAQ
Claude Code hooks vs skills: what’s the difference?
A skill is instructions Claude chooses to use. A hook is a command, HTTP call, MCP tool, prompt or agent that Claude Code fires on its own at a fixed point, like before a tool call or when Claude stops. So if a rule must hold every time, it’s a hook. If it’s “here’s how we do X”, it’s a skill. They aren’t rivals either: the docs let a skill carry its own hooks in its frontmatter.
Where’s the full Claude Code hooks list and reference?
The official hooks reference has every event, from SessionStart and UserPromptSubmit to PreToolUse, PostToolUse and Stop, plus the JSON each one receives. It’s long. I keep it open in a tab and search it rather than read it. Typing /hooks inside Claude Code shows which hooks you actually have loaded and where each came from.
A Claude Code hooks example worth copying?
Two from the docs. A PostToolUse hook with an Edit|Write matcher that runs your linter after every edit, and a PreToolUse hook on Bash that blocks rm -rf. Both are a few lines of JSON plus a tiny script.
Any Claude Code hooks best practices?
The one that bit me: a hook that’s meant to block should exit with code 2, not 1. Exit 1 is a non-blocking error and the action just goes ahead. Also, a policy hook with a typo in its path silently never runs, so watch for the hook error on its first run, or set "onFailure": "block" (needs Claude Code v2.1.295 or later).
More on this: more Claude guides, more DeepSeek guides and AI subscription and API price comparison.