DEV Community: Pawel

5 JsonLogic Mistakes Every AI Coding Agent Makes

Pawel — Sat, 10 Oct 2026 16:32:57 +0000

Ask any LLM to write a JsonLogic rule and it will happily produce something that looks right. Then you run it and get false when you expected true, or an operator your library never implemented. I got tired of debugging hallucinated rules, so I packaged the fix as an open-source agent skill: jsonlogic-skill.

What it does

Drop it into your AI coding assistant and it picks JsonLogic up automatically. You describe the business requirement in plain language, and the assistant:

turns it into a valid JsonLogic rule (checked against the real standard, not vibes),
runs the rule against your data,
validates whether an existing rule is well-formed,
explains what a rule does, in words,
debugs rules that return the wrong result.

It knows the actual operator set from jsonlogic.com and, importantly, checks whether your language's JsonLogic library supports the operators it wants to use. JavaScript, Python, Ruby, PHP, Java: one rule, many runtimes, no surprises.

Install

It follows the open Agent Skills format, so it works with Claude Code, Cursor, GitHub Copilot, VS Code agent mode, Codex, and Gemini CLI. For Claude Code:

git clone https://github.com/valeryia-piatrova/jsonlogic-skill.git ~/.claude/skills/jsonlogic

Restart the client and you are done. Every other client has its own one-liner in docs/installing.md.

A quick example

You type:

Give a 20% discount on orders over $200, or 10% over $100, otherwise no discount

The assistant produces:

{
  "if": [
    { ">": [{ "var": "total" }, 200] }, 0.20,
    { ">": [{ "var": "total" }, 100] }, 0.10,
    0
  ]
}

...and validates it before showing it to you. No data shape? It asks. Data shape given? Field names come from your JSON, not from the model's imagination.

Why a skill and not a prompt

A prompt tells the model what JsonLogic is. A skill gives it a workflow: gather the data shape, write the rule incrementally, validate it with a real script, then answer. That validate-before-you-answer loop is the whole difference between "looks right" and "runs right."

Try it

The repo is MIT licensed and free: github.com/valeryia-piatrova/jsonlogic-skill. If it saves you a debugging session, leave a star. And if you hit a JsonLogic edge case it handles badly, open an issue: real-world rules are how it gets better.

The Trust Boundary Is Now Whoever Wrote the Last Mod You Installed

Pawel — Wed, 07 Oct 2026 14:03:49 +0000

Every extension system for AI coding agents has quietly moved the trust boundary. Nobody announced it. It just happened, one layer at a time, and Claude Code mods are the layer where it finally becomes impossible to ignore.

Let me trace the line.

Skills were prompts

A skill is a markdown file of instructions the agent reads. The trust question was always about the text: is this guidance good, is it poisoned, does it tell the model to do something I would not want? The blast radius was bounded by what the model could be talked into. A malicious skill could social-engineer the agent, but it could not do anything the agent would not do on its own. The boundary was between you and the words.

MCP servers were services

Then came MCP: external processes that hand the agent new tools. Now the trust question included code, but code running over there, in its own process, behind a tool interface. An MCP server could exfiltrate data through tool results or lie about what a tool does, and researchers found plenty of both. But there was still a membrane: the agent called the tool, the tool returned, the agent decided. The boundary was between the agent and the service.

Mods are inside the process

A mod is a module loaded into Claude Code's own runtime. It does not wait to be called. It sees every event as it happens: your prompts, every tool call, every turn, every pixel of the interface as it is drawn. And it can do three things no previous layer could:

See first, answer last. Hooks form a chain, and the first mod to load sees each event first and the result last. That includes the events your audit logger was counting on. A mod loaded above your logger can edit what the logger records.
Rewrite the event mid-flight. Not suggest, not return a suspicious result for the agent to interpret. Change the tool call itself before the rest of the chain sees it.
Answer instead of the engine. Skip the chain entirely and serve the event itself. Refuse the call. Approve the call your hooks blocked. Submit a prompt as if you typed it.

The docs say it plainly: "A mod is code that runs with your permissions." It can read and write your files, start processes, make network requests, and read your secrets, including an API key you keep in environment variables or settings files.

So here is the new boundary, stated without euphemism: the trust boundary is now whoever wrote the last mod you installed. Not the model provider. Not the tool interface. A person, whose code runs inside your agent's process, with your privileges, seeing your prompts before you finish reading them.

Why this feels different from "just install trusted software"

The usual response is: this is just software supply chain, we have always trusted our dependencies. And there is truth in it. You trust your editor's extensions, your npm packages, your shell plugins.

But there is a difference in position. Your npm packages run when your code runs them. Your editor extensions run in a host that sandboxes them from each other. A mod runs inside the agent loop itself, at the exact point where your intent becomes action. It is not a dependency of your program. It is a participant in your thinking.

Consider the permission prompt, the one UI element Anthropic hardened. A mod can restyle almost the entire interface but cannot touch the permission dialog or change what it shows you. That single exception tells you the threat model: the mod is untrusted code with your privileges, and the permission prompt is the last honest surface in the room. They protected the one moment where your eyes are the security control, because everything else is already inside the wire.

What we do not have yet

Here is the uncomfortable part: the ecosystem is two days old and the answers do not exist yet.

No capability model. A context-bar mod and a security guard request the same $ API. There is no "this mod only draws" permission to grant. claude plugin validate lists what a mod asks Claude Code to do, which is transparency, not least privilege.
No signatures, no provenance chain. Marketplaces, awesome lists, a community scoreboard grading reach levels, all useful, all informal. (Disclosure: I run one of these directories, aifamily.website, indexing 1,600+ mods with a transparent access profile per mod, because discovery is where trust starts.) Nothing cryptographically binds a mod to its author at install time.
No conflict story. Two mods hooking the same event: load order decides. Load order is configuration, and configuration is the thing attackers love most.

Anthropic shipped the escape hatches: disableAllHooks, allowManagedModsOnly for organizations, --safe-mode for a session. Those are off switches, not a trust model. The trust model is still "install mods only from authors and marketplaces you trust", which is the same sentence every platform says right before its first big incident.

The question I keep coming back to

We built the most privileged extension point in the history of dev tools, code running inside the agent, seeing events before the user, answering instead of the engine, and we called it a "mod", a word borrowed from game skins.

Maybe that is fine. Maybe the right answer is capability-scoped permissions and signed mods within a year, and this essay ages like every other "the sky is falling" post. Or maybe the first serious incident comes from a 40-line UI mod that nobody audited because it was small, and small felt safe.

I genuinely do not know which. What I know is that the boundary moved while we were looking at the demo gifs, and it is worth saying out loud where it sits now.

So: what would it take for you to install a mod from a stranger? A signature? A scoreboard? Or is "trust the author" actually enough, and I am overthinking this?

I Replaced All My Hooks With Mods. Here's What Changed.

Pawel — Tue, 06 Oct 2026 13:55:45 +0000

I had five settings hooks. A guard that blocked rm -rf. A logger that recorded every file edit. A notifier that pinged me when a long turn finished. An auto-approver for safe reads. And a context counter I duct-taped onto the status line.

Last weekend I migrated all five to Claude Code mods. The honest ledger: three got shorter, one turned out to be impossible as a hook in the first place, and one opened a hole I had not thought about.

Here is the before and after, with code.

A quick refresher: what hooks actually are

A settings hook is a shell command that Claude Code runs on a lifecycle event, passing JSON over stdin and stdout. Your script reads the event, and decides: let it through, block it, or tweak it. It is simple, it is battle-tested, and it runs in a subprocess that starts, does its job, and dies.

A mod is different. It loads once, stays in the session, keeps state, and its hooks are middleware: observe, rewrite, or answer each event in-process. It can also draw UI and call back into Claude Code.

The docs put it well: if a settings hook, a skill, or an MCP server already does what you need, compare before you write a mod. I did the comparing. Here is what I found.

Migration 1: the guard (shorter)

Before. A PreToolUse hook in settings.json pointing at a bash script:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "~/.claude/hooks/guard.sh" }]
      }
    ]
  }
}

#!/bin/bash
# guard.sh: read the event JSON from stdin, block risky commands
input=$(cat)
cmd=$(echo "$input" | jq -r '.tool_input.command // empty')
case "$cmd" in
  *"rm -rf"*|*"git push --force"*)
    echo "Blocked: too risky to run unattended" >&2
    exit 2 ;;
esac
exit 0

Two files, a jq dependency, a subprocess spawned on every single Bash call, and the "UI" is a line of stderr.

After. One module:

export function register(on) {
  const RISKY = [/rm -rf/, /git push --force/];

  on("tool.call", { tool: "Bash" }, async ($, e, next) => {
    const cmd = e.input.command ?? "";
    if (RISKY.some((re) => re.test(cmd))) {
      return { deny: "Blocked: too risky to run unattended" };
    }
    return next(e);
  });
}

No subprocess per event. No jq. The deny path is a first-class return value, not an exit code convention. And because the mod is in-process, the same guard can later grow a UI, a panel with "what would this change" and Proceed/Cancel buttons, like Anthropic's own blast-radius sample mod. A hook can never do that part.

Verdict: shorter, and upgradeable. This is the migration that sells itself.

Migration 2: the notifier (impossible as a hook)

Before. My "tell me when a long turn finishes" hook. The problem: a settings hook can allow, block, or log an event. It cannot draw anything. The closest I got was appending to a log file and having a separate terminal tailing it. It worked, and it was embarrassing.

After. A mod hooks turn.complete and draws. The official docs use exactly this as their canonical example: count tool calls and show the count beside the spinner while Claude works, Thinking · tool calls: 3…, updating live. My notifier became a small band above the prompt showing turn duration and token delta, updating after every turn.

This one was not a migration. It was a capability that did not exist in my setup before. Hooks observe the world through a keyhole; mods live in the room.

Verdict: impossible before, trivial now. If your hook wishlist ever included the words "show me", this is your reason to migrate.

Migration 3: the auto-approver (the hole)

Before. A hook that approved safe reads. It exited 0 for cat, ls, git status, and let the permission system handle the rest.

After. A mod that answers tool.call events for the same safe list without calling next.

And here is the part I did not expect. While testing, I learned something from the docs that stopped me cold:

A mod that approves tool calls can approve one that an ask rule would prompt for, or that one of your own PreToolUse hooks blocked.

My old hook setup had a clear hierarchy: hooks were the bouncer, the permission rules were the policy. A mod does not sit inside that hierarchy. It sits above it. A mod can approve the exact call my Migration 1 guard denies. The guard and the approver are now peers in a middleware chain, and chain order decides who wins.

I am not saying "do not migrate your approver". I am saying: when you do, you are moving a security decision from a subprocess the engine invokes into code that runs with your full permissions and can overrule the other guards. Audit the chain order. Write a test that asserts your guard still denies when the approver is loaded. claude plugin test exists for exactly this.

Verdict: migrated, but it changed the trust model. This is the one migration I would do differently: I would have read the permissions docs first.

Migrations 4 and 5: the boring ones (kept as hooks, then moved anyway)

The file-edit logger and the context counter. Both were pure "observe and record" hooks with no UI and no decisions. The docs are honest about this case: if a hook already does what you need, a mod is not automatically better.

I migrated them anyway, for one reason: state. A settings hook is stateless across events; every invocation starts cold. My logger shelled out to append to a JSONL file, and the counter re-read it. The mod versions keep counters in memory (and in $.state, which survives hot reloads) and share them between hooks, one hook counts, another draws. Less I/O, no temp files, no parsing.

Were they shorter? Marginally. Was it worth it? For the shared state alone, yes.

What I would tell you before you start

Migrate the UI-shaped ones first. Anything your hooks do that wishes it could draw, notifiers, dashboards, review views, is where mods win by a mile.
Keep the pure block/allow/log hooks if they work. A mod is not a moral upgrade. It is a different tool.
Test the chain, not just the mod. claude plugin validate checks one plugin. claude plugin test exercises hooks against the real engine. Neither tells you what happens when your guard and your approver load together. Write that test yourself.
Re-read the permissions docs after migrating. Your mental model of "hooks enforce policy" does not survive contact with mods. The mod is code with your permissions, and it can approve what your hooks blocked.

Three shorter, one newly possible, one that taught me something uncomfortable. Not a bad weekend.

Which of your hooks is secretly wishing it could draw UI? That is the one to migrate first.

The Guard I Installed Was Enabled, Running, and Doing Nothing

Pawel — Mon, 05 Oct 2026 14:02:35 +0000

Last week I installed a guard mod. It was supposed to hold risky shell commands, rm -rf, force pushes, the usual suspects, and show me what they would change before letting them run.

It was listed in /plugin. It was enabled. It did absolutely nothing.

I spent an embarrassing amount of time re-reading my hook code. The code was fine. The harness had quietly discarded my mod before a single event ever reached it, and it never told me in any place I was looking.

If your mod is "working" but silent, run this checklist first. In order of likelihood, none of these is your code.

Mistake 1: the project was never trusted

This one got me first. Claude Code only adopts a plugin from a project's .claude/ folder after you accept the trust dialog, the record lives in ~/.claude.json under projects[<path>].hasTrustDialogAccepted. Until then, an untrusted folder's .claude/ is repository content as far as the engine is concerned. It is not read at all.

The nasty variant: claude -p never shows the trust prompt. A headless run in a fresh folder will never load your project mod, and it will not complain about it either.

Two fixes, pick one:

Open claude interactively in the folder and accept the prompt.
Load it explicitly with --plugin-dir .claude/skills/{name}, which loads it as {name}@inline without needing trust.

User-level plugins under ~/.claude/skills/{name}/ always load. If your mod works from the user folder but not from the project folder, trust is your answer.

Mistake 2: I was looking in the wrong place

My mod logged everything through $.ui.log. In an interactive session, that appends a dim line to the transcript. In claude -p or the Agent SDK, there is no transcript and no status row, so those lines go exactly one place: the debug log.

The debug log lives at ~/.claude/debug/<session-id>.txt. Note the extension: .txt, not .log. There is a latest symlink pointing at the newest one, which saves you from guessing session ids.

The transcript also carries a dim line naming the mod and the reason when something fails to load. And claude --debug logs the load sequence itself. I now run every mod debugging session with --debug from the start. It is the difference between guessing and reading.

Also worth knowing: a mod that draws UI can check which surface it is on. Drawing only happens in the terminal and the Desktop app's Code tab. In the VS Code chat panel, claude -p, or a cloud session, your hooks run but your panes and bands simply do not exist. If your mod is a UI mod and you tested it headless, "doing nothing" is the correct behavior.

Mistake 3: my options were under the wrong key

Plugin options are read from user or managed settings under pluginConfigs, keyed by the plugin's full id, and the full id depends on how the plugin loaded:

Auto-loaded from .claude/skills/: the key is "{name}@skills-dir"
Loaded with --plugin-dir: the key is "{name}"

I had mine under the bare name while the mod loaded as {name}@skills-dir. Every option silently fell back to its default. No error, no warning in the session. The debug log does say plugin {name}: no pluginConfigs["{name}@skills-dir"].options in user, --settings or managed settings, which is precise and completely invisible unless you are reading the log (see mistake 2).

One more trap inside this trap: options are read from user and managed settings, never from project settings. Putting them in the project's .claude/settings.json is the same as not setting them.

The fix looks like this in ~/.claude/settings.json:

{
  "pluginConfigs": {
    "my-guard@skills-dir": {
      "options": {
        "blockPatterns": ["rm -rf", "git push --force"]
      }
    }
  }
}

Get the key wrong and you get defaults. Get the file wrong and you get defaults. The mod will not tell you.

Mistake 4: something turned the whole thing off

During early access, mods sat behind a rollout flag, and with the flag off the debug log said installed plugins' hooks modules not loaded: rollout flag is off. In 2.1.287 mods are on by default, so this specific trap is mostly history. But its modern equivalents are alive and well:

"disableAllHooks": true in ~/.claude/settings.json stops your mods (and your settings hooks, and your custom status line) in every session.
An organization's allowManagedModsOnly stops user-installed mods from loading while the rest of the plugin keeps working. Your skills and commands load fine, your mod does not, and nothing in the session explains the difference.
Anthropic can also turn off specific built-in pieces remotely; the plugin-authoring skill that lets Claude write mods is subject to that.

The cruel detail: built-in mods load regardless of these flags. So /plugin can show mods active, your session can look completely normal, and your mod is still not among them.

The checklist, in order

Before you touch your module code:

Run /plugin in an interactive session. Look for the dim line: N mod active · name. If yours is not named there, it never loaded. Stop debugging code.
Trust the project, or load with --plugin-dir.
Read the debug log at ~/.claude/debug/latest (remember: .txt). Search for your plugin's name and for pluginConfigs.
Check your options key against the full plugin id, in user settings, not project settings.
Check disableAllHooks and any managed settings your org deploys.

Four of my last five "broken" mods were fixed by this list without changing a line of module code. The fifth was a typo in hooks.json, which claude plugin validate caught in three seconds. Run that too. Always run that.

What is the most silent failure you have hit with Claude Code mods so far? I have a feeling mistake 3 has bitten more people than will admit it.

Claude Code Mods Aren't Sandboxed. Neither Is Your Understanding of "Sandboxed".

Pawel — Sun, 04 Oct 2026 13:49:49 +0000

Two statements about Claude Code mods, both true, both from Anthropic's own docs:

The module runs in a sandbox of its own, with no DOM and no Node.
"Mods aren't sandboxed."

The first two days of the mods launch have been one long argument about which of these is the lie. Neither is. The confusion comes from the word "sandbox" doing two different jobs, and once you separate them, the real trust boundary snaps into focus. It is not where most people think it is.

Sandbox #1: the JavaScript runtime

When you write a mod, your module gets a private little world. No document. No window. No Node globals. If your code wants to touch anything outside itself, files, processes, the network, the UI, it goes through one object: $.

export function register(on) {
  on("tool.call", { tool: "Bash" }, async ($, e, next) => {
    const listing = await $.fs.readDir("/tmp");   // through $, not fs
    return next(e);
  });
}

This is sandbox #1. It is a language-level sandbox: it constrains how your code reaches the outside world, not whether it can. Every capability lives behind the $ API, which means the engine can see every request, log it, and (in theory) gate it. Think of it like a phone where every app must use the official APIs. The APIs still include the camera.

Sandbox #2: the one that does not exist

Here is what the documentation says, and I am quoting because paraphrasing would soften it:

"A mod is code that runs with your permissions. It can read and write your files, start processes, and make network requests. Install mods only from authors and marketplaces you trust."

And:

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

Read that second one twice. Claude Code has a sandboxing feature, and it sandboxes Claude's Bash commands. A mod that starts its own process steps cleanly outside of it. The fence was built around the agent, not around the extension.

The capability list gets worse the further you read. A mod can:

Read your secrets: environment variables and settings files, "including an API key you keep in either".
Approve tool calls you blocked: a mod that approves tool calls can green-light one "that an ask rule would prompt for, or that one of your own PreToolUse hooks blocked". Your hook said no. The mod says yes. The mod wins.
Rewrite events before you see them: hooks form a chain, and a mod can observe, rewrite, or fully answer any event. Including the ones your audit logger was counting on.

So when someone says "mods are sandboxed", they are describing the JS runtime. When Anthropic says "mods aren't sandboxed", they are describing your files, your processes, your network, and your API keys. Both true. The second one is the one that matters.

The one hard boundary

There is exactly one thing Anthropic drew a hard line around, and it is telling:

"A mod can restyle much of Claude Code's interface, but not the permission prompt. It can't change what a prompt shows you."

A mod can redraw almost the entire UI, panes, bands above the prompt, toasts, but the permission dialog stays Claude Code's own. Whatever else a mod draws, the moment that asks "are you sure?" cannot be faked, restyled, or have its contents swapped.

Think about why that specific line exists. If a mod could restyle the permission prompt, it could show you "run tests?" while actually approving rm -rf. Anthropic hardened the one UI element where your eyes are the security control, and left everything else open. That tells you exactly what threat model they designed for: the mod is untrusted code with your privileges, and the permission prompt is the last honest surface in the room.

The mental model that actually works

Stop picturing a browser iframe. The right mental model is much older and much simpler:

Installing a mod is giving someone your shell.

Not a restricted shell. Not a shell with an auditor watching. Your shell, with your env vars, your files, your network, and the ability to overrule the guardrails you built for the agent. The JS-runtime sandbox is real engineering, it keeps modules from stepping on each other and gives the engine a clean interception point, but it was never a security boundary between the mod and your machine.

Once you have that model, the hygiene checklist writes itself:

claude plugin validate before you install, not after. It lists the events a mod handles and what it asks Claude Code to do, file reads, network requests, without running any code. Read it like you would read the permissions screen on a phone app. If a context-bar mod wants network access, ask why.
Know your off switches. Disable one plugin from the Installed tab in /plugin. Start a session with --safe-mode to drop all customizations. Set "disableAllHooks": true in ~/.claude/settings.json for the wide kill switch. Organizations get allowManagedModsOnly, which stops user-installed mods from loading while skills, commands, and MCP servers keep working.
Audit the small ones hardest. A 40-line UI mod feels safe because it is small. But 40 lines is enough to read ~/.claude/settings.json, exfiltrate an API key, and approve the tool call that covers its tracks. Size is not a security property.

None of this means you should not install mods. It means you should install them the way you would hand your laptop to a colleague: only to people you trust, and knowing exactly what they can reach while they have it.

So here is my question: what does your claude plugin validate say about the mods you have already installed? And did you read it before, or just now?

I Built My First Claude Code Mod Without Writing Code: Claude Wrote It, Validated It, and Hot-Reloaded It

Pawel — Sat, 03 Oct 2026 09:19:53 +0000

I wanted one thing: to see my context window without typing /context.

Not a dashboard. Not a plugin I install and configure for twenty minutes. Just a small bar above the prompt that tells me how full the window is, the way the /context command does, but always on screen. One sentence of a prompt later, it was there.

This is the story of the first Claude Code mod I built without writing a single line of code. Claude wrote it, validated it, tested it, and hot-reloaded it into my session. I just watched.

What a mod actually is

Claude Code mods (shipped in v2.1.287, on by default) are small JavaScript or TypeScript modules that live inside a plugin. They see every event in your session as it happens: tool calls, the prompt you submit, turns starting and ending, and every piece of the interface as it is drawn.

That last part is the new bit. Mods can rewrite what Claude Code does and draw their own UI: a pane, a band above the prompt, a status line entry, a toast. Everything the engine draws is a component you can hook into.

And here is the part that still feels strange: you do not need to learn the API to try one. You describe the mod you want, and Claude Code builds it.

Step 1: ask for it

Open any project, run claude, and paste a prompt like this:

Create a mod that draws my context window as a stacked bar above the prompt, one colour per category like /context, toggled with /context-bar.

Claude Code loads its own plugin-authoring skill, reads the engine's type declarations, and writes three or four files into a session folder under ~/.claude/dev-mods/. Then it asks one question: allow hot reloading for this session?

Say yes. When the turn ends, the bar appears above your prompt.

That is the moment that sold me. I did not open an editor. I did not read the docs. I described a UI in plain English, and it showed up.

Step 2: make Claude validate its own homework

Before I even looked at the code, I asked for two things while the session was still warm:

Run claude plugin validate on the folder. The validator reads the module the way the engine will and names anything the engine would refuse. Think of it as a compiler for mods: non-negotiable.
Write a tests/ file and run claude plugin test. That exercises the hooks against the real engine. No TypeScript toolchain needed on your machine.

This is the difference between "Claude wrote something plausible" and "the engine will actually load this". An LLM will happily produce a mod that looks right and fails at load time. Validate and test are what separate the magic from the garbage.

Step 3: peek under the hood (optional, but worth it)

Curiosity won, so I read the code. A mod is one module exporting register:

export function register(on) {
  on("ui.render", { component: "AbovePrompt" }, ($, e, next) => {
    const { Box, Text } = $.ui.resolve(e);
    return Box({
      paddingX: 1,
      children: [Text({ children: "hello from my mod" })],
    });
  });
}

The shape is middleware. Your hook runs, then next(e) hands the event to the next plugin in the chain, then to Claude Code itself. Every hook does one of three moves:

Observe: call next(e), then look at the result. Record every file edit, take a reading after each turn.
Rewrite: call next with a modified event. Change what the rest of the chain sees.
Answer: skip next entirely and serve the event yourself. Refuse a tool call, handle a slash command.

One detail I stole from Addy Osmani's guide: do not keep history in a module-level let. Hot reload is a fresh load, register runs again, and module variables start over. Keep readings in $.state, declared in a small types contract, and they survive reloads. If you skip the contract, claude plugin validate stops you with an error that names the fix. The tooling here is genuinely good.

Step 4: make it permanent

The session folder dies with the session. Copy the mod somewhere stable:

mkdir -p ~/.claude/mods
cp -R ~/.claude/dev-mods/<session-id>/context-bar ~/.claude/mods/context-bar

Keep the manifest in .claude-plugin/plugin.json, the hooks/ folder with its module, and the types/ contract if the mod keeps state. Copy tests/ too, so you can rerun the tests after an update.

Then tell Claude Code where it lives. The one place that reaches every session, including the ones the desktop app starts, is the env block of your user settings file. Open ~/.claude/settings.json and add:

{
  "env": {
    "CLAUDE_CODE_PLUGIN_DIRS": "/Users/you/.claude/mods/context-bar"
  }
}

Use the full path, not ~. Several mods are separated with a colon. For a one-off terminal session, claude --plugin-dir ~/.claude/mods/context-bar does the same without touching settings.

Open a new session in any project. The bar is above the prompt before you type anything, and /context-bar hides it.

Two things that bit me

Early access means churn. The API can change between releases, so a mod written today may need a touch-up after an update. Rerun claude plugin validate after every upgrade. It is cheap insurance.

Check which claude you are running. The desktop app bundles its own engine, and the one on your PATH may be older. Mine was, and its validator did not recognize the hooks module at all. Validate with the app's bundled binary, or update the CLI first. This cost me twenty confused minutes staring at an error that was not mine.

Why this feels different

I have used hooks, slash commands, and skills. A settings hook runs a shell command per event and passes JSON over stdin and stdout. A mod loads once, keeps state, draws UI that updates as events happen, and can call back into Claude Code: open a pane, run a process, register a slash command, register a tool the model can call. Some of Claude Code's own features are built as mods, including AGENTS.md support and the /diff pane. Their source is public, so you can read how the team builds them.

But the real shift is the loop. The skill for writing mods ships inside Claude Code, so the agent modifies its own runtime, in the same session, and hot reload shows you the result on the next turn. I kept asking for tweaks ("add a legend line with per-category token counts", "show a toast when context crosses 85%") and watched the bar change. It felt less like configuring a tool and more like pair programming with the tool itself.

If you could describe a mod in one sentence, what would it do?