<- all tokdocs

Claude Code Mods: What They Do and Which Viral Use Cases Need One

By , founder of Mavric and Apso

View on TikTok ->

Claude Code mods are plugins made of JavaScript or TypeScript event handlers that change how Claude Code looks and behaves. They shipped in v2.1.287 on October 1, 2026. A popular TikTok lists three things to do with them, but one of the three, making sessions talk to each other, worked before mods existed and needs no mod at all.

The video, from @nocode.joshua, posted five days after the release.

What is a Claude Code mod?

The Claude Code changelog lists "Added Claude Mods" under v2.1.287, October 1, 2026, noting that "plugins may now modify deeper behavior." The mods overview defines one: "A mod is a plugin that changes how Claude Code looks and behaves. It's made of JavaScript or TypeScript event handlers: Claude Code calls one when an event happens, such as a tool call, a submitted prompt, or a part of the interface being drawn, and the handler can watch the event, change it, or take it over."

Two version floors apply. The terminal CLI needs v2.1.287 or later. The Desktop app ships its own copy of Claude Code and supports mods from v2.1.286.

Do you need a mod to make Claude Code sessions talk to each other?

You do not, and this is the video's biggest error. It says "one claude code session can now send a message to another so one can plan while the other builds," and presents that as a mod feature.

Cross-session messaging is older. The cross-session messaging page says it "requires Claude Code v2.1.224 or later on macOS and Linux, including Linux inside WSL 2. On native Windows, it requires Claude Code v2.1.234 or later." It also says "messaging is on with nothing to enable." Claude finds the other session with ListAgents and sends with SendMessage. You can type @api-worker in a prompt or just ask in plain language.

What mods add is control over that traffic. The mods API provides $.session.send({ to, text }), "the same delivery the SendMessage tool makes," plus session.send and session.receive events. A hook can block a message from arriving or leaving, so a mod can filter, log or redirect messages.

One cost the video skips: the costs page says Claude Code "delivers a message from another of your sessions as a new turn when this session sits idle, sending your full context each time."

Can a mod add a dashboard inside Claude Code?

A mod can do this. The overview lists "Draw an interface you can use: a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields."

The mods reference names render sites including Pane, AbovePrompt, Spinner and ToolUse.

"Right inside Claude Code" needs a caveat. The overview says "only the terminal and the Desktop app show a mod's panes, bands, and replaced rows." Hooks still run in the VS Code extension, claude -p, the Agent SDK and cloud sessions, but nothing a mod draws appears there. A mod also cannot restyle the permission prompt.

Can a mod route simple tasks to a cheaper model?

A mod can do this. The reference documents turn.step, which "Fires when one request is about to go to the model." A hook can return next({ ...e, model }) to send that request to a different model. agent.spawn lets a hook choose a subagent's model, and $.model.complete can make a one-off call with model: 'haiku'.

The model configuration page lists haiku ("Fast and efficient Haiku model for simple tasks") and opus ("Latest Opus model for complex reasoning tasks") as current aliases.

Does routing to Haiku save your usage limits?

Routing helps only partly. The video says simple tasks "stop eating into your limits." The costs page says subscription session and weekly limits are "shared across all models, so the developer can't restore access by switching models with /model."

Per-family limits are different. After a "You've hit your Opus limit" message, the costs page says switching to a model outside that family "does keep the developer working." So routing a typo fix to Haiku spends fewer tokens against your shared window and leaves your Opus budget alone. It does not take those requests off your limits.

A mod's own model calls also count. The API page says "These calls use the user's plan or API key."

Can Claude build a mod for you?

Claude can write one. The create page says "Describe the mod you want in an interactive Claude Code session, and Claude writes it." Claude uses a built-in skill named plugin-authoring and writes into ~/.claude/dev-mods/. The video's claim that "you don't need to know anything technical" leaves out four things:

  • You approve every file. In default and acceptEdits modes, Claude Code asks before creating each file, because ~/.claude is a protected path. A second prompt asks about hot reloading.
  • The mod is temporary. It loads only in the session that made it and is deleted after cleanupPeriodDays. To keep it, copy it out and run claude --plugin-dir ~/mods/git-branch, or publish it.
  • Some sessions block it. A Claude-written mod will not load in claude -p runs, dontAsk mode, untrusted workspaces, or where --safe-mode, --bare, disableAllHooks or managed settings block mods.
  • It runs as you. The overview warns: "A mod is code that runs with your permissions. It can read and write your files, start processes, and make network requests." It can read API keys in environment variables and approve tool calls "before you're asked." The docs add: "Mods aren't sandboxed."

Before running a mod, claude plugin validate ./some-mod lists every event it handles and every API method it calls, without executing the code.

Bottom line

Mods are real and shipped on October 1, 2026, so "just dropped" was accurate. Dashboards and model routing both need a mod. Session-to-session messaging does not, since it has worked since v2.1.224. Routing to Haiku slows how fast you use a shared limit without removing those requests from it. A mod Claude writes for you runs unsandboxed with your full permissions, so check it before you keep it.

Sources

Published October 6, 2026. Based on a TikTok by @nocode.joshua. Full video notes (markdown)