Claude Code mods and plugins, explained

People use "plugin" and "mod" for Claude Code almost interchangeably, and that gets confusing fast. I build Tokenbreak, which is a Claude Code mod, so I spend a lot of time explaining the difference. This post is the version I wish I could link people to.

Tokenbreak is an independent project and isn't affiliated with or endorsed by Anthropic. Everything below is my understanding as a mod author. The mod API is in early access, so check the current docs before you build on any detail here.

Plugins and mods

A plugin is the thing you install. You add a marketplace, install a plugin from it, and Claude Code loads whatever the plugin contains. For Tokenbreak that looks like this:

/plugin marketplace add tokenbreak/tokenbreak
/plugin install tokenbreak@tokenbreak

A mod is a plugin written as a set of function hooks that run inside Claude Code's interface. It listens for things that happen during a session and responds, usually by drawing something on screen. So every mod is a plugin, but plenty of plugins aren't mods.

What a mod can do

Function hooks

The core idea is one function: on(event, hook). You name an event and pass a function to run when it fires. The events I use most are these:

• session.start, when a Claude Code session begins
• turn.start, when you send a prompt and Claude starts working
• turn.complete, when Claude finishes that turn

That's enough to build a surprising amount. A turn timer is three lines of logic. A nudge to stand up every twenty turns is about the same.

Places a mod can draw

A mod can put things in a few parts of the screen.

The status line is the strip at the bottom of the screen. A mod can set it with $.ui.status. It's small and always visible, which makes it good for short facts that change often.

Above the prompt there's room for a one-line band, which a mod draws with ui.render into AbovePrompt. It's the spot people look at right before they type, so use it sparingly.

A Pane is a panel next to the conversation, also drawn with ui.render. It gives you the most room, but it needs space to exist, which comes up again in the limits section.

The shape of a small mod

Here's roughly what a tiny mod looks like. This one shows how long the last turn took, in the status line. It's simplified, and exact signatures may differ from the current docs, but the shape is right.

// Show how long Claude took on the last turn.
let startedAt = 0
 
on("turn.start", () => {
  startedAt = Date.now()
  $.ui.status("working...")
})
 
on("turn.complete", () => {
  const seconds = ((Date.now() - startedAt) / 1000).toFixed(1)
  $.ui.status(`last turn: ${seconds}s`)
})

That's the whole thing: two hooks and a variable. Most of the good mods I've seen are about this size.

A band above the prompt works the same way, just with a different surface:

// Say hello once when a session starts.
on("session.start", () => {
  ui.render(AbovePrompt, "Hello from a very small mod")
})

Two habits help a lot. Keep hooks fast, because they run while you're working, and give people a way to turn your mod off without uninstalling it.

How Tokenbreak uses these pieces

Tokenbreak is a mod that shows ads, so it uses all three surfaces:

When an ad is shown, the mod records which ad it was and when, along with a random device id. That's what it sends home, and it sends nothing else. You can pause it at any time:

/ads pause

Why Tokenbreak never touches the model's context

A mod can do two very different kinds of things. It can draw on your screen, or it can change what the model sees. Tokenbreak only ever does the first. It was the earliest design decision I made, and the one I'm least willing to bend on.

Tokens cost money

Anything added to the model's context gets processed as tokens. If ads went into the context, every ad would use up part of your plan or your bill, and you'd be paying to see ads. That would make the whole idea absurd. Because Tokenbreak only draws on screen, ads cost zero tokens.

Ads shouldn't steer the agent

If an advertiser's text sat in the model's context, it could influence what Claude writes. Even a harmless line like "Acme DB is great for this" might nudge a suggestion. That's prompt injection with a marketing budget, and I don't want to build it. Claude doesn't know Tokenbreak exists, and that's how it should be.

It doesn't need your prompts

To decide when to show an ad, Tokenbreak only needs to know that a turn started or finished. It doesn't look at what you asked or what Claude answered, and it never reads your code. Less access means less to secure and fewer reasons for you to distrust it.

The code is open source, so you can check all of this. I'd honestly prefer that you did.

The limits

The API is early access

The mod API is new and still moving. Hooks and surfaces may change between Claude Code releases, and a mod that works today can break after an update. If you build one, plan to keep up with changes, and don't make promises to users that depend on details that aren't stable yet.

Panes need a wide fullscreen terminal

A pane takes up columns, and a narrow terminal doesn't have any to spare. So panes only show up in wide fullscreen terminals. That's why Theater, Tokenbreak's image format, doesn't appear for everyone. In a split or a small window you'll only see the status line and the banner, which is what you'd want anyway.

Screen space is shared

You might run several mods at once, and they all want the same few spots. If you're building one, be polite about it. Use one line where one line is enough, and don't redraw constantly.

Building your own

Small mods are a good weekend project. I'd love a CI indicator in my status line, or a band that shows which branch I'm on before I send a risky prompt.

If you also build a website for your mod and want it to look like a terminal, the components on tokenbreak.dev are free. They're shadcn components with a terminal look, and each one installs with a single command:

npx shadcn add https://tokenbreak.dev/r/<name>.json

There's a terminal window, a split-flap display, and a copy of the prompt banner, among others. Use whatever helps.