MemoryLake
Back to all articles
TutorialNovember 16, 2026·11 min read

What Can Claude Code Mods Do? How They Differ From Hooks and Plugins, What a Mod Keeps Between Sessions, and Why /clear Resets Its State (2026)

You installed a Claude Code mod that adds a pane beside the transcript: a running tally of the files Claude touched and the decisions you made along the way. It was useful all afternoon. Then you ran /clear to start fresh, and the pane went back to empty. The next morning, a different counter in the same mod still remembered yesterday's total.

That's how Anthropic's documentation says mod state works. A mod can keep values in different places, and each place lasts a different length of time. One of them resets when "the user runs /clear, /resume, or /branch". Another is shared by every session on your machine and survives from one day to the next.

Mods are one of the newer ways to customize Claude Code, and they can do things the other options can't. This guide covers what a mod is and what it can do, how mods differ from settings hooks, skills, plugins, and MCP servers, how to install one and decide whether to trust it, where mods run, what a mod keeps between sessions, how to turn mods off, and where your project context belongs instead.

What a mod is

Anthropic's documentation starts with a definition: "A mod is a plugin that changes how Claude Code looks and behaves."

A mod is code. "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."

The documentation calls those handlers hooks, which can be confusing, because Claude Code already has hooks you configure in a settings file. On the mod pages, Anthropic calls the settings-file kind a settings hook. The difference is where they run: "A mod's handlers are functions that run inside Claude Code instead."

A small mod is three files: a plugin manifest, a hooks.json that points to the code, and a code file that registers the handlers.

What a mod can do

Because a mod runs inside Claude Code, Anthropic lists things it can do that settings hooks, skills, status lines, and MCP servers can't:

  • Draw an interface you can use, such as a pane beside the transcript or a band above the prompt, with tabs, buttons, and text fields.
  • Redraw Claude Code's own interface, such as a tool call's row, the spinner, or the dialog Claude asks questions in.
  • Step into a tool call or a request, for example holding a tool call while you're asked a question, or sending a request to a different model.
  • Run your own code on a command, a /command that runs at once, with no Claude turn, even while Claude is working.
  • Share data between hooks, so one hook can record something and another can display it.

Some of Claude Code's own features are built as mods. The built-in list includes /diff, and a built-in mod that "Loads AGENTS.md as project instructions". You can see built-in mods in the Installed tab of /plugin, but "You can't update or uninstall a built-in mod."

How mods differ from settings hooks, skills, plugins, and MCP servers

Plugins. A mod isn't a separate thing from a plugin. It installs as a plugin, from a marketplace, and a plugin can hold a mod alongside skills, commands, agents, and MCP servers.

Settings hooks. A settings hook is a shell command, HTTP request, or prompt that Claude Code runs on a lifecycle event. It can allow, block, or change a tool call or prompt, and add context for Claude, but it can't draw anything. We covered settings hooks, and which ones can add context, in our guide to what Claude Code hooks are.

Skills. A skill is a SKILL.md file of instructions Claude reads. It changes what Claude knows and does, not what Claude Code does.

MCP servers. An MCP server gives Claude tools to reach an external system.

Anthropic's comparison sums up when to pick a mod: when you want a pane, a band above the prompt, a custom command, or to rewrite an event. If a settings hook, a skill, or an MCP server already does what you need, the documentation suggests comparing them before writing a mod.

Installing a mod, and deciding whether to trust it

You install a mod the way you install any plugin: run /plugin install with the plugin name, an @, and the marketplace name in a session. If you install from your shell while a session is open, run /reload-plugins to load it.

Anthropic also shares sample mods in a public repository, such as one that draws a forecast of your context window above the prompt and one that holds a risky shell command and shows what it would change.

Before installing, take the warning seriously. "A mod is code that runs with your permissions." The documentation lists what a mod can reach once it loads, including your files, your environment variables and settings files, and your session: "every prompt you send and every tool call Claude makes".

And: "Mods aren't sandboxed." If you turn on sandboxing, it isolates the Bash commands Claude runs, but a process a mod starts runs outside it.

There are limits. "A mod can restyle much of Claude Code's interface, but not the permission prompt." And Anthropic describes a built-in guard that, when loaded, by default stops a user's mod from approving tool calls your rules or hooks would stop.

To see what a mod does before you install it, run claude plugin validate on its folder. The output lists the events the mod handles and what it asks Claude Code to do.

Where mods run

Mods work in the Claude Code CLI, the Code tab of the Claude Desktop app, and the VS Code extension. Anthropic's table adds the edge cases:

  • claude -p and the Agent SDK: hooks run, but nothing is drawn.
  • Remote Control: hooks run in the session on your machine, and drawing appears in the terminal there.
  • Cloud sessions: hooks run for a plugin that reaches the cloud session, but nothing is drawn.
  • WSL sessions in the Desktop app: mods don't run, because plugins aren't available there.

A mod that draws can check where it's running and fall back to a line in the transcript or a command's text reply.

What a mod keeps between sessions

This is the part worth understanding before you rely on a mod. Anthropic's documentation says: "Where a mod keeps a value decides how long the value lasts: until the module reloads, until the session ends, or from one session to the next."

There are three places:

A module-level variable. It lasts until the module reloads, which during development happens every time you save a file. Anthropic describes these as values you can lose.

$.state. It lasts until "The session ends, or the user runs /clear, /resume, or /branch". It's meant for values a drawing depends on that should survive a module reload. That's why the pane in the opening example went blank after /clear.

$.store. It lasts until the mod deletes the value, or until no session reads or writes the store for the cleanupPeriodDays period. Anthropic describes it as "A key-value store that every session on the machine shares." It's saved as a JSON file of the plugin's own under ~/.claude/plugins/store/, and the documentation lists settings, history, and "anything the user expects to find next time" as what it's for.

So the counter that remembered yesterday's total was in $.store. The pane that reset was drawing from $.state.

A well-built mod bridges the two. Anthropic notes that if a mod copies a saved value from $.store into $.state when a session starts, it has to copy it again after /clear, /resume, or /branch, because those commands reset $.state and the session-start hook doesn't fire again. If a mod's display resets when its data shouldn't, that's the place the author needs to look.

Two practical points follow. A mod's store is on your machine, shared by sessions there, so it isn't the same as something your teammates or another computer can see. And it's subject to the same retention period Claude Code uses elsewhere, if nothing touches it.

How to turn mods off

"Mods are on by default." To stop them, Anthropic lists three levels:

  • One mod: disable or uninstall its plugin from the Installed tab in /plugin.
  • Every installed mod, for one session: start Claude Code with --safe-mode, which also disables your other customizations.
  • Every mod you installed, in every session: set disableAllHooks to true in ~/.claude/settings.json. Your settings hooks and custom status line stop too.

Built-in mods are different: "The settings and flags that stop installed mods, such as disableAllHooks, --bare, and --safe-mode, don't stop built-in mods." Organizations can also limit which mods load through managed settings.

What people try first

Expecting a mod's pane to survive /clear. $.state resets on /clear, /resume, and /branch.

Expecting a mod's data on another machine. $.store is shared by sessions on the machine where it's saved.

Installing without checking. Run claude plugin validate to see what a mod does.

Assuming the sandbox covers mods. Mods aren't sandboxed.

Using a mod for project knowledge. A mod changes how Claude Code behaves; project knowledge belongs in instruction files.

The Fix: Use mods for behavior, and keep context elsewhere

Step 1: Check what a mod does before installing

Run claude plugin validate on its folder and read the events and calls it lists.

Step 2: Know where each value lives

If you write a mod, put values that must survive /clear in $.store, and reload them into $.state after a reset.

Step 3: Keep project knowledge in instruction files

Conventions and structure belong in CLAUDE.md or AGENTS.md, which load as project instructions.

Step 4: Write down what you learn in a session

A mod's pane can track progress, but the decisions behind it should be recorded somewhere that outlasts the session and the machine.

Setting this up in MemoryLake

A mod is a good way to see what's happening in a session. The decisions and lessons from that session, such as which approach worked or why a file is off-limits, need a home that doesn't reset on /clear and isn't tied to one machine.

MemoryLake is a memory layer for that kind of project context, such as decisions, conventions, and lessons learned, kept in one place you maintain and available to the assistants you connect, such as ChatGPT, Claude Code, and Codex.

You write the entries yourself, in your own words. Nothing is read out of, written to, or deleted from your mods, their $.state or $.store, your plugins, your settings files, your sessions, or any vendor's store. Mods and their state work the way Anthropic describes them.

Step 1: Create an API key

Sign in and generate a key from the dashboard. Keep it out of plugin and mod code, like any other credential.

The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent
The MemoryLake console showing the API keys screen, where a new key is created and copied for use in an agent

Step 2: Upload your first memories

Start with what you wrote in Step 4 of the fix: decisions from recent sessions, conventions you rely on, and lessons you don't want to relearn. One decision per entry.

The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory
The MemoryLake workspace with the first documents uploaded, listing each file as it becomes searchable memory

Step 3: Connect your AI & agents

Connect Claude Code and the other assistants you use. A new session, or another machine, can draw on the same entries.

The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer
The MemoryLake integrations screen listing the AI clients and agent frameworks that can be connected to the memory layer

What this changes in practice

The first difference is that /clear stops costing you context. A mod's display can reset, and the decisions are still written down.

The second is portability. What you learned isn't tied to one machine's store.

The third is a cleaner split. Mods handle how Claude Code behaves, and your project context lives in one place.

Best practices for Claude Code mods

Treat mods as code. They run with your permissions and aren't sandboxed.

Validate before installing. claude plugin validate lists what a mod does.

Reload after shell installs. Run /reload-plugins in an open session.

Know the three lifetimes. Variables, $.state, and $.store each last a different length of time.

Expect resets on /clear. $.state goes back to its defaults.

Use --safe-mode to troubleshoot. It disables installed mods for one session.

Keep context out of mods. Use instruction files and a memory you maintain.

Conclusion

A Claude Code mod is a plugin made of JavaScript or TypeScript handlers that run inside Claude Code. It can draw panes and bands, redraw parts of the interface, step into tool calls and requests, and add commands, which settings hooks, skills, and MCP servers can't. It also runs with your permissions and isn't sandboxed, so validate before you install.

What a mod keeps depends on where it stores a value. Module variables last until a reload, $.state lasts until the session ends or you run /clear, /resume, or /branch, and $.store persists across sessions on your machine until the mod deletes it or it goes unused for the retention period. For context that has to outlast all of that, write it down somewhere you maintain.

Frequently asked questions

What is a Claude Code mod?

A plugin made of JavaScript or TypeScript event handlers that Claude Code calls when events happen. Anthropic says a mod changes how Claude Code looks and behaves.

How are mods different from Claude Code hooks?

Settings hooks run a shell command, HTTP request, or prompt from a settings file. A mod's handlers are functions that run inside Claude Code and can also draw in the interface.

Why did my mod reset after /clear?

$.state lasts until the session ends or you run /clear, /resume, or /branch.

Do mods remember anything between sessions?

Yes, if they use $.store, a key-value store shared by every session on the machine and saved under ~/.claude/plugins/store/.

Are mods safe?

A mod runs with your permissions and isn't sandboxed. Install mods only from authors and marketplaces you trust, and check them with claude plugin validate.

How do I turn off all mods?

Start with --safe-mode for one session, or set disableAllHooks to true in ~/.claude/settings.json. Built-in mods aren't stopped by these.

Where do mods work?

In the Claude Code CLI, the Code tab of the Claude Desktop app, and the VS Code extension. In claude -p and cloud sessions, hooks run but nothing is drawn.