DEV Community: Waclaw Kusnierczyk

Claude Code Plugin Cache

Waclaw Kusnierczyk — Wed, 25 Feb 2026 11:52:35 +0000

Claude Code Plugin Cache Gotcha: Why Your Edits Aren't Taking Effect

If you're developing a Claude Code plugin and your changes aren't showing up after restarting the session, you're probably hitting the plugin cache.

The symptom

You edit a command, agent, or skill file in your plugin directory. You restart Claude Code. The old version still runs. You restart again. Same thing. You stare at the file, confirm it's correct on disk, question your sanity.

The cause

Claude Code caches plugin files under ~/.claude/plugins/cache/, keyed by plugin name and version from your plugin.json:

~/.claude/plugins/cache/local-plugins/your-plugin/0.1.0/commands/your-command.md

When you start a session, Claude Code checks the cache first. If it finds a match for your plugin name and version, it serves the cached copy — without checking whether the source files have changed.

The fix

Option A: Bump the version in .claude-plugin/plugin.json after making changes:

{
  "name": "my-plugin",
  "version": "0.1.0"
}

Change it to 0.1.1, 0.2.0, whatever — just make it different.

Option B: Delete the cache manually:

rm -rf ~/.claude/plugins/cache/local-plugins/your-plugin

Either way, restart the session afterward.

During active development

If you're iterating on a plugin, you'll hit this constantly. A quick workflow:

# after editing plugin files
rm -rf ~/.claude/plugins/cache/local-plugins/my-plugin
# then restart your Claude Code session

Or adopt a habit of bumping the patch version with every edit cycle.

Is this a bug?

It looks like one. A local plugin's cache should be invalidated when the source files change — checking file modification timestamps would be sufficient. Caching by version alone makes sense for published/marketplace plugins, but for local development it creates a confusing experience where your edits silently don't apply.

This has been reported multiple times:

#14061
#15621
#17361
#28492 (filed by us after encountering this firsthand)

As of February 2025, the issue remains unresolved.

aigent: toolchain for AI agent skills

Waclaw Kusnierczyk — Mon, 23 Feb 2026 10:06:34 +0000

AI agents are getting good at following instructions. The bottleneck has shifted: it's no longer about what the model can do, but about how well you package what it should do. That packaging layer is agent skills — structured documents that tell an agent what a capability does, when to activate it, and how to use it.

The Agent Skills open standard, originally defined by Anthropic for Claude Code, codifies this into a simple format: a SKILL.md file with YAML frontmatter (name, description, compatibility, allowed tools) and a Markdown body with detailed instructions. The metadata is indexed at session start for fast discovery; the body is loaded on demand, following a progressive-disclosure pattern that keeps the context window lean.

The format is simple. Getting it right at scale is not.

The problem

When you have a handful of skills, you can eyeball them. When you have dozens — across teams, repositories, and CI pipelines — you need tooling. Names drift from conventions. Descriptions become vague. Activation patterns go untested. Formatting diverges. Nobody catches the skill that fails to trigger because its description doesn't match the query patterns users actually type.

The specification defines what a valid skill looks like. The Python reference implementation provides basic validation, but it's a library — not a toolchain you can drop into CI, pre-commit hooks, or a plugin build pipeline.

What `aigent` does

aigent is a Rust library, native CLI, and Claude Code plugin that implements the Agent Skills specification as a proper toolchain — the same way a formatter, linter, and test runner enforce conventions in any mature language ecosystem.

It covers the full skill lifecycle:

Create — Generate skills from natural language with aigent new. Deterministic by default, with optional LLM enhancement (Anthropic, OpenAI, Google, Ollama backends). Produces a complete SKILL.md directory ready for validation and refinement.

Validate — Check skills against the specification with typed diagnostics, error codes, and JSON output. Run aigent validate in CI to catch problems before they reach production. Three severity levels (error, warning, info) and a --format json flag for machine consumption.

Format — Canonical YAML key ordering, consistent whitespace, idempotent output. aigent format --check returns non-zero when files need formatting — drop it into a pre-commit hook.

Score — A weighted 0-100 quality score against a best-practices checklist. Structural checks (60 points) verify specification conformance; quality checks (40 points) evaluate description clarity, trigger phrases, naming conventions, and detail. Use it as a CI gate: aigent score my-skill/ || exit 1.

Test — Fixture-based testing from tests.yml. Define input queries, expected match/no-match results, and minimum score thresholds. aigent test runs the suite and reports pass/fail. aigent probe does single-query dry-runs: "if a user said this, would the agent pick up that skill?"

Build — Assemble skills into Claude Code plugins with aigent build. Validate entire plugin directories — manifest, hooks, agents, commands, skills, and cross-component consistency — with aigent validate-plugin.

Specification compliance

aigent implements every validation rule from the Anthropic specification, plus additional checks that go beyond both the specification and the Python reference implementation:

All name constraints (length, casing, reserved words, XML tags, Unicode NFKC normalization)
All description constraints (length, non-empty, no XML/HTML)
Frontmatter structure, delimiter matching, compatibility field limits
Body length warnings
Path canonicalization and symlink safety
Post-build validation

Where the specification and the reference implementation diverge, aigent reconciles them and documents the decision.

See the compliance section in the README for a detailed three-way comparison.

Beyond individual skills

Skills don't exist in isolation. As your collection grows, new problems emerge: name collisions, overlapping descriptions that confuse activation, token budgets that exceed context limits. aigent handles this with cross-skill conflict detection, token budget estimation, and batch validation across directories.

And skills are just one part of a Claude Code plugin. aigent's validate-plugin command checks the full plugin ecosystem: the plugin.json manifest, hooks.json configuration, agent files, command files, skill subdirectories, and cross-component consistency. Typed diagnostics with error codes (P001-P010 for manifests, H001-H007 for hooks, X001-X008 for cross-component) give you the same deterministic enforcement across the entire plugin structure.

Where it fits

The agentic AI ecosystem is moving fast. Tools like Anthropic's plugin-dev teach you the patterns; aigent enforces them. Think of it as the difference between a language tutorial and a linter — you need both, but they serve different purposes.

Other tools in the space, like AI Agent Skills, focus on distribution — installing pre-built skills across multiple agents. aigent focuses on authoring quality: making sure what you publish is correct, consistent, and well-tested before it reaches any distribution channel.

Get started

# Install
cargo install aigent                        # official distribution at crates.io
brew install wkusnierczyk/aigent/aigent     # homebrew tap

# Create, validate, score
aigent new "process PDF files and extract text" --no-llm
aigent check extracting-text-pdf-files/
aigent score extracting-text-pdf-files/

About

$ aigent --about
aigent: Rust AI Agent Skills Tool
├─ version:    0.6.3
├─ author:     Wacław Kuśnierczyk
├─ developer:  mailto:waclaw.kusnierczyk@gmail.com
├─ source:     https://github.com/wkusnierczyk/aigent
└─ licence:    Apache-2.0 https://www.apache.org/licenses/LICENSE-2.0

Apache 2.0 — see apache.org/licenses/LICENSE-2.0.

Reference	Link
Sources	https://github.com/wkusnierczyk/aigent
Releases	https://github.com/wkusnierczyk/aigent/releases
Crates	https://crates.io/crates/aigent
Docs	https://docs.rs/aigent

Auto Memory, Auto Forget

Waclaw Kusnierczyk — Sun, 08 Feb 2026 11:55:42 +0000

Claude Code's Auto Memory Isn't Thread-Safe

Date: 2026-02-08

Claude Code has a handy auto memory feature: a project-scoped MEMORY.md file that persists across conversations. Agents read it at startup and write to it when they learn something worth remembering — patterns, gotchas, user preferences. It works great for single-agent sessions.

Then Anthropic ships agent teams.

The problem

Agent teams let multiple Claude Code instances work on the same project simultaneously. A lead agent coordinates, teammates work independently in their own context windows, and they share a task list. They also share the same project-scoped memory directory.

The memory file (~/.claude/projects/<project>/memory/MEMORY.md) is a plain file on disk. The Edit tool reads the file, does a string match-and-replace, and writes the whole file back. No locking, no compare-and-swap, no merge strategy.

If two agents discover something worth recording at roughly the same time:

Agent A reads MEMORY.md (version 1)
Agent B reads MEMORY.md (version 1)
Agent A writes its update (version 2a)
Agent B writes its update (version 2b, based on version 1)
Agent A's update is silently lost

This is a classic lost-update race condition. It also affects background agents launched via Task with run_in_background, which have been around longer than agent teams.

Why it matters

Memory writes are infrequent in single-agent sessions, so the window for collision is small. But agent teams change the calculus:

Multiple agents are running concurrently by design
They're working on the same project, so they share the same memory file
Complex tasks (the kind you'd use teams for) are exactly the kind that generate new insights worth recording

You won't know something was lost until a future session acts on stale or missing knowledge.

Possible fixes

We filed anthropics/claude-code#24130 with four suggested approaches:

File locking — flock or equivalent around reads and writes. Simple, proven, platform-dependent.
Append-only log — agents only append; a periodic compaction pass deduplicates. This eliminates the lost-update race, but the file grows, needs garbage collection, and contradictory entries can coexist until compaction resolves them.
Per-agent memory files — each agent writes to memory/<agent-id>.md, and a merged view is assembled for the system prompt. Clean separation, but needs a merge strategy for contradictory entries.
Compare-and-swap — re-read the file before writing, retry if it changed since the last read. Works well for low-contention scenarios (which memory writes are).

Workaround

For now, if you're using agent teams or background agents, be aware that concurrent memory writes can lose data. You can mitigate by:

Having only the lead agent write to memory
Using separate memory files per topic (reduces collision surface)
Reviewing MEMORY.md after parallel sessions to catch any gaps

Bun's Coverage Threshold

Waclaw Kusnierczyk — Sun, 08 Feb 2026 11:40:26 +0000

Bun's Coverage Threshold: Three Undocumented Behaviors That Will Waste Your Afternoon

Date: 2026-02-08

On a private project, we spent a full debugging session chasing down why bun test --coverage exits with code 1 despite all 757 tests passing and overall line coverage sitting at 80% — comfortably above our 80% threshold. There was no error message and no indication of what failed. Just a silent exit code 1 annoyingly breaking the CI.

Here's what we found.

The Setup

Our bunfig.toml looked perfectly reasonable:

[test]
coverageThreshold = { lines = 0.8 }
coverageSkipTestFiles = true
coveragePathIgnorePatterns = [
  "src/app/**",
  "src/components/**",
]

Coverage output showed everything green:

All files  |   63.40 |   80.03 |

80.03% lines, threshold is 80%. Should pass. Doesn't.

Gotcha 1: The threshold is per-file, not overall

The docs say:

To require 90% line-level and function-level coverage: coverageThreshold = 0.9

This implies it checks the "All files" aggregate. It doesn't. Bun checks every single file individually against the threshold. If you have a utility module at 19% line coverage and your threshold is 80%, the build fails — even if your overall coverage is well above 80%.

In our project, files like rag-lookup.ts (2.7% lines) and ollama-client.ts (19.7% lines) were dragging things down per-file while the overall sat at 80%.

This is oven-sh/bun#17028, filed Feb 2025, labeled bug, still open.

Gotcha 2: Specifying `lines` implicitly enforces a function threshold

Even after we dropped the threshold to { lines = 0.5 } (way below our actual coverage), it still failed. We swept through threshold values:

functions=0.0   EXIT=0   <-- only this passes
functions=0.05  EXIT=1
functions=0.1   EXIT=1
functions=0.3   EXIT=1
functions=0.5   EXIT=1

Specifying any lines value in the threshold object causes bun to also enforce a function coverage check with some implicit default. Many of our files have 0% function coverage (bun counts top-level code as "line" coverage but not "function" coverage), so any non-zero function threshold fails them.

The fix: coverageThreshold = { lines = 0.8, functions = 0 }. But since gotcha #1 makes this per-file anyway, it still doesn't do what we want.

This behavior is completely undocumented. The docs show { lines = 0.9, functions = 0.9 } as an example but never mention what happens to unspecified metrics.

Gotcha 3: No error output whatsoever

When the threshold check fails, bun prints the normal coverage table and then exits with code 1. No message saying "file X has Y% coverage, below threshold Z%". No indication that the threshold is what failed vs. a test failure. Just a silent non-zero exit.

Combined with gotchas 1 and 2, this means you see:

All tests pass
Overall coverage above threshold
Exit code 1
No explanation

Our Workaround

We removed coverageThreshold from bunfig.toml entirely and enforce the threshold in a custom script that parses the "All files" line:

// scripts/update-coverage-report.ts
const REQUIRED_LINE_PCT = 80;
if (allLines < REQUIRED_LINE_PCT) {
  console.error(
    `\n✗ Overall line coverage ${allLines.toFixed(1)}% is below the ${REQUIRED_LINE_PCT}% threshold`,
  );
  process.exit(1);
}

The script runs bun test --coverage, parses the text output, checks the overall aggregate, and prints a clear error message if it fails. CI calls this script instead of relying on bun's built-in threshold.

# bunfig.toml
[test]
# NOTE: We do NOT use coverageThreshold here because bun enforces it
# per-file (not overall), and many utility files have low coverage.
# Overall threshold is enforced in scripts/update-coverage-report.ts instead.

Bonus: `[test].exclude` doesn't exist either

While debugging this, we also discovered that [test].exclude in bunfig.toml is silently ignored — it's not a real option. Bun's test runner has no built-in way to exclude test files from discovery. The workaround is describe.skipIf() at runtime. Tracked in oven-sh/bun#21395.

Upstream Issues

oven-sh/bun#17028 — coverageThreshold is per-file, not overall (labeled bug)
oven-sh/bun#5099 — Feature request for per-folder threshold control
oven-sh/bun#21395 — Feature request for test file exclusion

Takeaways

If bun test --coverage exits 1 with all tests passing, the culprit is almost certainly a per-file coverage check on a low-coverage file.
Always specify functions = 0 if you only care about line coverage — otherwise bun applies a phantom function threshold.
Parse the coverage output yourself if you need overall (not per-file) threshold enforcement.
Bun is still young. Its test runner has rough edges. When something doesn't work, check whether the config option actually exists before assuming your config is wrong.

Two Bugs, One Symptom

Waclaw Kusnierczyk — Sun, 08 Feb 2026 10:38:28 +0000

A debugging war story from implementing SSE client transport in Raku MCP SDK.

The task seemed straightforward: add legacy SSE transport to Raku MCP SDK. The server side went smoothly — Cro makes it easy to push text/event-stream responses. The client side destroyed an afternoon.

The symptom was simple. is-connected stays False. Forever. No error, no exception, no timeout message. Just... nothing happens.

The hunt

The maddening part about debugging concurrency issues is how many hypotheses you generate per hour.

The SSE client needed to:

open a GET to /sse,
parse the event: endpoint line to learn the POST URL,
report itself as connected.

Step 1 wasn't completing. Or was it? Hard to tell when your debug prints don't appear either.

Here's what we tried, in roughly this order:

start { await $client.get(...) } — GET takes 5–10 seconds to resolve
$client.get(...).then(-> $p { ... }) — .then callback also delayed
react { whenever $resp.body-byte-stream } — whenever doesn't fire
Supply.tap(...) — tap callback delayed
RAKUDO_MAX_THREADS=128 — no help

Each approach had the same shape: code that works fine in isolation, fails when a Cro HTTP server is running in the same process.

Bug 1: Thread pool starvation

Raku's start blocks, .then callbacks, and react/whenever all share a single ThreadPoolScheduler. Cro uses these same primitives. When a Cro server holds open long-lived SSE streams — which are Supply pipelines sitting in whenever blocks — and a Cro client in the same process needs scheduler slots to resolve its HTTP response pipeline, they compete for the same pool.

Neither side is doing anything wrong. The starvation is emergent.

Debug output told the story:

SSE-CLIENT: before get
connected=False
connected=False
connected=False
SSE-CLIENT: after get, status=200

The GET resolves. Just 10 seconds too late, after the test's polling loop has already given up.

The fix: escape the shared pool entirely. Thread.start creates a real OS thread outside Raku's scheduler. But there's a wrinkle — await doesn't work inside Thread.start. It silently returns Nil:

THREAD: entering sse-loop
SSE-LOOP: before get
THREAD: exited sse-loop

No error. No exception. await just... doesn't block. The solution is .result, which is a synchronous wait on a Promise and works correctly outside the scheduler:

method !connect-sse() {
    my $self := self;
    my $url  := $!url;

    Thread.start: {
        my $client = (require ::('Cro::HTTP::Client')).new;
        my $resp = $client.get($url,
            headers => [Accept => 'text/event-stream']).result;

        react whenever $resp.body-byte-stream -> $chunk {
            $self.handle-sse-chunk($chunk);
        }

        CATCH { default {} }
    }
}

Connection established. Data flowing. Chunks arriving. And is-connected stays False.

Bug 2: The invisible space

Same symptom. Completely different cause.

The SSE parser receives "event: endpoint\ndata: http://...\n\n". It splits each line on :, getting field "event" and value " endpoint". Per the SSE spec, a single leading space after the colon should be stripped. The code did this:

$value = $value.subst(/^ /, '') if $value.defined;

Looks right. Does nothing.

In Raku regexes, whitespace is insignificant by default. The regex /^ / means "anchor to start of string." The space is formatting — syntactic sugar for readability of complex patterns. It is not a literal space character. So subst matches a zero-width position at index 0, replaces nothing, and returns the original string unchanged.

The event type becomes " endpoint" (with a leading space). The check $!sse-event-type eq 'endpoint' fails. The POST endpoint is never set. is-connected stays False.

Debug output, once we added it in the right place:

HANDLE-CHUNK: empty line, event-type=[ endpoint] data=[ http://127.0.0.1:39652/message]

That leading space in [ endpoint] is the entire bug. The fix avoids regex entirely:

$value = $value.substr(1) if $value.defined && $value.starts-with(' ');

Why the combination was brutal

Bug 1 prevented data from arriving in time, so bug 2 was invisible. You can't debug a parser that never receives input.

Once bug 1 was fixed, the symptom was identical: is-connected stays False. No error. No exception. Same silent wrongness, completely unrelated root cause. There was no moment where one bug was fixed and the system partially worked — it went from "broken for reason A" to "broken for reason B" with no observable change in behavior.

Reflections

The regex design choice is defensible. When you write complex patterns — and Raku grammars get genuinely complex — insignificant whitespace is a gift:

/ <ident> \s* '=' \s* <value> /

is easier to read than:

/\w+\s*=\s*\S+/

But / ^ / silently meaning something different from every other regex flavor on earth is a trap. It doesn't warn. It doesn't fail. It matches, successfully, matching nothing. A language where /foo bar/ doesn't match "foo bar" has an onboarding cost, and that cost is paid in debugging sessions like this one.

The thread pool issue is subtler and arguably more interesting. It's not a bug in Raku or Cro. It's an emergent property of running a server and client in the same process when both rely on cooperative scheduling. The kind of thing that works fine in production (separate processes) and fails in tests (same process). The fix — Thread.start with .result instead of start with await — is the sort of incantation you'd never guess from the documentation.

Thanks to @lizmat for motivating this post.

DEV Community: Waclaw Kusnierczyk

Claude Code Plugin Cache

Claude Code Plugin Cache Gotcha: Why Your Edits Aren't Taking Effect

The symptom

The cause

The fix

During active development

Is this a bug?

aigent: toolchain for AI agent skills

The problem

What aigent does

Specification compliance

Beyond individual skills

Where it fits

Get started

About

Auto Memory, Auto Forget

Claude Code's Auto Memory Isn't Thread-Safe

The problem

Why it matters

Possible fixes

Workaround

Bun's Coverage Threshold

Bun's Coverage Threshold: Three Undocumented Behaviors That Will Waste Your Afternoon

The Setup

Gotcha 1: The threshold is per-file, not overall

Gotcha 2: Specifying lines implicitly enforces a function threshold

Gotcha 3: No error output whatsoever

Our Workaround

Bonus: [test].exclude doesn't exist either

Upstream Issues

Takeaways

Two Bugs, One Symptom

The hunt

Bug 1: Thread pool starvation

Bug 2: The invisible space

Why the combination was brutal

Reflections

What `aigent` does

Gotcha 2: Specifying `lines` implicitly enforces a function threshold

Bonus: `[test].exclude` doesn't exist either