DEV Community: Local Plugins

Your Claude Code hook doesn't fire on Windows, and nothing tells you why

Local Plugins — Thu, 16 Jul 2026 13:19:30 +0000

One of my plugins has a SessionStart hook. It loads the active brand kit into context, so a plain request already knows your colors and fonts without you re-explaining them every session.

On macOS it works. On Windows it does nothing. No error, no warning, no line in the transcript. It just silently isn't there.

Here's the whole path, including the wrong turn, because the wrong turn is the interesting part.

The symptom

The hook is declared like this:

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup|resume",
        "hooks": [
          {
            "type": "command",
            "command": "bash \"${CLAUDE_PLUGIN_ROOT}/hooks/session-start.sh\"",
            "async": false
          }
        ]
      }
    ]
  }
}

Nothing wrong with it. Plugin enabled, script present, script executable. On a Mac it fires every session.

The wrong theory

First I checked whether the hook was being invoked at all. Claude Code stores a record when a hook fires, so you can audit it. In the failing session:

SessionStart:startup records: 0
PreToolUse:Bash records: 12

So SessionStart never ran, but a different hook ran twelve times. And a sibling session on the same app version did have a SessionStart record carrying the exact line my plugin emits. The hook works. It just wasn't invoked here.

That led to a reasonable theory: the matcher. startup|resume doesn't match every session source (there are four: startup, resume, clear, compact), so maybe the desktop app creates sessions through a path that never produces a matching event.

So I dropped the matcher, which makes it fire on all four. Shipped it. Updated the Windows machine.

Still nothing.

That's the useful part. The theory was plausible, it explained the evidence, and it was wrong. Zero records is equally consistent with "the event never arrived" and "the hook ran and failed." I picked one without testing the other.

The actual cause

The command starts with bash. So the question was never whether the event arrived. It's whether bash resolves.

> where.exe bash
INFO: Could not find files for the given pattern(s).

It doesn't. Meanwhile:

Check	Result
Default shell (`COMSPEC`)	`C:\WINDOWS\system32\cmd.exe`
Git Bash installed?	Yes, at `C:\Program Files\Git\bin\bash.exe`
Is `Git\bin` on PATH?	No. Only `Git\cmd` is, which has `git.exe` but not `bash.exe`

So Claude Code hands bash "...session-start.sh" to cmd.exe, cmd can't resolve bash, the command errors, the hook exits non-zero, and it gets dropped. Silently.

The two things that look like contradictions

Both of these made me believe bash was fine. Both are actually confirmations.

The Bash tool works. I can run bash commands in the session all day. But the tool finds its own Git Bash through a different resolution path than the hook runner, which uses the OS shell and the system PATH. "bash works in my session" tells you nothing about whether the hook can find it.

A different hook does fire. My PreToolUse hook runs an echo. It works because echo is a cmd built-in and needs no bash at all. Only the bash-invoking hooks fail, which is all of them, in every plugin I have.

This is the default install, not an edge case

Git for Windows puts Git\cmd on PATH, not Git\bin. That's the standard install option. Adding Git\bin is the option the installer explicitly warns you about, because it puts GNU find and sort ahead of the Windows native ones and breaks other tooling.

So the default Windows setup is: bash is installed, and bash is not on PATH. Every plugin whose hooks shell out to bash silently does nothing for a large share of Windows users, with no error anywhere.

The fixes, including the ones that don't work

Add Git\bin to PATH. Works. It's also the thing Git warns about, and it's per machine, so it fixes you and nobody else.

Hardcode an absolute path. No. There isn't a single correct one. macOS ships bash at /bin/bash, not /usr/bin/bash. Most Linux has /usr/bin/bash. Windows has a path that varies by installer. And cmd can't resolve a POSIX path anyway, so /usr/bin/bash is meaningless there.

Use sh instead. Worse. There's no sh on Windows either, both come from the same Git Bash layer. And my scripts use set -euo pipefail, and pipefail isn't POSIX, so running them under dash (which is /bin/sh on Debian and Ubuntu) breaks them immediately. That trades a Windows problem for a Linux problem.

Put the condition in the command. Tempting, but the hook command runs in cmd.exe on Windows and sh on Unix, and their conditional syntax has nothing in common. There's no single string that checks paths in both.

Use node. This is the one that works. Node's Windows installer puts node on PATH by default, which is exactly what Git's installer doesn't do for bash. So either port the hook to Node, or keep the bash scripts and add a small Node launcher that walks candidate locations and runs whichever exists:

// candidates, first hit wins
const candidates = [
  'bash',                                   // on PATH (mac/linux, or Git\bin on PATH)
  '/bin/bash',                              // macOS, most Linux
  '/usr/bin/bash',                          // most Linux
  'C:\\Program Files\\Git\\bin\\bash.exe',  // default Git for Windows
  'C:\\Program Files\\Git\\usr\\bin\\bash.exe',
];

Not a guarantee. If node isn't on the hook runner's PATH either, you're back where you started. But it drops the dependency that's broken by default.

The actual bug

The PATH thing is a packaging quirk. The real problem is that the hook failed and told nobody.

The command errored. The plugin silently lost a feature. Nothing in the transcript, no warning, no log line, no exit code surfaced to the user or to me. From the outside it's indistinguishable from a hook that was never registered, which is exactly why I burned a day on the wrong theory.

If you're building a harness with hooks: surface the failures. A hook that dies quietly is worse than one that doesn't exist, because at least a missing hook is visible.

And if you're writing plugins with hooks: run where.exe bash on a Windows box before you assume anything.

Local-first Claude Code plugins: no keys, no network, open source

Local Plugins — Tue, 14 Jul 2026 13:30:56 +0000

I keep living inside Claude Code, and I kept wanting small, useful tools in
there that didn't phone home. Not another SaaS with a login and an API key,
just something that runs on my machine, does one job well, and that I can read
before I trust it.

So I packaged the workflows I actually use into a few open-source plugins and
put them in one marketplace. This is the first write-up.

What "local-first" means here

The rule I set for myself: a plugin should run entirely on your machine by
default. No account, no API key, no network call, nothing uploaded or
auto-posted. And if a plugin genuinely needs the network, it should be:

obvious,
isolated to a single module,
off by default, and
using your own key.

That way you can grep the code and see exactly what touches the outside
world. For a tool that generates your logo or your résumé, that inspectability
matters.

Two honest exceptions, called out up front: docpin fetches library
documentation from the web (always cited), and brand-forge has one opt-in
module that can call an image API for AI photography. Everything else is local.

What's in the suite

brand-forge — save a brand profile once (colors, fonts, voice), then generate on-brand logos, social templates, and doc/deck templates as SVG. The vector output is drawn by local code, so it's deterministic: the same profile always produces the same asset.
cv-forge — keep one résumé in the JSON Resume schema, generate a clean, ATS-friendly PDF from a local HTML template and your browser's print. No Node, no keys, no network.
content-multiplier — turn one idea into on-brand, multi-channel, multi-language content from a single command.
docpin — ground code against your installed version of a library by pulling version-matched, cited docs.
plus a couple more in the same spirit.

Installing

Everything installs through Claude Code's plugin system. In a session:

/plugin marketplace add localplugins/plugins
/plugin install brand-forge@localplugins

Then a natural request like /brand-make instagram post "We just shipped" uses
your saved brand and returns an editable SVG in output/.

A few design choices worth calling out

Deterministic generation over an LLM round-trip. brand-forge's logos and
templates are generated by plain code from your profile, not by asking a model
to draw them. That makes them reproducible, diffable, and editable, and they
don't drift between runs.

The network boundary is a single file. In brand-forge, the only module
that can reach the internet is the opt-in image generator. It's off unless you
set an env var and provide your own key, and the text of your asset is
composited locally as an SVG overlay so it never goes into the image prompt.
One file to audit, not a whole codebase.

Plugin anatomy. Each plugin is a normal Claude Code plugin: slash commands,
skills that trigger from natural requests, sometimes a SessionStart hook that
loads context, and in brand-forge's case two subagents (an art-director that
plans a multi-asset set, and a visual-guardian that checks output against the
brand for palette and contrast). If you're building your own plugins, they're
small enough to read as examples.

What this isn't

It's not a design tool that will out-polish a human designer, and it isn't
trying to be. It's a way to get consistent, on-brand, good-enough assets and
documents without leaving your terminal or signing up for anything. If you need
pixel-perfect art direction, use it for the scaffolding and finish by hand.

Try it

It's all MIT and open source, built with Claude Code itself:
https://github.com/localplugins/plugins

I'd genuinely like feedback on two things: what feels useful vs. gimmicky, and
where you think the line should be for what a local-first plugin is allowed to
do. Issues and comments welcome.