DEV Community: pponali

I Ran a Health Check on My Claude Code Setup — Here's What Was Actually Slowing It Down

pponali — Sun, 26 Jul 2026 12:41:18 +0000

I've been running Claude Code against a mid-size monorepo (a Node.js + Spring Boot + Flutter + Kotlin agricultural platform, if you're curious — five components, a strangler-fig microservices migration in progress) for a few months now, wired up with a fairly aggressive set of hooks: repo memory that indexes symbols on every edit, a Postgres-backed transcript store for every prompt and tool call, automatic RCA triggers when a subagent fails, feedback capture on session end. It's a lot of automation, and automation you don't audit eventually silts up.

So I ran /doctor — a setup-health check that treats the Claude Code installation itself as a system worth debugging: duplicate installs, dead config, unused extensions burning context, and — the part that turned out to matter most — hooks that run on every single turn and have quietly gotten slow.

This post is the account of that audit: what it found, what surprised me, and the one bug that was costing 10+ seconds on every conversation turn for a reason that had nothing to do with the code doing the actual work.

Why bother auditing a CLI tool's config

Hooks in Claude Code are shell commands the harness runs automatically around specific events — before a tool call, after a tool call, when a prompt comes in, when the model finishes responding. They're how you bolt persistent memory, telemetry, or guardrails onto an otherwise stateless agent loop. Mine do things like: re-index the codebase's symbol graph after an edit, capture the git diff for feature attribution, and log every prompt/response pair to a database for a later confidence-scoring pass.

The problem with hooks specifically is that they're invisible by design. They don't show up in the conversation. They just... run, in the background, adding latency to every turn, and unless you go looking, a hook that's degraded from "instant" to "12 seconds" reads to the user as "the model got slower today" — nobody thinks to blame the plumbing.

What the audit actually checks

The scan pulls from local, read-only sources only — no telemetry upload, nothing sent anywhere:

Installation health. Are there duplicate installs (native launcher vs. an old npm-global leftover)? Does the resolved binary match what the config thinks is installed? Any broken or colliding agent definition files?
Usage signal for extensions. Every skill, plugin, and MCP server (a connection to an external tool) has either a lifetime usage counter or — for MCP servers, which have none — transcript evidence from recent sessions. Cross-reference both against a window of the 50 most-recently-touched session transcripts.
Checked-in memory file bloat. CLAUDE.md files get loaded into every session's context. Anything in them a fresh session could reconstruct by reading the code (a docker-compose port table, standard flutter build commands already in pubspec.yaml) is dead weight paid every session.
Hook performance. Aggregate durationMs per hook, per event, from the transcript's attachment records. Flag anything that's both frequent (fires every prompt or every tool call) and slow.
Permission friction. Which safe, read-only commands keep getting denied and re-prompted for, that could be pre-approved once.

I ran it, then acted on the findings, which is the part worth walking through.

What was actually wrong

A duplicate install. which -a claude turned up two resolutions — the native launcher I actually use, and a stale @anthropic-ai/claude-code@2.1.76 sitting in an npm-global prefix, two minor versions behind. Harmless on its own, but it's the kind of thing that causes "wait, which version am I even running" confusion six months later. Removed.

One broken, silently-dead agent file. Out of 193 project-level agent definitions, one had no description: in its frontmatter — which means Claude Code never loads it at all. It also happened to collide in name: with a working sibling file in the same directory, which is a separate failure mode (when two files in one directory share a name, the loser is discarded based on directory-read order, which isn't guaranteed stable across machines). Deleted the broken one.

Genuinely unused extensions. A plugin with zero recorded uses since install. An MCP server (Dropbox) with zero invocations across the whole scan window. Both disabled — reversibly, one command each to bring back.

Checked-in CLAUDE.md files carrying content the code already says. My Flutter app's memory file listed the full flutter build/flutter test command set and a directory tree — both fully derivable by reading pubspec.yaml and ls lib/. Same pattern in three other component files: a Kotlin Gradle command list, a Node.js npm run list, a docker-compose port table. None of it was wrong, it was just cost paid on every single session for something a few ls/cat calls reconstruct for free. Trimmed all four down to the parts that aren't derivable — setup steps that need an external file, a gotcha about a migration naming convention, a pointer to an external QA test-case spreadsheet. Those stay, because no amount of reading the repo tells you a Google Sheet exists.

And the big one: hook latency.

The hook that was eating 12 seconds a turn

The Stop hook — the one that fires after every model response — was averaging 12.1 seconds, with a worst case of 113 seconds, across 251 recorded runs in the scan window. The UserPromptSubmit hook (fires on every message you send) was averaging 5.5 seconds. For context: the rule of thumb is that anything running on every prompt or every tool call should stay under roughly 2 seconds, and even the less-frequent session-boundary hooks (SessionStart, Stop) should stay under 10.

My first assumption, walking in, was that the hook scripts referenced a hardcoded path from when I'd set this up on a different machine (a Mac) and were now silently failing on this Linux box — every python3 /Users/me/project/.claude/hooks/whatever.py call would just error out fast and move on. That turned out to be half right: I did find exactly that bug, but in a smaller, unrelated script (a debug-logging hook that was writing to a log path that no longer existed — fast to fail, ~5ms, not the source of the 12-second problem). The actual Stop and UserPromptSubmit hooks had already been fixed to use $PWD and $HOME instead of a hardcoded path.

The real cause was simpler and less obvious: the Stop hook chains six separate calls to a repo-memory CLI, each one invoked as npx -y @invariance/gps <subcommand>. npx -y doesn't just run a cached binary — every invocation re-resolves the package and, in the -y (auto-confirm) case, checks the registry for whether a newer version exists, before it runs anything. Timed cold: 1.6 seconds per call. Six of those, sequentially, in one hook, before the turn is considered "done." UserPromptSubmit chains three more. That's the 12-second average baseline right there — and the 113-second worst case is almost certainly a slow or flaky registry round-trip on top of that, since npx -y's freshness check is a live network call every single time, not a cached one.

The fix was almost embarrassingly small: install the package once, globally, so it's a real binary on $PATH.

npm install -g @invariance/gps --prefix ~/.npm-global

Then swap every npx -y @invariance/gps <subcommand> in the hook config for a plain gps <subcommand>. Same six calls, same behavior — just no per-call registry check and no npm package-resolution overhead.

Before:  npx -y @invariance/gps brief --root "$PWD"   → ~1.6s, network round-trip every time
After:   gps brief --root "$PWD"                        → ~0.7s, resolved once, no network

Six calls at 1.6s each versus six at 0.7s each is roughly the difference between a 10-second tax and a 4-second one, on every single turn — and it eliminates the network-flakiness tail that was almost certainly behind that 113-second outlier. I verified the fix with a direct timing test before and after: 1.601s cold via npx, 0.740s via the global binary, consistently, across repeated runs.

It's worth being precise about what that 0.7 seconds still is, because it's not zero. It's still a fresh Python/Node process spin-up, still a full CLI argument parse, still whatever the tool does internally before it touches the filesystem. Installing globally removes exactly one specific tax — the registry freshness check — and nothing else. If I wanted to go further, the next lever would be collapsing the six sequential subcommands into one long-running call, or making the non-critical ones (suggest, prune) asynchronous so the turn doesn't block on them at all. I didn't do that here, on purpose: the ask was "why is this slow," not "rewrite this tool's invocation model," and a six-line diff that's easy to verify beats a bigger one that's easy to get subtly wrong. Diminishing returns are still returns, but there's a point where the next fix belongs in its own, separately-reviewed change.

The diagram below is the shape of the fix: four hook events (UserPromptSubmit, PreToolUse, PostToolUse, Stop) fire in sequence around every turn, three of them call into the repo-memory CLI, and that's where the cold-start tax was hiding. A separate transcript-logging hook writes every prompt/response pair to Postgres — I profiled that too, out of caution, and it's a non-issue: about 50ms per write, confirmed with a direct psql round-trip test.

What I didn't touch, and why

A couple of things came up during the audit that I deliberately left alone.

The repo memory MCP server (gps, exposed as a set of MCP tools inside Claude Code itself, distinct from the CLI binary discussed above) showed zero tool invocations in the scan window. By the "unused → disable" logic that applied everywhere else, that's a removal candidate. But the project's own guidance mandates using it before any non-trivial edit, and the cost of leaving it enabled is close to zero — MCP tool schemas are deferred by default, meaning only the tool name sits in context until it's actually called, not the full schema. One thin transcript window showing zero calls isn't strong enough evidence to override an explicit, repo-wide instruction, especially when the downside of being wrong (removing something actually load-bearing) is worse than the upside (saving essentially nothing). Sometimes the right call from an audit is "leave it, and say why," not "remove everything unused."

I also didn't touch anything requiring destructive or hard-to-reverse action without asking first — no force-pushes, no permission-mode changes applied without a separate confirmation step, no deleting anything that wasn't obviously dead. Every change made was either trivially reversible (a plugin disable is one command to undo) or a working-tree edit left for review before it got anywhere near a commit.

The takeaway

None of these problems were exotic. A stale duplicate install. A broken frontmatter field. Memory files repeating what the code already states. And a six-line hook chain that had quietly picked up a per-call network round-trip nobody asked for, because npx -y optimizes for "always get the latest version" in a context (a hook that fires hundreds of times a session) where that tradeoff makes no sense at all.

The pattern underneath all of it: automation you don't periodically re-examine degrades in ways that are individually invisible and collectively expensive. A hook doesn't announce that it's gotten 8x slower. It just quietly adds a few seconds to every response until "Claude feels slow today" becomes the ambient explanation, and the actual cause — six npx cold starts nobody's looked at in months — never gets named.

If you're running any nontrivial hook setup, it's worth timing it occasionally. Not because any single hook is doing something exotic, but because "small tax, every single turn" compounds in a way that's easy to stop noticing.

We Audited Our Claude Code Setup Against Anthropic's Own Context-Engineering Rules — Here's What We Found

pponali — Sun, 26 Jul 2026 12:32:46 +0000

The question that started this

We run Claude Code against a fairly large, fairly automated repository — a farming-assistance platform with a Node.js backend, a Flutter app, a React dashboard, an in-progress Spring Boot microservices migration, and a home-grown "repo memory" layer called gps that captures invariants, lessons, and preferences across sessions. Over several months we'd wired up a lot of automation: session-start hooks, prompt-submit hooks, auto-captured preferences, persona plugins, a mandatory agent-dispatch table. It felt sophisticated. It also felt, some days, slow to get going — every session seemed to start with a wall of text before any real work happened.

So when Anthropic published "The New Rules of Context Engineering for Claude 5 Generation Models", we asked the obvious question: are we actually following our own advice, or have we just accumulated automation that looks like good practice?

This post is the audit, the root cause we found, and the fix — including a mistake we made mid-fix that's worth telling on ourselves for.

What the blog post actually says

Stripped of marketing language, the post boils down to five concrete rules:

Keep CLAUDE.md lightweight. Describe gotchas and non-obvious patterns, not everything you know about the repo. Organize by relevance, not comprehensiveness.
Progressive disclosure. Load context at the right time — skills, references, and detail should be pulled in when needed, not front-loaded into every session regardless of task.
Trust the model's judgment. Remove redundant guardrails and standing instructions that the newer models don't need spelled out every time.
Rely on automatic memory, not manual dumps. Don't hand-maintain a giant preferences block in a markdown file — let the memory system surface the right thing at the right time.
Design tools and interfaces, not prose. Push instructions into tool schemas and parameter design rather than repeating them in the system prompt.

None of this is radical. It's the same discipline good engineers apply to code: don't load everything into scope just because you might need it, don't repeat yourself, don't keep dead configuration around because removing it feels risky. The interesting part is applying it literally, to an actual production Claude Code setup, and seeing what falls out.

What we found when we actually measured it

We started by tracing exactly what gets injected into the context window at SessionStart, since that's the one moment every single session pays the cost.

The .claude/settings.json SessionStart hook was running a chain of gps commands. Three of them, in sequence, all touched the exact same data:

gps preferences --write      # bakes a markdown block into CLAUDE.md
gps preferences --markdown   # prints the same list to stdout
gps prime                    # emits a session primer that overlaps both

--write persisted a ... block directly into CLAUDE.md, which is read every session. --markdown printed the identical list again as hook stdout, which Claude Code surfaces as a second system reminder. prime added a third pass that substantially overlapped both. Same ~60-line list, injected three times, every single session, before any actual task began.

That's rule #1 and #4 violated in one shot: a hand-persisted dump in CLAUDE.md (the opposite of "lightweight, gotchas only") that was also duplicated by the very memory system that was supposed to replace it.

Then we looked at what was actually in that preferences list, because 60 lines of genuine cross-cutting invariants would at least be defensible even if wastefully injected three times. It wasn't. Pulling the raw store (.gps/preferences.yml) showed 105 entries, and a good two-thirds of them weren't standing preferences at all — they were things like:

A verbatim quote from an eval judge's commentary: "Judge weakness: 'never specifies idempotency for event consumers.'"
A code comment lifted out of context: // replace, never append
A fragment of a test assertion: test('refresh() replaces list, never appends', () async { ...
Duplicate phrasings of the same secrets rule, recorded three separate times with three separate IDs.

The mechanism responsible was gps capture-preference --emit and gps capture-directive --emit, both wired into the UserPromptSubmit hook — meaning they fired on every single message in every session. Their logic was a bare regex cue: anything matching \b(?:please\s+)?never\b or \balways\b, recorded as a standing, always-injected "preference," with source: auto and no expiry. It didn't matter whether the match came from the user's actual instruction, a pasted log, a quoted test file, or the agent's own prior output describing what an eval judge said. If the substring was there, it got written to disk and re-injected every session forever.

This is the sharpest version of the trap the blog post warns about: "automatic memory" sounds like the responsible, judgment-trusting choice — right up until the automation itself has no judgment. A regex doesn't know the difference between a user's hard rule and a stray quote in a transcript. Left alone, it just accumulates noise at the same rate it accumulates signal, and every session pays for both.

On top of that, we found two plugins — caveman (terse response style) and ponytail (anti-overengineering behavioral rules) — set to always-on in the global enabledPlugins config. Both inject their full rule text (roughly 40 lines each) at every SessionStart, regardless of whether the task at hand has anything to do with response verbosity or engineering discipline. Useful personas, wrong default: standing injection instead of on-demand invocation is exactly the "load everything just in case" pattern rule #2 argues against.

The fix

We worked through it in four concrete steps.

1. Collapse the triplicated emission. Dropped --write and --markdown from the SessionStart hook, keeping a single gps prime pass. One source of truth, one injection per session.

2. Strip the manual dump from CLAUDE.md. Removed the  block entirely. CLAUDE.md went back to being what rule #1 asks for: hand-curated gotchas, not an auto-regenerated preference log.

3. Prune the store. We pulled the full 105-entry list and manually classified every one. About 35 were genuine, cross-cutting invariants worth injecting into every session regardless of task — secrets handling, PII rules, git-push restrictions, migration reversibility, PCI scope boundaries. The other 70 were dropped: judge commentary, code fragments, near-duplicate phrasings, symbol-specific one-off fixes that only matter when that exact piece of code is touched again (those still exist — just surfaced on demand via gps prepare_edit when relevant, not blasted into every session).

4. Fix the actual leak, not just the symptom. This is the part worth dwelling on, because the first three steps only clean up what had already accumulated — they don't stop it from happening again. The regex-based capture-preference/capture-directive hooks were still wired in and would refill the store with the same class of noise within days. We replaced them with a small filtered wrapper script that:

reads only the literal current user prompt ($CLAUDE_USER_PROMPT), never the transcript, never the agent's own output, never quoted or pasted content;
requires an actual imperative sentence shape — the text has to start with never, always, don't, must, or should, not just contain the word anywhere;
rejects lines that look like code, quotes, or table rows (//, #, |, ,>`);
checks the existing store for a near-duplicate before writing anything new.

We disabled caveman and ponytail as always-on plugins and left them invokable via their slash commands, on demand, exactly when their behavior is actually wanted.

The mistake worth admitting

Midway through pruning that 105-entry list by hand, we cut a handful of rules that were real, not noise — a "reference the config key, never the value" secrets-handling convention, a backend mock-fallback contract invariant, an API schema-evolution rule ("add fields, never remove"), a known config-server caching gotcha. They looked narrow enough to fold into "one-off" at a glance, but they were genuinely cross-repo conventions, not symbol-specific trivia.

The user caught it with a simple question: "is it losing existing functionality?" That's the right question to ask after any aggressive prune, automated or manual — and it's the reason we're writing this section at all. Nothing was destroyed; the full pre-prune store was still sitting in git history, recoverable with one git show. But it's a useful reminder that "delete the noise" and "delete everything that isn't obviously load-bearing" are not the same operation, and doing the second by accident while intending the first is an easy mistake to make when you're skimming 105 entries under time pressure.

Verifying the automated version wasn't just automating the same mistake

Before trusting the new filtered capture script, we tested it against an isolated scratch copy of the .gps store — not the live repository — feeding it a mix of a genuine directive and the exact kind of noise that had polluted the original store:

plaintext Never log raw request bodies for the payment endpoint. Always validate the webhook signature before processing. The judge said: never sent to the network, that's just eval commentary.

The result: both real directives were captured and written to the store correctly. The judge-commentary sentence was rejected, because it doesn't open with an imperative verb — it opens with "The judge said." That's a small test, but it's exactly the discriminator the original regex lacked, and it's cheap enough to run before wiring anything back into a live hook.

What this actually bought us

Token-wise, the honest estimate is roughly ~1,200+ tokens injected at every SessionStart before the fix, down to ~400 after — a triplicated 60-line list plus a noisy 105-entry store plus two always-on plugins, versus one clean primer pass plus a curated 35-entry store plus plugins that only cost anything when explicitly invoked. That's not a huge absolute number in isolation, but it's paid on every single session, compounds across a team, and — more importantly than the raw token count — it was diluting the signal-to-noise ratio of the one list that's supposed to carry the invariants Claude should never violate. A 35-item list of real rules is something a model can actually hold onto. A 105-item list where two-thirds is eval-transcript noise trains exactly the wrong instinct: skim past it, because it's mostly not going to matter.

The generalizable lesson

None of the individual fixes here are exotic — collapse duplicate emissions, prune a noisy store, tighten a regex, gate a plugin behind explicit invocation. The useful part is the audit discipline itself: pick a set of concrete, checkable rules (Anthropic gave us five good ones), and then actually trace what your own automation does against them, hook by hook, rather than assuming that "we have automatic memory" or "we use skills" means the rules are satisfied by construction. Automation that was designed well can still drift into violating the very principles it was built to serve — usually quietly, one auto-captured preference at a time, until someone asks what's actually in the store.

If you're running Claude Code with any nontrivial hook setup — gps, a custom memory layer, auto-capture of any kind — it's worth doing the same trace. Open the SessionStart hook chain, count how many times the same information gets emitted, and go look at what your "automatic" capture mechanism has actually been recording for the last few months. You may be surprised what's in there.

From Monolith to 23 Microservices: A Strangler-Fig Migration

pponali — Mon, 13 Jul 2026 12:10:23 +0000

I've spent the last several months rebuilding the backend for Kheti Sahayak, an agricultural assistance platform, from the ground up — taking it from a single Node.js/Express monolith to 23 Spring Boot microservices. Not because microservices are trendy, but because the monolith had genuinely started working against us: every deploy touched everything, every schema change was a coordination problem, and the team (well, mostly just me) couldn't ship one feature without risking three others.

Here's how the migration actually went, and what I'd tell someone about to do the same thing.

Strangler-fig, not big-bang

The instinct when a monolith gets painful is to stop, design the "real" architecture, and rewrite. I didn't do that, and I'd argue you shouldn't either unless you can afford months of feature freeze.

Instead I used the strangler-fig pattern: new functionality got built as standalone Spring Boot services from day one, while the old Node.js backend kept serving existing traffic. Over time, more and more surface area moved to the new services, until the monolith's job shrank to "the stuff nobody's gotten around to migrating yet." The system stayed shippable the entire time — there was never a week where the app was down for "the migration."

One front door: the API Gateway

With 23 services, you can't have every client know 23 different addresses. Every request — from the Kotlin/Compose Android app or the React admin dashboard — goes through a single Spring Cloud Gateway instance. It's the only thing external clients ever talk to directly.

# gateway-service application.yml — routing to internal services
spring:
  cloud:
    gateway:
      routes:
        - id: user-service
          uri: lb://user-service
          predicates:
            - Path=/api/users/**
        - id: payment-service
          uri: lb://payment-service
          predicates:
            - Path=/api/payments/**
          filters:
            - name: RequestRateLimiter

The gateway also owns JWT verification before a request ever reaches a downstream service — auth logic doesn't get duplicated 23 times.

Finding each other without hardcoded IPs

Services need to find each other, and hardcoding hostnames doesn't survive contact with real deployments. I run a discovery-service (Eureka) that every service registers with on startup, and a config-service that serves configuration — including secrets — encrypted at rest.

# any service's bootstrap config
eureka:
  client:
    service-url:
      defaultZone: http://discovery-service:8761/eureka
spring:
  config:
    import: "configserver:http://config-service:8888"

That second point matters more than it looks: no service carries plaintext secrets in an env var or a properties file. The config server decrypts on the fly using a key that never leaves the server itself.

Not everything needs to be synchronous

Some of these services genuinely don't need to talk to each other in real time. When an order gets placed, the notification service doesn't need to block the checkout flow to send a push notification — it just needs to know the order happened, eventually. That's where Kafka comes in.

@Service
public class OrderEventPublisher {
    private final KafkaTemplate<String, OrderEvent> kafkaTemplate;

    public void publishOrderPlaced(OrderEvent event) {
        kafkaTemplate.send("orders.placed", event.getOrderId(), event);
    }
}

notification-service consumes from that topic independently and fires push notifications (via Firebase Cloud Messaging), SMS, and text-to-speech — the last one matters a lot for farmers who may not read English fluently. That's an accessibility requirement that shaped the architecture, not an afterthought bolted on later.

Observability isn't optional past a certain scale

With one service, you can tail -f a log file and mostly know what's happening. With 23, you can't. The stack I run:

Prometheus scraping metrics from every service
Grafana for dashboards
Elasticsearch, Logstash, Kibana (the ELK stack) for centralized logs
An APM server for distributed tracing across service boundaries
Purpose-built exporters for Postgres, Redis, and Kafka broker metrics

# prometheus scrape config (excerpt)
scrape_configs:
  - job_name: 'gateway-service'
    metrics_path: '/actuator/prometheus'
    static_configs:
      - targets: ['gateway-service:8080']

Fourteen components total in that stack. It sounds like a lot for a side project, but the alternative — debugging a cross-service failure blind — is worse.

Where the AI actually lives

One service doesn't run on the JVM at all: a FastAPI service handles crop disease detection from photos farmers upload, sitting alongside the Java stack and reached the same way every other service is — through the gateway. Polyglot isn't a religion here; it's just that Python's ML tooling is better than Java's for this specific job, so that's what that one service uses.

What I'd actually tell you

If you're staring down a monolith that's slowing your team (or just yourself) down: don't wait for permission to do a "proper" rewrite. Strangle it. Ship the new service, route one path to it, watch it work in production, then move the next path. The migration becomes a series of small, reversible bets instead of one enormous one — and you never have to explain to anyone why the app is down for a week.

Kheti Sahayak is a solo project — architecture, migration, and all the mistakes along the way are mine. Happy to go deeper on any piece of this in the comments.

Scoring AI Agents: Deterministic Metrics + an LLM Judge

pponali — Thu, 18 Jun 2026 05:57:49 +0000

I run a lot of small autonomous agents — backend, frontend, mobile, devops, monitoring tiers, each one a prompt with a job. The moment you have more than a handful, a question gets uncomfortable: are they actually any good, and did my last prompt edit make them better or worse? "It looked fine when I tried it" doesn't scale. So I built a small evaluation framework that answers it with numbers, and then closes the loop by improving the prompts automatically.

Here's how it's put together.

Deterministic first, LLM second

The core principle: measure what you can measure deterministically, and only reach for an LLM judge where you must. Deterministic metrics are free, instant, and reproducible. An LLM judge is none of those things — so it's opt-in and purely additive.

The harness runs each agent as an isolated subprocess, feeds it a fixed fixture on stdin, captures stdout, and scores the result against expected outputs. No shared state, no network, no flakiness.

python3 harness/evaluate.py \
  --agents-dir ./agents \
  --out-dir ./out \
  --seed 42 \
  --timeout 10

That single command produces report.json, a human-readable report.txt/.html, a failures.json, and appends to history.jsonl so you can track drift over time. No SDK, no API key required.

The agent contract is dead simple

Every agent is just a program that reads a task from stdin and writes an answer to stdout. That's the whole interface — which is exactly why subprocess isolation works.

# agents/sample_agent/agent.py
import sys

def main():
    task = sys.stdin.read().strip()
    # ... the agent's real logic ...
    print(answer)

if __name__ == "__main__":
    main()

Because the contract is a process boundary, an "agent" can be Python, a shell script, or anything that respects stdin/stdout. The harness doesn't care.

Five metrics, one threshold gate

Each run is scored on five deterministic metrics, checked against thresholds declared in metrics.yaml:

thresholds:
  accuracy: 0.8                  # exact normalized matches
  fuzzy_score: 0.7               # average sequence similarity 0-1
  timeout_rate: 0.1              # fraction of runs that timed out
  safety_violations: 0           # outputs matching unsafe patterns
  reproducibility_variance: 0.05 # std-dev across repeated runs

reproducibility_variance is the one people forget. Running an agent once tells you what it did; running it several times and measuring the spread tells you whether you can trust what it did. A correct-but-nondeterministic agent is a latent bug.

The LLM judge, when correctness isn't enough

Some qualities aren't string-comparable: did the agent stay in role? Did it respect its constraints? Is the output well-formed and complete? For those, an opt-in judge sends the rubric, the task, and the agent's real output to Claude and gets back a structured verdict — validated against a JSON schema so a malformed judgment can't poison the report.

{
  "overall": 7.5,
  "dimensions": {
    "contract_adherence": 8,
    "role_fidelity": 9,
    "constraint_safety": 7,
    "output_format": 6,
    "completeness": 8
  },
  "verdict": "needs_improvement",
  "weaknesses": [
    { "dimension": "output_format", "prompt_fix": "Require a fenced JSON block in the system prompt." }
  ]
}

The judge runs three ways depending on what you have: the Anthropic API (--llm-judge), the headless Claude Code CLI for subscription-only setups (--llm-judge-cli), or pre-computed verdicts from any source (--llm-verdicts). Same report either way. Identical outputs are judged once to bound cost.

The important detail: every weakness must map to a fixable line in the agent's prompt. The judge isn't there to vibe-check; it produces edits.

Closing the loop: the prompts improve themselves

This is where it gets fun. A fail verdict and its prompt fixes land in failures.json, which feeds a GEPA-style improve loop: judge each candidate prompt per dimension, mutate the frontier candidate that owns the weakest dimension, keep a pool of candidates rather than greedily chasing one best, and write back only the best pool member. Scores and mutations are persisted to repo memory so the next run starts informed, and a nightly job commits improvements.

The diagram above shows the whole flow: inputs → harness → (metrics + judge) → reports → improve loop, with a feedback edge carrying mutated prompts back to re-evaluation.

What I'd tell my past self

Deterministic metrics are the foundation, not the LLM judge. The judge is a scalpel, not a hammer.
Validate the judge's output against a schema. An LLM that returns malformed JSON shouldn't be able to corrupt your report.
Track history. A single score is a snapshot; history.jsonl is the trend that tells you whether you're actually getting better.
Make every critique actionable. "This is weak" is noise. "Add a fenced JSON block to line 12" is a commit.

The payoff is a system where I can change a prompt, run one command, and know — numerically — whether I helped or hurt, with the loop quietly fixing the easy regressions for me.

I built a Claude Code skill that discovers which automations to build — by mining my own work

pponali — Thu, 18 Jun 2026 05:34:53 +0000

Most automation projects build an automation. This one builds a system that discovers which automations to build — by mining your own recent work — and then packages the high-confidence ones into reusable tools. It's a self-improving skill for Claude Code.

The problem: repeated manual work is invisible

You feel it but rarely measure it: the same multi-step sequence done by hand for the third time. A focused bug-fix → branch → conventional commit → PR cycle. A QA-sweep dispatch. A release deploy. Each repetition is a signal that an abstraction is missing — but nobody systematically finds those signals. They're scattered across git history, terminal sessions, and memory.

What `distill-workflows` does

distill-workflows is a Claude Code skill that turns that scattered signal into reusable tooling, in one pass:

Scan three sources of "what was done recently":
- Git commit-shape frequency — normalized subjects, ranked.
- Session transcripts (*.jsonl) — repeated bash command patterns and recurring user-request phrasings. What you did and what you were asked.
- Repo memory (GPS) — lessons, decisions, and promotion candidates already flagged.
Cluster the raw signal into named, repeated procedures.
Reconcile against a persistent cross-session ledger so a pattern seen once per session still accumulates toward the bar over time.
Score each candidate on frequency × determinism × friction.
Propose a ranked table and confirm with the human before doing anything irreversible.
Scaffold the winners from templates into the right artifact — a skill, a subagent, or a workflow — and record the rationale back into memory.

The architecture

The diagram above maps the flow left-to-right: Signal Sources → Scanner (scan.sh) → Distill Engine → Packaging → Outputs, with a Persistent Ledger the engine reads and writes, and a dashed cross-session feedback loop that feeds each run's recorded rationale back into the next run's sources.

A few design choices worth calling out:

Read-and-propose first, scaffold on confirmation. Nothing lands on disk without a human gate. Automation that edits your repo should ask first.
Extend before create. If 80% of a candidate already lives in an existing skill, the engine says so instead of producing a near-duplicate.
The ledger fixes the frequency blind spot. A workflow you do once per session looks rare inside a single run. Accumulating "seen" counts across runs is what lets genuinely recurring work eventually qualify.

It found real work — on itself

Run against its own repo, the scanner surfaced a pattern repeated 50+ times that nobody had abstracted: a single-concern Android/Kotlin fix shipped as a small PR with the same conventions every time (branch naming, conventional commit scope, base branch, size limit, no AI attribution). The engine packaged it into an android-fix-pr skill — exactly the kind of convention layer the generic commit/create-pr tools don't encode.

The higher-frequency QA-sweep pattern was also detected, but the engine correctly declined to package it: it already existed as a parameterized workflow. Knowing when not to build is half the value.

How it's built

A SKILL.md procedure the agent follows.
A scan.sh signal miner — jq over transcripts, git log shape analysis, gps recall, artifact inventory — emitting one structured report.
A watchlist.md ledger for cross-session frequency.
Artifact templates for skill / subagent / workflow.
GPS repo memory for persisted decisions.

What's next

Schedule it to run automatically and surface a weekly "candidate digest."
Rank promotion candidates via the GPS MCP tool.
Share distilled skills across repos.

Built with Claude Code. The core idea generalizes well beyond one repo: point a discovery loop at your own work history, score what repeats, and let the high-confidence patterns become tools.

I tried to run Google Antigravity on an arm64 VM. It did not go well.

pponali — Sun, 24 May 2026 06:08:35 +0000

TL;DR

I tried to install Google Antigravity (the new agent dev IDE) on a headless arm64 Ubuntu VM. It is a x86_64 Electron app. Three emulation layers later, I gave up and uninstalled everything. Here is the trail of pain so you do not repeat it.

The setup

Oracle Cloud Ampere VM, aarch64, Ubuntu 24.04 LTS
Headless (no display server, SSH only)
96GB disk, 24GB RAM
Antigravity build: linux-x64 tarball, 168MB, Electron-based

The plan: install a desktop environment + RDP, emulate x86_64, run Antigravity, connect from my laptop. Sounds reasonable. It is not.

Round 1: qemu-user-static

The classic approach. Install qemu-user-static + binfmt-support, register qemu-x86_64 in binfmt_misc, point at an amd64 sysroot, run the binary.

sudo apt-get install -y qemu-user-static binfmt-support

First exec attempt:

x86_64-binfmt-P: Could not open '/lib64/ld-linux-x86-64.so.2': No such file or directory

No amd64 dynamic linker. Bootstrap one with debootstrap:

sudo debootstrap --arch=amd64 --variant=minbase noble /opt/amd64-sysroot \
  http://archive.ubuntu.com/ubuntu

debootstrap finished extracting but post-install scripts crashed:

Setting up libpam-modules:amd64 (1.5.3-5ubuntu5) ...
x86_64-binfmt-P: QEMU internal SIGSEGV {code=MAPERR, addr=0x20}
Segmentation fault (core dumped)

qemu-user segfaulted on basic dpkg postinst. If passwd cannot configure itself, Chromium has zero chance. This is a known qemu-user limitation: threading + atomic ops + signal handling get exotic enough that complex binaries crash.

Verdict: dead.

Round 2: FEX-Emu

FEX-Emu is purpose-built for this: userspace x86_64 -> aarch64 translation, designed with Chromium and Wine in mind. There is a PPA.

sudo add-apt-repository -y ppa:fex-emu/fex
sudo apt-get install -y fex-emu-armv8.2 fex-emu-binfmt64

(Pick the armv8.X package matching your CPU — check /proc/cpuinfo features. Ampere Altra has lse, lrcpc, asimddp => armv8.2.)

FEX needs a rootfs. The shipped fetcher (FEXRootFSFetcher) opens a zenity GUI even with -y --assume-yes. On a headless box it hangs forever holding zero network connections.

Skip it. Pull the JSON manifest and fetch directly:

curl -fsSL https://rootfs.fex-emu.gg/RootFS_links.json | \
  python3 -c "import json,sys; d=json.load(sys.stdin); \
  [print(k, v['URL']) for k,v in d['v1'].items() if 'Ubuntu_24' in v['URL']]"

I grabbed the SquashFS image (~500MB), extracted it to a directory (no FUSE needed), pointed ~/.fex-emu/Config.json at it:

{ "Config": { "RootFS": "Ubuntu_24_04" } }

Started FEXServer -p 3600 (persistent for an hour), then:

FEXInterpreter /opt/antigravity/antigravity --version

First real progress:

FATAL:sandbox/linux/suid/client/setuid_sandbox_host.cc:166]
The SUID sandbox helper binary was found, but is not configured correctly.

Fixable. chmod 4755 + chown root:root on chrome-sandbox. Also disable AppArmor restricted userns (Ubuntu 24.04 added this):

sudo chown root:root /opt/antigravity/chrome-sandbox
sudo chmod 4755 /opt/antigravity/chrome-sandbox
sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0

Try again under xvfb with --no-sandbox:

xvfb-run -a FEXInterpreter /opt/antigravity/antigravity --no-sandbox --version

Result:

Trace/breakpoint trap (core dumped)

V8 JIT crashed. Electron's V8 generates x86_64 machine code at runtime and runs it. FEX must re-translate that emitted code on the fly. It works for many binaries; for Electron with modern V8 it does not. SIGTRAP every time.

Verdict: dead.

Round 3: there is no round 3

Options I considered and rejected:

box64 — same userspace translation class, same V8 problems.
Full-system KVM x86_64 VM — nested virt on arm64 Ampere is brutally slow, needs ~15GB disk, hours of setup, and you still need a display server inside.
Wait for an arm64 Antigravity build — not on the roadmap.

The actual answer

Antigravity is an IDE. IDEs have Remote-SSH. The correct topology:

[Local laptop: Antigravity x86_64]  --SSH-->  [arm64 VM: your code]

The IDE runs on hardware that natively supports it. The VM stays headless and serves files + runs your stack. No emulation, no RDP, no zenity, no V8 JIT translation.

I should have done this in the first 30 seconds.

What it cost

~2 hours
~3GB of packages installed and then purged
168MB tarball + 836MB EroFS + 497MB SquashFS rootfs (also purged)
A renewed appreciation for native binaries

Lessons

Check arch before download. arch64 + linux-x64 .tar.gz = no.
Headless VM + Electron app = pick your pain. RDP into a heavy desktop, or admit the IDE belongs on your laptop.
qemu-user is for static utilities, not Chromium.
FEX-Emu is impressive but V8 self-modifying code is its kryptonite.
FEXRootFSFetcher is GUI-only; fetch the rootfs JSON directly on headless machines.

If you want to try anyway, the squashfs rootfs URL is in https://rootfs.fex-emu.gg/RootFS_links.json. Don't say I didn't warn you.

I shipped my first agentic workflow on GitHub Actions — 4 AI reviewers on every PR

pponali — Mon, 18 May 2026 07:29:54 +0000

I run Khetisahayak — a small agritech app — solo. Every PR I open has nobody to review it but me, and I review my own code about as well as anyone reviews their own code. So I built a GitHub Actions workflow that drops four AI reviewers and a test runner onto every PR. This is the first real "agentic" workflow I've shipped, and it now greets every commit I push with five separate opinions.

This post walks through exactly how it works — trigger, sequence, and flow — plus what I'd change.

Here's what one PR actually looks like in production (this is the fallback path when the Gemini API rate-limits us — more on that at the end):

Four bot comments, one per persona — Senior Developer, CSO, Engineering Lead, Software Architect — and a fifth from the test runner. When the AI call succeeds, those "Automated review could not be completed" blocks are replaced with actual line-by-line review feedback.

The two files that do everything

The whole system is two files:

.github/workflows/code-review-agents.yml — the GitHub Actions workflow (the orchestration)
.github/scripts/review_agent.py — a ~120-line Python script that calls Gemini once per reviewer persona

That's it. No Lambda, no queue, no separate review service. GitHub Actions is the runtime.

1. The trigger

on:
  pull_request:
    branches: [main, develop]
    types: [opened, synchronize, reopened]

Fires when a PR targeting main or develop is:

opened — PR created
synchronize — new commits pushed to the PR branch
reopened — closed PR reopened

It does not fire on direct pushes to main, draft PRs (until marked ready), PRs targeting other branches, comments, or label changes. That's deliberate — I don't want a reviewer firing every time someone reacts with a 👍.

Permissions are scoped tight:

permissions:
  contents: read
  pull-requests: write
  issues: write

Read the code, write comments. Nothing else.

2. The sequence — five jobs, one DAG

The workflow defines five jobs. GitHub Actions runs them according to needs: declarations:

flowchart TD
    A([PR event]) --> B[L1: peer-review]
    A --> D[L4: security-review]
    A --> E[test-execution]
    B --> C[L2: lead-review]
    C --> F[L3: architect-review]
    B --> G[review-gate]
    C --> G
    F --> G
    D --> G
    E --> G

    style B fill:#dbeafe,stroke:#2563eb
    style C fill:#dbeafe,stroke:#2563eb
    style F fill:#dbeafe,stroke:#2563eb
    style D fill:#fee2e2,stroke:#dc2626
    style E fill:#dcfce7,stroke:#16a34a
    style G fill:#f3f4f6,stroke:#6b7280

Three things kick off in parallel the moment a PR event lands:

peer-review (L1) — code style, correctness, DRY
security-review (L4) — OWASP, secrets, injection, auth
test-execution — actually runs Jest + Flutter tests in a real Postgres container

A sequential chain runs alongside:

lead-review waits on peer-review finishing
architect-review waits on lead-review finishing

The final gate waits on all five:

review-gate:
  needs: [peer-review, lead-review, architect-review, security-review, test-execution]
  if: always()

if: always() means the gate runs even if upstream jobs fail. Right now it just echoes each job's result — it doesn't actually block the merge. To make it blocking, you add a step that exits non-zero on any failure, then mark review-gate as a required check in branch protection. (I have not done this yet. Don't be like me.)

Observable wall-clock timing on a typical PR:

T=0: peer + security + tests start
T≈45s: peer finishes → lead starts
T≈90s: lead finishes → architect starts
T≈3–8 min: tests finish (usually the slowest)
T≈4–9 min: review-gate fires

End-to-end: roughly 5–10 minutes per PR, with 4 AI comments + 1 test report appearing on the PR.

3. The flow inside one review job

Every AI review job is the same 4-step pattern. Here's peer-review as the template:

peer-review:
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
      with: { fetch-depth: 0 }

    - name: Get PR diff
      env: { GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} }
      run: |
        gh pr diff ${{ github.event.pull_request.number }} > /tmp/pr_diff.txt
        head -c 30000 /tmp/pr_diff.txt > /tmp/pr_diff_truncated.txt

    - uses: actions/setup-python@v6
      with: { python-version: '3.11' }

    - name: Run Peer Review
      env:
        GEMINI_API_KEY: ${{ secrets.GEMINI_API_KEY }}
        PR_TITLE: ${{ github.event.pull_request.title }}
        PR_BODY: ${{ github.event.pull_request.body }}
        PR_NUMBER: ${{ github.event.pull_request.number }}
      run: python3 .github/scripts/review_agent.py peer

    - name: Post Peer Review Comment
      env: { GH_TOKEN: ${{ secrets.GITHUB_TOKEN }} }
      run: |
        gh pr comment ${{ github.event.pull_request.number }} \
          --repo ${{ github.repository }} \
          --body-file /tmp/review_peer.md

Step by step:

Checkout — full clone (fetch-depth: 0). Honestly overkill since we use gh pr diff which hits the GitHub API, not local git. A shallow clone would be fine.
Get the diff — gh pr diff <num> writes the diff to disk, then head -c 30000 truncates to fit the model's context window.
Run the Python agent — picks the right persona prompt, posts to Gemini, writes a markdown file.
Post the comment — gh pr comment --body-file drops the markdown onto the PR.

The four reviewer jobs are nearly identical — only the persona argument changes (peer, lead, architect, security).

The Python script — one file, four personas

PROMPTS = {
    "peer": {
        "role": "Senior Developer (Peer Reviewer)",
        "emoji": "👨‍💻",
        "focus": (
            "You are a senior developer doing a peer code review.\n"
            "Focus on:\n"
            "1. Code correctness — logic bugs, off-by-one, null checks\n"
            "2. Code style — naming, readability, comments\n"
            "3. DRY violations\n"
            "4. Error handling\n"
            "5. Edge cases\n"
            "Rate: APPROVE, REQUEST_CHANGES, or COMMENT."
        ),
    },
    "lead":      { "role": "Engineering Lead",          "focus": "..." },
    "architect": { "role": "Software Architect",        "focus": "..." },
    "security":  { "role": "Chief Security Officer",    "focus": "..." },
}

prompt = (
    f"{config['focus']}\n\n"
    f"PR #{PR_NUMBER}: {PR_TITLE}\n"
    f"Description: {PR_BODY}\n\n"
    f"Diff:\n```
{% endraw %}
\n{diff_text[:25000]}\n
{% raw %}
```\n\n"
    f"Respond in markdown. Start with your verdict, then list findings."
)

url = f"https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key={API_KEY}"
req = urllib.request.Request(url, data=payload, headers={"Content-Type": "application/json"})
with urllib.request.urlopen(req, timeout=60) as r:
    output = json.loads(r.read())["candidates"][0]["content"]["parts"][0]["text"]

No SDK, no framework. Stdlib urllib, one POST to Gemini, write the response to /tmp/review_<level>.md. The whole script is ~120 lines.

The security persona prompt is the most useful to look at, because it's the one that has actually caught things:

You are a security officer reviewing this PR for vulnerabilities.
Check for:
1. OWASP Top 10 — SQL injection, XSS, CSRF, broken auth, SSRF
2. Secrets — hardcoded API keys, tokens, passwords, connection strings
3. Input validation — unsanitized user input, path traversal
4. Authentication/Authorization — missing auth checks, privilege escalation
5. Data exposure — PII leaks in logs, overly permissive CORS
6. Dependency risk — known CVEs in added dependencies
7. Cryptography — weak algorithms, insecure random generation
For each finding, provide: severity (Critical/High/Medium/Low), location, and fix.

It once flagged a JWT_SECRET I'd inlined into a .env.example "for convenience." Worth the API spend by itself.

4. The flow inside the test-execution job

The test job has a different shape — it actually runs code instead of asking an LLM about code:

test-execution:
  services:
    postgres:
      image: postgres:14
      env:
        POSTGRES_USER: test
        POSTGRES_PASSWORD: test
        POSTGRES_DB: kheti_sahayak_test
      ports: ['5432:5432']
      options: >-
        --health-cmd pg_isready
        --health-interval 10s
        --health-timeout 5s
        --health-retries 5

  steps:
    - uses: actions/checkout@v4
    - uses: actions/setup-node@v4
      with: { node-version: '20.x' }
    - uses: subosito/flutter-action@v2
      with: { flutter-version: '3.29.0', channel: 'stable', cache: true }

    - name: Run Backend Tests
      continue-on-error: true
      working-directory: kheti_sahayak_backend
      env:
        DATABASE_URL: postgresql://test:test@localhost:5432/kheti_sahayak_test
      run: |
        npm install
        npm test -- --coverage --json --outputFile=/tmp/backend_test_results.json

Two things worth calling out:

Real Postgres in a service container — no SQLite-in-memory shortcut. The backend tests hit a real DB, the same major version as prod.
continue-on-error: true on each suite — if Jest fails, Flutter tests still run. The job ends with a markdown report that shows ✅/❌ per suite and gets posted as a comment.

5. The gotchas (and the 429 in that screenshot)

Now the part I'd actually change.

1. The sequential L1→L2→L3 chain wastes time. Nothing in the lead prompt actually uses peer-review output — each reviewer reads the same diff independently. Running all four review jobs in parallel would cut wall time roughly 3×. The chain made sense when I imagined later reviewers reading earlier reviewers' comments. They don't.

2. review-gate doesn't actually gate anything. It just echoes results. Branch protection has to do the real enforcement. Easy to miss.

3. Every job re-runs gh pr diff. Cheap but wasteful. A single setup job that uploads the diff as an artifact would be cleaner.

4. fetch-depth: 0 on every job is overkill. gh pr diff is an API call.

5. The 429 in the screenshot up top. Four jobs hitting Gemini within ~30 seconds of each other, free tier, no backoff. The Python script catches the exception and writes the "Automated review could not be completed" message you see in the screenshot — so the workflow stays green, but the PR ends up with four useless comments. Two fixes I'm considering: add a small retry-with-jittered-backoff in the script, and stagger the jobs (security can wait 60s; it's not on the critical path).

Why I built it this way

I wanted four opinions, not one synthesized one. When a real team reviews a PR, the security person notices different things than the architect. Combining the personas into one prompt blurs that. Splitting them into separate jobs costs me a few extra API calls but gives me four distinct comment threads on the PR — which is exactly the shape a human reviewer cluster would have.

Total cost: roughly $0.01 per PR at Gemini 2.0 Flash prices, plus GitHub Actions minutes (free for me on a personal repo). Cheaper than coffee, more thorough than me reviewing my own PR at 11pm.

The files, in full

If you want to drop this into your own repo:

Put the workflow at .github/workflows/code-review-agents.yml
Put the script at .github/scripts/review_agent.py
Add GEMINI_API_KEY to your repo's Actions secrets
Open a PR

That's the whole setup. No external service, no webhook, no infrastructure.

If you build something on top of this, I'd love to hear what you change — especially how you handle the rate-limit problem and whether you ever managed to get one reviewer to actually read another's comments.

Stop Wrestling with Merge Conflicts: Automate the Whole Workflow

pponali — Tue, 12 May 2026 16:08:51 +0000

It's 4:47 PM on a Friday. You've been coding all week on a feature you're proud of. You open a PR, and GitHub greets you with the one message that turns your stomach:

"This branch has conflicts that must be resolved."

You already know what's waiting. The pom.xml has diverged again. Someone on main bumped a YAML config. There are three Markdown docs with ugly <<<<<<< HEAD markers scattered through them. You're not shipping today.

Every software developer has lived this moment. And most of us keep solving it the same slow, error-prone, manual way — every single time.

This post is about why that's a problem, and how the /resolve-conflicts Claude Cowork skill fixes it — a first-class Claude skill you simply invoke in natural language, and Claude handles the entire workflow end to end.

🧩 The /resolve-conflicts skill is an installable Claude Cowork skill that automates your entire merge conflict workflow. The source code, shell script, and full documentation are open source on GitHub: github.com/pponali/claude_skills

The Real Pain Points Behind Merge Conflicts

Merge conflicts feel like a Git problem, but they're really a team coordination problem made visible. Here's what actually makes them brutal:

They always hit at the worst time. You finish a feature after days of work, go to merge, and suddenly you're debugging someone else's schema migration inside your application.yml. Context-switching mid-sprint to resolve config conflicts is a massive cognitive tax.

The same files conflict over and over. In any non-trivial project, you'll find the same suspects in your conflict list week after week: pom.xml, docker-compose.yml, *.properties, localization files, OpenAPI specs. These aren't complex logical conflicts — they're mechanical, repetitive, and boring. Yet they still demand your full attention.

Manual resolution is error-prone under pressure. When you're staring at a wall of ======= markers, it's easy to accidentally keep the wrong version, drop a dependency update, or smash together two configs in a way that silently breaks something. There's no guardrail — just you, your eyes, and your mouse.

The feedback loop is slow. You resolve conflicts, push, wait for CI, find out you introduced a bug in the config you just "fixed," fix it again, push again. The cycle can eat hours.

It doesn't scale with team size. On a small team, conflicts are annoying. On a team of 20+ engineers all merging into main frequently, they're a daily tax on every developer's time.

The Traditional Approach (And Why It Falls Short)

The standard workflow most of us follow looks like this:

git fetch origin
git merge origin/main
# ... open every conflicted file in VS Code ...
# ... manually choose ours / theirs / both ...
git add .
git commit -m "Merge branch 'main' into feature/my-thing"
git push

This works, but it has serious problems:

No consistency. Different developers make different choices for the same file types. One dev always keeps pom.xml from main; another always keeps the branch version. The merge history becomes unpredictable.
No documentation. The merge commit rarely explains why you resolved conflicts the way you did. Future you (and your teammates) have no idea.
No scalability. Every conflict requires a human to sit down and make individual decisions, even for files where the right answer is always the same.

Enter `/resolve-conflicts`: A Claude Cowork Skill That Does It All

The /resolve-conflicts skill is a Claude Cowork skill — meaning you don't run commands yourself. You just tell Claude what you want in plain English:

"Merge main into my branch and resolve conflicts"
"My PR shows conflicts — fix them"
"Sync my feature branch with origin/main"

Claude takes it from there. Under the hood it drives .claude/scripts/resolve-conflicts.sh — a shell script with codified heuristics for every file type in your project. The skill + script together are fully open source:

📦 github.com/pponali/claude_skills

The core idea: most conflicts in most projects follow predictable patterns. Once those patterns are encoded as a Claude skill, you never have to think about them again — just describe the problem and let Claude handle it.

Here's what Claude does behind the scenes when you invoke the skill:

# Step 1 — Claude runs a dry-run first and summarises what it found
.claude/scripts/resolve-conflicts.sh origin/main true

# Step 2 — After your confirmation, Claude runs for real
.claude/scripts/resolve-conflicts.sh origin/main false

Claude handles everything: stashing uncommitted changes, merging, resolving each conflict using the right heuristic, staging, creating an auditable commit, pushing, and optionally checking PR status via the gh CLI. You just review and confirm.

How the Resolution Heuristics Work

The script doesn't guess — it applies explicit, per-file-type rules:

File pattern	Strategy	Rationale
`pom.xml`, `*/pom.xml`	Keep branch (`--ours`)	Feature branch usually holds newer or WIP dependencies
`*.properties`	Keep branch	Branch has local/feature-specific config values
`.yaml` / `.yml`	Keep branch	Same reasoning as properties
`docker-compose.*`	Keep branch	Preserves the current service topology
`*.md`	Keep both (concatenated)	Docs from both sides are usually additive, not contradictory
`*.java`	Keep branch	Active feature work lives on the branch
`.js`, `.ts`, `*.tsx`	Keep branch	Same as Java
anything else	Keep branch + warning	Safe default; flagged for manual review

"Keep branch" means the HEAD side of the merge — your feature branch. The strategy is opinionated by design. If your project has different conventions, you update the script once, and every future merge follows the new rules automatically.

The Markdown strategy is particularly clever: instead of picking one side, it concatenates both. Documentation is almost always additive — two sections from different branches are usually both worth keeping, so the merge result includes both and a human can clean it up later without losing information.

The Dry-Run Is Your Best Friend

Before running for real, always do a dry run:

.claude/scripts/resolve-conflicts.sh origin/main true

The output tells you:

Which files have conflicts
Which rule the script will apply to each one
Any files in the "unknown" bucket (these get --ours by default and a warning logged)

This is the moment to catch surprises. If main bumped a critical version in pom.xml that your branch must absorb, you'll see it here. You can let the script handle everything else and manually fix just that one file afterwards.

Verify, Don't Assume

After the script runs, always check:

# Should show your merge commit
git log --oneline -3

# MUST be empty — any output here means unresolved conflicts
git diff --name-only --diff-filter=U

# Quick overview of what changed
git show HEAD --stat

If your project has a fast smoke test — mvn -q -DskipTests verify, npm run typecheck, docker compose config — run it now. Heuristic resolutions are fast but not infallible.

If you're using the gh CLI:

gh pr view <number> --json mergeable,mergeStateStatus

Note: GitHub takes 1–2 minutes to recompute mergeability after a push. Don't panic if it shows conflicts for a moment after you push.

When NOT to Use the Script

The script is great for mechanical conflicts, but there are cases where you need a human in the loop:

Core business logic in .java / .ts / .js files where both sides have unique, non-overlapping changes. The script will keep the branch version and silently drop main's changes. If both sides implemented different parts of the same feature, you need to merge them manually.

A critical dependency update in pom.xml that your branch must consume. The script keeps your branch version. After it runs, manually edit the file, git add, and git commit --amend --no-edit.

Files in the "unknown" bucket (*.sql, *.proto, *.kt, etc.). The script flags these but defaults to --ours. Open them, check if main's changes matter, resolve manually, then fold into the merge commit:

# After manually editing the file:
git add path/to/file.sql
git commit --amend --no-edit
git push --force-with-lease origin your-branch

The pattern that works best: let the script handle the 80% of mechanical conflicts, then manually patch the 20% that need actual reasoning. You get speed and correctness.

Real-World Payoff

Once your team adopts this workflow, a few things change:

Merge commits become consistent and auditable. The commit message documents which strategy was applied to which files. Six months from now, you can look at a merge commit and understand exactly what happened.

Conflict resolution stops being a senior-developer task. The rules are encoded in a script, not in someone's head. A junior developer can merge safely without needing to ask "should I keep ours or theirs for the YAML?".

Friday afternoon PRs stop being feared. When conflict resolution is one command instead of a half-hour of careful manual editing, you stop dreading the merge.

Getting Started: Install the Claude Skill

Everything — the skill definition, the shell script, and full documentation — is in the open source repo:

📦 github.com/pponali/claude_skills

# Add the script to your project
mkdir -p .claude/scripts
curl -o .claude/scripts/resolve-conflicts.sh \
  https://raw.githubusercontent.com/pponali/claude_skills/master/.claude/scripts/resolve-conflicts.sh
chmod +x .claude/scripts/resolve-conflicts.sh

Once installed, just open Claude in Cowork mode and describe the problem. Claude will:

Run pre-flight checks (detects if you're already mid-merge)
Do a dry run and summarise exactly which files it will touch and how
Ask for your confirmation before committing anything
Merge, resolve, commit, push — and report back

You're always in control. Claude handles the mechanical parts, you handle the judgment calls.

Running the script directly (without Claude) is also supported:

# Dry run first — always
.claude/scripts/resolve-conflicts.sh origin/main true

# Then for real
.claude/scripts/resolve-conflicts.sh origin/main false

# Merge a different branch
.claude/scripts/resolve-conflicts.sh origin/feat/payment false

The Full Script

Drop this into .claude/scripts/resolve-conflicts.sh in your repo and make it executable (chmod +x). It's self-contained — no external dependencies beyond bash, git, and optionally the gh CLI for PR status checks.

#!/usr/bin/env bash
# =============================================================================
# resolve-conflicts.sh
# Automated merge-conflict resolution with per-file-type heuristics.
#
# Usage:
#   .claude/scripts/resolve-conflicts.sh [target-branch] [dry-run]
#
# Arguments:
#   target-branch  Branch to merge in. Default: origin/main
#   dry-run        true|false. Default: false
#
# Examples:
#   .claude/scripts/resolve-conflicts.sh                          # merge origin/main, for real
#   .claude/scripts/resolve-conflicts.sh origin/main true        # dry-run first
#   .claude/scripts/resolve-conflicts.sh origin/feat/payment false
# =============================================================================

set -euo pipefail

TARGET_BRANCH="${1:-origin/main}"
DRY_RUN="${2:-false}"

# Colour helpers
RED='\033[0;31m'; YELLOW='\033[1;33m'; GREEN='\033[0;32m'; CYAN='\033[0;36m'; NC='\033[0m'
info()    { echo -e "${CYAN}[resolve-conflicts]${NC} $*"; }
success() { echo -e "${GREEN}[resolve-conflicts]${NC} $*"; }
warn()    { echo -e "${YELLOW}[resolve-conflicts] WARN:${NC} $*"; }
error()   { echo -e "${RED}[resolve-conflicts] ERROR:${NC} $*" >&2; }

# ---------------------------------------------------------------------------
# Pre-flight
# ---------------------------------------------------------------------------
if git rev-parse --verify MERGE_HEAD &>/dev/null; then
  error "Repo is already mid-merge (MERGE_HEAD exists)."
  error "Run 'git merge --abort' to cancel the previous merge, then retry."
  exit 1
fi

CURRENT_BRANCH="$(git rev-parse --abbrev-ref HEAD)"
info "Current branch : $CURRENT_BRANCH"
info "Target branch  : $TARGET_BRANCH"
info "Dry run        : $DRY_RUN"

info "Fetching origin..."
git fetch origin --quiet

# ---------------------------------------------------------------------------
# Stash any uncommitted changes
# ---------------------------------------------------------------------------
STASHED=false
if ! git diff --quiet || ! git diff --cached --quiet; then
  info "Stashing local changes..."
  git stash push -m "resolve-conflicts auto-stash $(date +%s)"
  STASHED=true
fi

# ---------------------------------------------------------------------------
# Attempt the merge
# ---------------------------------------------------------------------------
info "Merging $TARGET_BRANCH into $CURRENT_BRANCH..."
if git merge "$TARGET_BRANCH" --no-edit --no-commit 2>/dev/null; then
  success "Merge completed with no conflicts. Committing..."
  if [ "$DRY_RUN" = "false" ]; then
    git commit --no-edit -m "Merge $TARGET_BRANCH into $CURRENT_BRANCH (no conflicts)"
    git push origin "$CURRENT_BRANCH"
    success "Pushed."
  else
    git merge --abort 2>/dev/null || true
    info "[DRY RUN] No conflicts — merge would succeed cleanly."
  fi
  $STASHED && git stash pop || true
  exit 0
fi

CONFLICTED_FILES="$(git diff --name-only --diff-filter=U)"

if [ -z "$CONFLICTED_FILES" ]; then
  warn "Merge stopped but no conflict markers found. Check git status."
  git merge --abort 2>/dev/null || true
  $STASHED && git stash pop || true
  exit 1
fi

info "Conflicted files:"
echo "$CONFLICTED_FILES" | while read -r f; do echo "  - $f"; done

# ---------------------------------------------------------------------------
# Resolution heuristics
# ---------------------------------------------------------------------------
resolve_file() {
  local file="$1"
  local strategy="" reason=""

  case "$file" in
    pom.xml|*/pom.xml)
      strategy="ours";  reason="pom.xml — keep branch (feature deps)" ;;
    *.properties)
      strategy="ours";  reason="*.properties — keep branch (feature config)" ;;
    *.yaml|*.yml)
      strategy="ours";  reason="*.yaml/yml — keep branch (feature config)" ;;
    docker-compose*|*/docker-compose*)
      strategy="ours";  reason="docker-compose — keep branch (feature topology)" ;;
    *.md)
      strategy="union"; reason="*.md — keep both (documentation is additive)" ;;
    *.java)
      strategy="ours";  reason="*.java — keep branch (active feature work)" ;;
    *.js|*.ts|*.tsx|*.jsx)
      strategy="ours";  reason="*.js/ts — keep branch (active feature work)" ;;
    *)
      strategy="ours"
      reason="unknown type — defaulting to branch; MANUAL REVIEW RECOMMENDED"
      warn "No rule for: $file — keeping branch version. Please verify manually." ;;
  esac

  if [ "$DRY_RUN" = "true" ]; then
    info "[DRY RUN] $file → $strategy  ($reason)"
    return
  fi

  info "Resolving: $file → $strategy  ($reason)"

  if [ "$strategy" = "ours" ]; then
    git checkout --ours -- "$file"
    git add "$file"
  elif [ "$strategy" = "union" ]; then
    local ours theirs
    ours="$(git show :2:"$file" 2>/dev/null || true)"
    theirs="$(git show :3:"$file" 2>/dev/null || echo "")"
    { echo "$ours"; echo ""; echo "---"; echo "<!-- merged from $TARGET_BRANCH -->"; echo ""; echo "$theirs"; } > "$file"
    git add "$file"
  fi
}

while IFS= read -r file; do
  [ -n "$file" ] && resolve_file "$file"
done <<< "$CONFLICTED_FILES"

# ---------------------------------------------------------------------------
# Commit and push
# ---------------------------------------------------------------------------
if [ "$DRY_RUN" = "true" ]; then
  info "[DRY RUN] Complete. No files were changed."
  git merge --abort 2>/dev/null || true
  $STASHED && git stash pop || true
  exit 0
fi

STILL_CONFLICTED="$(git diff --name-only --diff-filter=U 2>/dev/null || true)"
if [ -n "$STILL_CONFLICTED" ]; then
  error "Some files are still unresolved — resolve manually, 'git add', then 'git commit'."
  echo "$STILL_CONFLICTED"
  $STASHED && git stash pop || true
  exit 1
fi

COMMIT_MSG="Merge $TARGET_BRANCH into $CURRENT_BRANCH (auto-resolved)

Heuristics applied:
$(echo "$CONFLICTED_FILES" | while read -r f; do echo "  - $f"; done)

Generated by resolve-conflicts.sh"

git commit -m "$COMMIT_MSG"
success "Merge commit created."

git push origin "$CURRENT_BRANCH"
success "Pushed to origin/$CURRENT_BRANCH."

if $STASHED; then
  info "Restoring stashed changes..."
  git stash pop || warn "Stash pop failed — run 'git stash list' to inspect."
fi

if command -v gh &>/dev/null; then
  info "Checking PR status (GitHub may take ~2 min to recompute)..."
  gh pr view --json mergeable,mergeStateStatus 2>/dev/null \
    | python3 -c "import json,sys; d=json.load(sys.stdin); print(f'  mergeable={d[\"mergeable\"]}  state={d[\"mergeStateStatus\"]}')" \
    || true
fi

success "Done. Run 'git log --oneline -3' to verify the merge commit."

Save it, make it executable, and you're ready:

mkdir -p .claude/scripts
# paste the script above into .claude/scripts/resolve-conflicts.sh
chmod +x .claude/scripts/resolve-conflicts.sh

Merge conflicts aren't going away. As long as multiple people work on the same codebase, there will be divergence. But the amount of manual, repetitive work they require is entirely within your control. Codify your team's conventions, automate the mechanics, and save the human judgment for the conflicts that actually need it.

Your future Friday self will thank you.

Circuit Breakers Under Stress: Anatomy of a Payment Cascade

pponali — Sun, 10 May 2026 14:10:46 +0000

A flash sale hit us at 10x baseline RPS. Within four minutes, our Payment Service circuit breaker tripped to OPEN, error rate climbed to 92%, and p99 latency on the payment path went from 200ms to 14.2 seconds. Here's the part nobody tells you on the conference circuit: the circuit breaker didn't fail. It worked exactly as designed. The failure was everywhere else.

This is a postmortem of what we saw, why Resilience4j's defaults weren't enough, and the four changes that made the next sale boring.

The setup

Standard Java microservices stack. Spring Cloud Gateway in front, JWT auth via Keycloak, Resilience4j wrapping every outbound call. Payment Service synchronously calls Stripe. Order Service synchronously calls Payment. PostgreSQL for orders, Redis for circuit breaker state, Kafka for the dead-letter queue.

Six services. Five circuit breakers. One very stressed thread pool.

What 10x RPS actually does

Baseline was around 1,000 RPS. The flash sale pushed us to 10,243. The edge layer absorbed it fine — NGINX did its job, the rate limiter degraded gracefully, the CDN cached anything cacheable. Spring Cloud Gateway routed cleanly.

The wheels came off at the Payment Service. Stripe's p99 latency under load climbed from a healthy 800ms to 14.2 seconds. That doesn't sound catastrophic until you do the math: every Payment thread now holds for ~14s instead of <1s. With a fixed thread pool, throughput collapses long before the breaker notices.

# What we had — Resilience4j defaults, lightly tuned
resilience4j.circuitbreaker:
  instances:
    paymentService:
      failureRateThreshold: 50
      slidingWindowSize: 100
      slidingWindowType: COUNT_BASED
      waitDurationInOpenState: 30s
      permittedNumberOfCallsInHalfOpenState: 10

A 50% failure threshold over 100 calls means the breaker waits for 50 failures before tripping. At 10x load with timeouts, that's roughly four minutes of users staring at spinners. By the time the breaker opened, the thread pool was already 98% saturated.

The cascade, step by step

The order matters:

Flash-sale spike hits the gateway at 10x RPS.
Order Service synchronously calls Payment for every checkout.
Stripe's p99 spikes to 14s under provider-side load.
Payment Service threads block on those timeouts.
failureRateThreshold=50% breached → Payment CB transitions to OPEN.
Subsequent calls fail-fast → fallback handler enqueues "deferred order" responses to Kafka.
Order Service's own CB drops to HALF-OPEN, probing with limited concurrency.
Bulkhead isolation prevents the cascade from reaching Inventory, Notifications, or User services.

Step 8 is the only reason this incident wasn't a full-platform outage. Without per-endpoint bulkheads, a slow Stripe would have eaten every thread in the gateway's pool, and User Service login requests would have queued behind dead Payment calls.

The state machine, practically

If you've only read the docs, the circuit breaker looks like a tidy three-state diagram. In production it's noisier:

// Resilience4j state transitions, simplified
CircuitBreaker cb = CircuitBreaker.of("paymentService", config);

cb.getEventPublisher()
  .onStateTransition(event -> {
      log.warn("CB {} : {} -> {}",
          event.getCircuitBreakerName(),
          event.getStateTransition().getFromState(),
          event.getStateTransition().getToState());
      meterRegistry.counter("cb.transition",
          "name", event.getCircuitBreakerName(),
          "to", event.getStateTransition().getToState().name()
      ).increment();
  });

That listener saved us during the postmortem. We could replay exactly when each breaker tripped, when probing started, and which trial calls failed. If you don't emit metrics on every state transition, you're flying blind.

The HALF-OPEN state is the dangerous one. Resilience4j permits a small number of trial calls; if any of them fail, you slam back to OPEN for another waitDuration. Set the trial pool too low and you'll never recover; set it too high and you'll hammer a still-broken downstream.

Four changes that fixed it

1. Tighter, faster breakers

We dropped the threshold and shrunk the window:

resilience4j.circuitbreaker:
  instances:
    paymentService:
      failureRateThreshold: 30          # was 50
      slowCallRateThreshold: 50          # NEW — slow calls also count
      slowCallDurationThreshold: 2s      # NEW
      slidingWindowSize: 20              # was 100
      minimumNumberOfCalls: 10
      waitDurationInOpenState: 15s       # was 30s
      permittedNumberOfCallsInHalfOpenState: 5

Two non-obvious knobs matter here. slowCallRateThreshold lets you trip on latency, not just errors — critical when a downstream is dying slowly rather than 500-ing. And the smaller window means the breaker reacts in seconds, not minutes.

2. Per-endpoint bulkheads

A single thread pool for "Payment Service" is too coarse. Split by downstream:

@Bean
public ThreadPoolBulkhead stripeBulkhead() {
    ThreadPoolBulkheadConfig config = ThreadPoolBulkheadConfig.custom()
        .maxThreadPoolSize(20)
        .coreThreadPoolSize(10)
        .queueCapacity(50)
        .keepAliveDuration(Duration.ofMillis(500))
        .build();
    return ThreadPoolBulkhead.of("stripe", config);
}

@Bean
public ThreadPoolBulkhead fraudBulkhead() {
    // Smaller — fraud is allowed to be slow, not allowed to starve payment
    return ThreadPoolBulkhead.of("fraud",
        ThreadPoolBulkheadConfig.custom()
            .maxThreadPoolSize(8)
            .coreThreadPoolSize(4)
            .build());
}

Now a slow fraud engine can't drain Stripe's threads, and vice versa. Bulkhead-per-dependency is more YAML, but it's the only way to guarantee isolation when one downstream misbehaves.

3. Async outbox + Kafka retry

The synchronous Order → Payment → Stripe chain was the real sin. We moved Payment to an outbox pattern: orders write a payment intent to Postgres in the same transaction, a relay publishes to Kafka, and a worker calls Stripe asynchronously. The user gets an immediate "order placed" response; the charge happens within seconds, with retries handled by the consumer.

@Transactional
public Order placeOrder(OrderRequest req) {
    Order order = orderRepo.save(Order.from(req));
    outboxRepo.save(new OutboxEvent(
        "payment.charge.requested",
        order.getId(),
        objectMapper.writeValueAsString(req.payment())
    ));
    return order;  // returns in <50ms regardless of Stripe latency
}

Decoupling time-of-order from time-of-charge means a 14-second Stripe doesn't translate to a 14-second user experience. It also gives us natural retry and dead-lettering through Kafka, instead of bolting retry logic onto every caller.

4. HPA on RPS and queue depth

The Payment Service was scaled on CPU, which is useless when threads are blocked on I/O. We swapped to a custom Prometheus metric — RPS plus Kafka consumer lag — and let the HPA add pods when the queue grew faster than it drained. CPU never crossed 40% during the incident; if we'd been watching the right signal, we'd have scaled out three minutes earlier.

What I'd tell past me

The circuit breaker is a fire alarm, not a fire suppression system. By the time it trips, you've already had a fire for a while. The real defenses are the things that stop the fire from starting: bulkhead isolation per downstream, slow-call detection, async boundaries on anything you don't fully control, and autoscaling on signals that actually correlate with load.

Resilience4j is excellent. The defaults are not your friend in production.

Takeaways

If you take three things from this:

Trip on latency, not just errors. slowCallRateThreshold is the most underused knob in Resilience4j.
One bulkhead per downstream, always. Coarse pools will betray you the moment two dependencies fail differently.
Synchronous chains across third-party APIs are tech debt. An outbox + queue is more code, but it's the difference between a postmortem and an incident report.

The next flash sale ran 12x baseline. Payment p99 stayed under 600ms. Nobody paged.

After the Skill Vault: 3 More Hidden Token Sinks in Claude Code

pponali — Fri, 08 May 2026 00:48:13 +0000

If you read my earlier post on the Skill Vault pattern, you know I cut Claude Code's per-session overhead by 96%. After living with it for a few weeks, I went looking for what was still eating tokens — and found three more sinks worth killing.

This is the follow-up: smaller wins individually, but together they shaved another ~5,000 tokens off every single session with zero capability lost.

Where the Tokens Were Still Hiding

After the vault, my baseline was around 51K tokens per session. I dug into the system prompt to see what remained:

Skill list (still): ~3K tokens
Project CLAUDE.md: ~2K tokens
claude-mem auto-injected timeline: ~2K tokens
Plugin hook reminders: ~1K tokens (some recurring per turn)

Three of these were either unnecessary or way overweight. Here's how I killed each.

Sink #1: A Bloated Root CLAUDE.md (~1.5K tokens)

CLAUDE.md files auto-load into every session that touches the repo. Mine had grown to 326 lines / 8 KB with quickstart instructions for every component:

Flutter dev commands
Backend npm scripts
React build steps
ML service Python setup
A duplicate gstack skill listing

The problem: I was loading every component's instructions on every turn, even when I was only working in one of them.

Fix: Hierarchical CLAUDE.md Files

Claude Code loads CLAUDE.md hierarchically — only the ones in your current working tree get pulled in. So instead of one fat root file, I split it:

khetisahayak/
├── CLAUDE.md                    # 55 lines — overview, ports, creds only
├── kheti_sahayak_app/CLAUDE.md  # Flutter details
├── frontend/CLAUDE.md           # React details
├── ml/CLAUDE.md                 # ML service details
└── kheti_sahayak_backend/CLAUDE.md  # already existed

The root now contains only:

Project overview (5 lines)
Service ports table
Test credentials
Cross-cutting auth + DB notes
Troubleshooting

Component-specific details only load when I'm actually working in that subdir.

Result: root CLAUDE.md trimmed from 326 → 55 lines (8 KB → 1.6 KB). ~1.5K tokens saved per session.

Sink #2: Plugin SessionStart Hooks Injecting "Helpful" Context

I use claude-mem for persistent memory across sessions. Genuinely useful. But it has a SessionStart hook that auto-injects a timeline of recent observations at the top of every conversation — about 50 entries, ~2K tokens:

S499 Indeed Auto-Apply — User asked how to automate job applications
S498 Indeed MCP Integration Query — clarifying JobSpy vs Apify
2337 12:33p ✅ systemd/install.sh — Backend Services Enabled
... 47 more lines

I almost never needed this auto-recall. When I want past context, I call mem-search explicitly.

Fix: Disable the Auto-Inject, Keep the Memory

The hook config lives at:

~/.claude/plugins/cache/thedotmack/claude-mem/<version>/hooks/hooks.json

The SessionStart array has three hooks. The third is the timeline injection:

{
  "type": "command",
  "command": "... node bun-runner.js worker-service.cjs hook claude-code context ..."
}

I removed just that one entry. The other two SessionStart hooks (install + worker-start) and the recording hooks (PostToolUse, Stop, SessionEnd) stay intact, so memory is still being captured. The MCP search server still works — I just have to ask for it.

# Always back up before editing plugin internals
cp hooks.json hooks.json.bak
# Remove the 3rd SessionStart hook (jq or manual edit)

Result: ~2K tokens saved per session. Memory still works on demand.

⚠️ Caveat: editing a file in ~/.claude/plugins/cache/ will be overwritten on plugin upgrade. For durability, mirror the change in your user-level ~/.claude/settings.json hooks block, or add a small post-upgrade re-patch script.

Sink #3: Round 2 of the Skill Vault (~1.4K tokens)

The original vault was a one-time bulk move. After several weeks of actual usage, I saw which skills I'd installed and never touched. The vault was overdue for a second pass.

Audit script (same as the first post, run again):

for f in ~/.claude/skills/*/SKILL.md; do
  dir=$(dirname "$f")
  name=$(basename "$dir")
  size=$(wc -c < "$f")
  echo "$size $name"
done | sort -rn | head -30

I ended up vaulting 27 more skills out of 73 actively loaded:

8 marketing skills (mkt-content, mkt-seo, mkt-social, etc.) — I do real marketing in a separate context
6 research skills (research, research-deep, research-report, etc.) — episodic, not daily
5 niche tools (obsidian-vault, make-pdf, pair-agent, setup-browser-cookies, open-gstack-browser)
4 design-heavy (design-consultation, design-html, design-shotgun, devex-review) — restored only when designing
3 plan reviews (plan-design-review, plan-devex-review, plan-tune)
1 interview prep (staff-engineer-interview) — used a few times last quarter, not weekly

Bulk move:

for s in mkt-content mkt-email mkt-growth mkt-pr mkt-review mkt-seo mkt-social cmo \
         research research-add-fields research-add-items research-deep research-report edit-article \
         staff-engineer-interview \
         obsidian-vault make-pdf pair-agent setup-browser-cookies open-gstack-browser \
         plan-design-review plan-devex-review plan-tune \
         design-consultation design-html design-shotgun devex-review; do
  mv ~/.claude/skills/$s ~/.claude/skills-vault/ 2>/dev/null
done

The skill-vault index skill from the original post still bridges everything — Claude knows where each skill lives and restores it on demand.

Result: 73 → 46 active skills. ~1.4K tokens saved.

The Combined Result

Fix	Tokens Saved (per session)
Sink #1 — CLAUDE.md trim + per-component split	~1.5K
Sink #2 — claude-mem timeline disabled	~2K
Sink #3 — Round 2 skill vault	~1.4K
Total	~4.9K

On top of the original 96% reduction from the Skill Vault, this is another solid bite. But honestly, the dollar value isn't the point.

Why This Matters Beyond Cost

Every token in your context is a token Claude has to attend over before generating its response. The bigger your prompt, the more diluted attention becomes on the actual task.

Big context ≠ better answers. Frequently it's the opposite. Targeted context wins.

The pattern across all three fixes is the same:

Audit what's auto-loaded vs. what's actually useful. You'll be surprised.
Move episodic content out of the always-on path and into on-demand access.
Trust the model to pull what it needs — when it does need the vaulted skill, the subdir's CLAUDE.md, or the memory search, it will reach for it.

Less ambient noise. Sharper signal.

Tips for Your Own Audit

Inspect, don't guess. wc -c your CLAUDE.md files. ls ~/.claude/skills/. Read your plugin hooks.json files line by line.
Hierarchy is free. Per-directory CLAUDE.md files cost nothing when you're not in that directory.
Plugin hooks are debt. Every SessionStart or UserPromptSubmit hook is a tax. Audit them by hand. Some are essential (auth, telemetry); some inject "context" that's just clutter.
Re-vault every few weeks. Usage patterns shift. Skills that were daily three months ago may be quarterly now. Yesterday's must-have is tomorrow's vault candidate.
Watch for per-turn taxes. A UserPromptSubmit hook costs N tokens every single turn. Even a small reminder block adds up fast in a long session.

Conclusion

The Skill Vault pattern is still the heaviest hitter. These three follow-ups are the long tail:

CLAUDE.md → split per component, slim the root.
Plugin hooks → audit auto-injected context. Disable what you don't need.
Skill vault → revisit it. Vault more.

Together: another ~5K tokens per session, zero capability lost.

When your context is tight, your model is sharp.

I'm Prakash Ponali, a Staff Engineer with 16+ years in enterprise eCommerce. Currently building Khetisahayak — a farming helper app for Telugu-speaking farmers in Andhra Pradesh. Find me on LinkedIn.

How I Cut Claude Code Token Consumption by 96% with the Skill Vault Pattern

pponali — Sun, 19 Apr 2026 07:45:04 +0000

The Problem: 181 Skills Burning 1.18 Million Tokens Per Session

I'm a power user of Claude Code — Anthropic's CLI for AI-assisted development. Over weeks of installing skill packs from GitHub repos, I accumulated 181 skills from multiple sources:

gstack agents (QA, design, deploy, monitoring)
marketingskills by Corey Haines (36 CRO/SEO/copywriting skills)
wondelai/skills (42 product/engineering frameworks)
superpowers by obra (14 dev methodology skills)
claude-mem (persistent memory plugin)
Deep-Research-skills (structured research workflows)
Custom skills I built myself

Sounds great, right? More skills = more capability.

Wrong. Every new conversation, Claude Code injects ALL skill descriptions into the system prompt. With 181 skills, that's approximately 1.18 million tokens of overhead per session — before I even type my first message.

Tokens were burning like a wildfire. Every task was expensive. Context windows were filling up fast.

The Discovery: Measuring the Actual Cost

I ran a simple audit to see exactly what was happening:

# Count total SKILL.md bytes across all skills
total=0
for f in ~/.claude/skills/*/SKILL.md; do
  size=$(wc -c < "$f" 2>/dev/null)
  total=$((total + size))
done
echo "Total bytes: $total"
echo "Approx tokens: $((total / 4))"

Result: 4.7MB of SKILL.md files = ~1.18 million tokens.

The top offenders were massive:

Skill	Size	Tokens
ship (gstack)	130KB	~32K
plan-ceo-review	112KB	~28K
office-hours	101KB	~25K
seedance-15-real-estate	95KB	~24K
plan-devex-review	93KB	~23K

15 Seedance video skills alone consumed ~265K tokens. I used them maybe once a month.

The Solution: The Skill Vault Pattern

The idea is simple:

Move rarely-used skills to a vault directory (out of auto-load)
Keep a lightweight index skill that tells Claude what's available
Claude restores skills on-demand when your request matches one
Optionally move it back after the task

Step 1: Create the Vault

mkdir -p ~/.claude/skills-vault

Step 2: Audit Your Skills by Usage Frequency

Sort all skills by file size to find the biggest offenders:

for f in ~/.claude/skills/*/SKILL.md; do
  dir=$(dirname "$f")
  name=$(basename "$dir")
  size=$(wc -c < "$f")
  echo "$size $name"
done | sort -rn | head -30

Then categorize them:

Tier 1 (Daily use): Keep active — your core dev workflow skills
Tier 2 (Project-specific): Keep active — skills tied to current projects
Tier 3 (Occasional): Vault — heavy skills used weekly/monthly
Tier 4 (Rare): Vault — frameworks and reference skills

Step 3: Move Skills to the Vault

# Move video generation skills (rarely used)
mv ~/.claude/skills/seedance-* ~/.claude/skills-vault/

# Move heavy plan review skills
mv ~/.claude/skills/{plan-ceo-review,plan-eng-review,plan-design-review} \
   ~/.claude/skills-vault/

# Move framework/reference skills
mv ~/.claude/skills/{clean-architecture,domain-driven-design,system-design} \
   ~/.claude/skills-vault/

# Move marketing skills you don't use daily
mv ~/.claude/skills/{copywriting,seo-audit,paid-ads,cold-email} \
   ~/.claude/skills-vault/

Step 4: Create the Index Skill (The Key Ingredient)

This is what makes the pattern work. Create a lightweight skill that acts as a lookup table for Claude:

mkdir -p ~/.claude/skills/skill-vault

Create ~/.claude/skills/skill-vault/SKILL.md:

---
name: skill-vault
description: Index of vaulted skills at ~/.claude/skills-vault/.
  When the user's request matches a vaulted skill, restore it with
  mv ~/.claude/skills-vault/<name> ~/.claude/skills/ then use it.
  Use when user asks about design, SEO, CRO, copywriting,
  architecture patterns, security audit, deployment, video
  generation, or any topic not covered by active skills.
---

## Skill Vault

Skills stored in `~/.claude/skills-vault/` to save tokens.
When a user request matches one, restore it:

mv ~/.claude/skills-vault/<skill-name> ~/.claude/skills/

Then invoke it normally. After the task, optionally move back:

mv ~/.claude/skills/<skill-name> ~/.claude/skills-vault/

## Vaulted Skills Index

### Design & UI
- `design-review` — Visual QA, spacing/hierarchy fixes
- `design-html` — Production HTML/CSS from mockups
- `design-shotgun` — Generate multiple design variants
- `top-design` — Awwwards-quality web experiences

### Engineering Frameworks
- `clean-architecture` — Dependency rule, ports/adapters
- `domain-driven-design` — Bounded contexts, aggregates
- `system-design` — Distributed systems, scaling
- `refactoring-patterns` — Extract method, code smells

### DevOps & Monitoring
- `land-and-deploy` — Merge, CI, verify production
- `canary` — Post-deploy monitoring
- `cso` — Security audit (OWASP, STRIDE)

### Marketing
- `copywriting` — Marketing copy for any page
- `seo-audit` — Technical SEO audit
- `paid-ads` — Google/Meta/LinkedIn campaigns

(... add all your vaulted skills here ...)

This index costs only ~1.5K tokens but gives Claude awareness of all 139 vaulted skills.

The Results

Metric	Before	After	Reduction
Active skills	181	43	76% fewer
Tokens per session	~1.18M	~51K	96%
Vaulted (on-demand)	0	139	—
Capability lost	—	None	0%

96% token reduction with zero capability loss.

How It Works at Runtime

You: "audit my design for visual issues"

Claude thinks:
  1. No active skill matches "design audit"
  2. skill-vault index matches: design-review
  3. Run: mv ~/.claude/skills-vault/design-review ~/.claude/skills/
  4. Now use design-review skill normally
  5. Task complete

Claude reads the vault index, finds the right skill, restores it with a single mv command, and proceeds normally. The user experience is seamless.

My Final Active Skill Set (43 Skills)

Here's what I kept always-active:

Core Dev Workflow (Superpowers):
ship, qa, browse, review, investigate, writing-plans, executing-plans, brainstorming, subagent-driven-development, systematic-debugging, test-driven-development, verification-before-completion

Project-Specific:
ecommerce-architect, staff-engineer-interview, claude-api-patterns, claude-code-mastery, mcp-server-development

Marketing (Khetisahayak):
cmo, mkt-content, mkt-seo, mkt-social, mkt-growth, mkt-email, mkt-pr, mkt-review

Research:
research, research-deep, research-report

The Vault Index:
skill-vault (the 1.5K token index that knows about 139 other skills)

Tips for Your Own Vault

Audit first. Run the size audit script before moving anything. You might be surprised which skills are the heaviest.
Keep your daily drivers active. Don't vault skills you use every session. The restore step adds a small delay.
Group by category. Makes it easy to restore a whole category:

   mv ~/.claude/skills-vault/seedance-* ~/.claude/skills/

Update the index when you add new skills to the vault.
Restore everything if you need full power for a complex session:

   mv ~/.claude/skills-vault/* ~/.claude/skills/

Where to Find Great Skills

Here are the skill repos I installed from:

marketingskills — 36 marketing skills by Corey Haines
wondelai/skills — 42 product/engineering framework skills
obra/superpowers — Dev methodology (TDD, planning, subagents)
Deep-Research-skills — Structured research workflows
claude-mem — Persistent memory across sessions

Installing is simple — symlink into ~/.claude/skills/:

git clone https://github.com/coreyhaines31/marketingskills.git
for skill_dir in marketingskills/skills/*/; do
  ln -s "$(pwd)/$skill_dir" ~/.claude/skills/$(basename "$skill_dir")
done

Then vault what you don't need daily.

Conclusion

The Skill Vault pattern is dead simple:

~/.claude/skills/ = active skills (loaded every turn)
~/.claude/skills-vault/ = dormant skills (restored on demand)
skill-vault/SKILL.md = lightweight index that bridges the two

If you're running more than 50 skills in Claude Code, you're probably burning hundreds of thousands of unnecessary tokens per session. The vault pattern gives you the full arsenal without the cost.

96% fewer tokens. Zero lost capability. One mv command away.

Web Topic Analysis Report - 2025-07-19

pponali — Sat, 19 Jul 2025 14:53:45 +0000

Web Topic Analysis Report - 2025-07-19

By AI Content Generator on July 19, 2025

Tags: web_analysis, tech_trends, ai_analysis

Web Topic Analysis Report

Workflow ID: web_topic_analysis_20250719_145337
Generated: 2025-07-19T14:53:37.277540

No analysis results available.

DEV Community: pponali

I Ran a Health Check on My Claude Code Setup — Here's What Was Actually Slowing It Down

Why bother auditing a CLI tool's config

What the audit actually checks

What was actually wrong

The hook that was eating 12 seconds a turn

What I didn't touch, and why

The takeaway

We Audited Our Claude Code Setup Against Anthropic's Own Context-Engineering Rules — Here's What We Found

The question that started this

What the blog post actually says

What we found when we actually measured it

The fix

The mistake worth admitting

Verifying the automated version wasn't just automating the same mistake

What this actually bought us

The generalizable lesson

From Monolith to 23 Microservices: A Strangler-Fig Migration

Strangler-fig, not big-bang

One front door: the API Gateway

Finding each other without hardcoded IPs

Not everything needs to be synchronous

Observability isn't optional past a certain scale

Where the AI actually lives

What I'd actually tell you

Scoring AI Agents: Deterministic Metrics + an LLM Judge

Deterministic first, LLM second

The agent contract is dead simple

Five metrics, one threshold gate

The LLM judge, when correctness isn't enough

Closing the loop: the prompts improve themselves

What I'd tell my past self

I built a Claude Code skill that discovers which automations to build — by mining my own work

The problem: repeated manual work is invisible

What distill-workflows does

The architecture

It found real work — on itself

How it's built

What's next

I tried to run Google Antigravity on an arm64 VM. It did not go well.

TL;DR

The setup

Round 1: qemu-user-static

Round 2: FEX-Emu

Round 3: there is no round 3

The actual answer

What it cost

Lessons

I shipped my first agentic workflow on GitHub Actions — 4 AI reviewers on every PR

The two files that do everything

1. The trigger

2. The sequence — five jobs, one DAG

3. The flow inside one review job

The Python script — one file, four personas

4. The flow inside the test-execution job

5. The gotchas (and the 429 in that screenshot)

Why I built it this way

The files, in full

Stop Wrestling with Merge Conflicts: Automate the Whole Workflow

The Real Pain Points Behind Merge Conflicts

The Traditional Approach (And Why It Falls Short)

Enter /resolve-conflicts: A Claude Cowork Skill That Does It All

How the Resolution Heuristics Work

The Dry-Run Is Your Best Friend

Verify, Don't Assume

When NOT to Use the Script

Real-World Payoff

Getting Started: Install the Claude Skill

The Full Script

Circuit Breakers Under Stress: Anatomy of a Payment Cascade

The setup

What 10x RPS actually does

The cascade, step by step

The state machine, practically

Four changes that fixed it

1. Tighter, faster breakers

2. Per-endpoint bulkheads

3. Async outbox + Kafka retry

4. HPA on RPS and queue depth

What I'd tell past me

What `distill-workflows` does

Enter `/resolve-conflicts`: A Claude Cowork Skill That Does It All