Claude Code mods are small JavaScript or TypeScript files that run inside a Claude Code session. A mod can observe what happens, change what Claude Code does, or draw its own UI in the terminal or desktop app. No API knowledge is required to try one: you can start a session, describe the mod you want, allow hot reload when asked, and the mod appears when the turn ends.

Under the hood, a mod is a Claude Code plugin whose behavior lives in one module. The folder has a normal .claude-plugin/plugin.json manifest, hooks/hooks.json names the module, and the module exports register(on). Inside it, on(event, matcher?, hook) adds a hook. Each hook receives $, the mods API for ui, session, state, store, fs, process, clock, http, tool, command, and model; e, the event input as plain data; and next, which passes the event on. Hooks form a chain like middleware. A hook can observe by calling next and inspecting the result, rewrite by returning a modified event, or answer by returning a denial without calling next. Events cover tool calls, prompt submission, turns, sessions, slash commands, and ui.render.

Mods differ from settings hooks. A settings hook runs a shell command per event and passes JSON over stdin and stdout, while a mod is loaded once, stays in the session, can keep state, draw updating UI, and call back into Claude Code. Anthropic uses mods internally for AGENTS.md support and the /diff pane; their source lives in the public anthropics/claude-code repository under mods/.

The guide builds one mod, Token Weather, from an empty folder. It reads context-window usage after each turn and draws a forecast above the prompt: a weather icon, percentage, tokens used, a sparkline of recent turns, and last-turn delta. The shortcut is to let Claude build it from a plain-language prompt; the longer path covers six steps: creating the plugin folder, drawing a first band by hooking ui.render on AbovePrompt, reading real numbers from $.session.usage(), keeping history in $.state so it survives hot reloads, validating with claude plugin validate, and testing with claude plugin test against the real runtime.

Two larger mods show the API’s range. Blast Radius holds risky Bash commands like rm -rf or git reset –hard, works out what they would touch, opens a pane with Proceed and Cancel, and can degrade to drawing above the prompt when the terminal is narrow. Replay Theater records every Edit and Write during a turn, then lets you step through the edits one diff at a time in a pane. It teaches pairing events, registering slash commands, and reading files through $.fs.

The guide closes with four habits: rely on the type declarations Claude Code writes into the plugin’s .claude-plugin/types/ folder, read props from e.props, plan for hot reload by keeping data in $.state rather than module variables, and check the debug log when a drawing does not validate. Mods are shared as plugins through marketplaces, with three install commands. The source notes that a mod has the same access as Claude Code and is written by its publisher, not Anthropic, so install only from trusted sources.