Anthropic
Blogcast

Alex: Hey everyone, welcome back to the Anthropic Blogcast. I'm Alex.

Jordan: And I'm Jordan. Today we're digging into a new post from Anthropic's developer blog, claude dot dev, and this one's a big deal for anyone who lives in Claude Code.

Alex: It is. The post is called Getting Started with Claude Code Mods. A mod is a small JavaScript or TypeScript file that runs inside your Claude Code session, and it can watch what's happening, change what Claude Code does, or draw its own interface right in your terminal or the desktop app.

Jordan: And the wildest part is the low barrier. You don't need to learn the mod A P I to try one. You just run claude, describe the mod you want in plain words, allow hot reload when it asks, and the mod shows up when the turn ends.

Jordan: The post goes deeper though. It explains what mods actually are under the hood, then builds one from scratch. So how does a mod differ from what Claude Code already lets you customize, like settings, permission rules, slash commands, skills, and the status line?

Alex: Claude Code already had a lot of knobs, but mods go further. A mod is a Claude Code plugin whose behavior lives in a JavaScript or TypeScript module. The folder is a normal plugin, with a manifest in a dot claude-plugin folder, and a hooks folder with a hooks dot json file naming exactly one module. That module exports a function called register. Inside it, you call an on function with an event name, an optional matcher, and a hook function.

Jordan: And under the hood, mods are hooks that ship inside plugins, and each one sees every event in your session as it happens. Tool calls, the prompt as submitted, turns starting and finishing, the session starting and ending, slash commands, and even the interface itself as it's drawn.

Alex: Exactly. Every hook has the same shape: a handler receiving three things. The dollar sign, which is the mods A P I, the event input as plain data, and a next function that passes the event down the chain to the other plugins and then to Claude Code's own behavior. Hooks form a chain, like middleware. Your hook runs, calling next hands the event on, and at the bottom Claude Code does what it would have done anyway.

Jordan: And the post boils every hook down to three moves: observe, rewrite, and answer. That's a really nice mental model.

Alex: It is. Observe means you call next first, look at the result, and return it, like recording every file edit or taking a reading after each turn. Rewrite means you pass a modified event into next, so the rest of the chain sees the changed version, like swapping a command for a safer one. And answer means you never call next at all. You return your own response directly, like refusing a tool call or serving a command yourself.

Jordan: There's also an important detail about where the module runs. It runs in a sandbox of its own, with no DOM and no Node, so everything outside goes through the dollar-sign A P I: user interface, session, state, storage, file system, processes, the clock, HTTP, tools, commands, and models.

Alex: Which is the key difference from the older settings hooks. A settings hook runs a shell command for each event and passes JSON over standard input and output. A mod is loaded once and stays in the session. It can keep state, draw interface elements that update as events happen, and call back into Claude Code: open a pane, run a process, register a slash command, or register a tool the model itself can call.

Jordan: And here's a credibility signal the post drops casually. Claude Code uses mods itself. Some of Claude Code's own features are built as mods, including the AGENTS dot md support and the slash diff pane beside the conversation. Their source, with tests, is in the public anthropics slash claude-code repository under a mods folder, so you can literally read how the team builds them.

Alex: Now the tutorial part. The post builds one mod from an empty folder, called Token Weather, a live forecast of the context window drawn above the prompt. It's about eighty lines of code. I love this example because context window anxiety is so real for every developer using these tools.

Jordan: It's such a good pick. Token Weather reads how full the context window is after each turn and draws one line above the prompt: a weather icon and word, the percentage, the tokens used out of the window, a small chart of recent turns, and how much the last turn added. Under twenty-five percent is Clear, twenty-five to forty-nine is Cloudy, fifty to seventy-four is Showers, seventy-five to eighty-nine is Storm, and ninety percent and up is Compact soon.

Alex: The hot reload lesson is the key insight. A module-level variable looks like the obvious place to keep history, but a hot reload is a fresh load, so module variables start over. You keep the history in the state A P I instead, which survives reloads, and you declare it in a small types file or the validate command stops you. You also get redraws for free, because a state read inside a render hook subscribes that drawing, so every later state write redraws the band automatically.

Jordan: Then it draws the forecast, appends a twelve-turn sparkline and the per-turn delta, and validates everything with claude plugin validate and claude plugin test. The test example stubs the usage numbers, mounts the interface, completes a turn, and checks the band moved from Clear to Showers at sixty-seven percent. It passes.

Alex: And sharing is simple because a mod is a plugin. Put it in a marketplace folder and install it from there, or submit it to the Claude directory so people can find it.

Jordan: But the post is upfront about the security model, and it matters. A mod is code that runs inside Claude Code on your machine, with the same access Claude Code has, and it's written by its publisher, not Anthropic. So install mods the way you'd install a package: read the repo first and only install from people you trust.

Alex: Now the two bigger mods the post tours. First, Blast Radius, the one every developer will immediately want. When Claude calls Bash with something dangerous, like a recursive remove, a hard git reset, a git clean, a force push, or a database migration, Blast Radius holds the call. It works out what the command would touch and opens a pane with Proceed and Cancel. Press two and Claude gets a refusal with the reason. Press one and the command runs as written.

Jordan: The example is holding a recursive remove of the build folder and listing the nine files, one point one megabytes, it would have deleted. It's the answer move in action: classify the command, measure what it would touch with dry-run commands, open a pane, and wait. Time spent waiting inside a dollar-sign call doesn't count against the hook's time limit. Too narrow for a pane, and the report draws above the prompt instead. But it's honest about being a safety net, not a permission system. It reads the command text, so shell substitutions and aliases can get past it. Use permission rules for a hard block.

Alex: Then there's Replay Theater, which steps through the last turn's edits. While a turn runs, it records every Edit and Write call, the file plus the text before and after. When the turn ends, a hint appears above the prompt. Press r, or type slash replay, and a pane walks through the edits one diff at a time with numbered steps. It never blocks or changes an edit. It purely observes, brackets the edits into one replay per turn, and registers its own slash command on session start.

Jordan: The post closes with four habits worth keeping, and these read like the team's distilled experience. Lean on the types Claude Code writes for you each time it loads your mod. Read component props from the props field, not the event top level. Plan for hot reload, keeping data in the state A P I, never module variables. And when a drawing doesn't show, run claude with the debug flag and look for the hook tree validation error.

Alex: The closing line is my favorite part. The three mods in the guide each came from one question: how full is my context, what is this command about to delete, and what did Claude just change. Your questions will be different, and that's the point.

Jordan: The big picture is that mods turn Claude Code from a tool you configure into a tool you program, with a chain of middleware over every event. One practical note: you need Claude Code version two point one point two eighty seven or later. Mods are on by default, and the generated types folder is the authority for your version. The A P I can change between releases, so treat those types as the source of truth.

Alex: That's the tour. Token Weather for the forecast, Blast Radius for the safety net, Replay Theater for the review. If any of these made you think of your own question, that's the whole invitation. Thanks for listening.

Jordan: Until next time.