Claude Code
Hands-on articles for the Claude Code CLI — installation, CLAUDE.md design, subagents, hooks, CI integration, and fixes for common errors.
If You Wrote MCP Allow Rules as Just `mcp__servername` — Three Lines to Recheck After v2.1.299
Claude Code v2.1.299 changed MCP allow rules to match only the server they name. Here is how to audit older entries in settings.json, with a short Python script that does it.
I Added the allow Rule and the Prompt Still Appears — Reading Six Layers from /permissions
When an allow rule is in your settings and the same approval prompt keeps coming back, something else decided first. Starting from what /permissions shows, here are six layers you can verify against the official permissions docs: ask and deny precedence, where settings.local.json is read, Cowork's shell tool, and more.
The Hook That Was Meant to Guard My Japanese Folder Never Blocked Anything — Python Was Reading stdin as cp932
A PreToolUse hook guarding folders like 経理 or 議事録 silently lets edits through when Python's stdin defaults to cp932. How I reproduced it, the three-line fix, and one command to check your own hooks.
I Set onFailure to block, and the Docs' rm -rf Guard Still Let Everything Through Without jq
When a PreToolUse guard hook fails, does the action go ahead or stop? The docs' own rm -rf example exits 0 and waves everything through when jq is missing. Ten failure modes run for real, the fix, and a script that finds fail-open guards in settings.json.
Grep's First 250 Lines Touched Only 42 of the 183 Files That Matched
Searching an article repository for the word hook returned 1,312 lines across 183 files. ripgrep, git grep and grep all finished in 11 to 35 ms, so speed was never the issue. Output size and ordering were. A script that estimates what a 250-line cutoff will miss, plus a search order backed by measurements.
The Same Approval Prompt for 'cd, git add, git commit' Every Time — Following It to a Design Choice, Not a Missing Setting
With a compound command like cd /path && git add && git commit, Claude Code keeps asking for approval even with allow rules in place. Reading the official permissions page next to a GitHub report shows that cd combined with git prompts by design. Here is how to tell, in what order to check, and four ways to cut the prompts.
After Moving to SPM, My App Died the Moment It Launched — Reading One dyld Line with Claude Code
Right after moving from CocoaPods to Swift Package Manager, the build passed but the app died on launch. Here is how I traced one dyld line to its cause, the fix, and how to verify it.
I Wrote "I'll Do the Commits" in CLAUDE.md. The Next Morning git log Had One More Line.
When Claude Code commits despite being told not to: undo with git reset --soft, then stop it physically with permissions.deny plus a PreToolUse hook. Covers the git -c form that deny rules let through, and how to test the hook without starting Claude Code.
Two Default-Model Changes Haven't Reached Claude Code's Stable Channel Yet
This morning, Claude Code's stable channel sat 6 releases and 10 days behind latest. A small standard-library Python script that counts the gap in real, published releases instead of version arithmetic, and lists what hasn't arrived yet with a headline for each.
The Week Opus 5.5 Became the Default, I Counted the Places I'd Left as Aliases
Claude Code 2.1.280 made Opus 5.5 the default Opus and moved Pro's default from Sonnet to Opus. Before touching a single setting, I checked three things: what the alias resolves to, whether a saved /effort carries over, and what $0.20 cache reads do to a monthly estimate. Scripts included.
Taking Inventory of Worktrees That Were Supposed to Be Gone
Isolated worktrees my subagents created were never folded away. Here is what I measured in git 2.34.1 about when remove succeeds, the branches that outlive the trees, the 12 MB per-tree difference, and how I decide who owns cleanup.
I Was Paying for Pro and Still Getting Billed by the Console
Your subscription and your API usage are two separate ledgers, and Claude Code will happily run on either one. Which credential wins is decided by a precedence list where your login sits dead last. Here is how to read status, and why unattended runs answer differently.
My overnight crawl never came back, and the reason was that WebFetch had no ceiling on how long it would wait
Claude Code v2.1.268 gives WebFetch a 300-second deadline. Here is how an unattended run stalls on a server that never closes its response, why CLAUDE_CODE_WEBFETCH_DEADLINE_MS=0 does not mean 'do not wait', and how I now place two separate ceilings.
inferenceGatewayHeaders still works today. At noon on October 7 it falls back to a default
I read the deprecation notice that started appearing on September 10 as a spelling cleanup. After the cut-off, the old names are not ignored — they fall back to a fail-closed value or a default. Here is the old-to-new map and a script that audits your config in one pass.
When Every Request Fails With Not signed in to the Cloud gateway, Check the Version Before the Config
A Claude Code 2.1.265 regression broke every request for gateway and proxy setups. I use it as an excuse to build a small snapshot of the auth input surface, so the next time something breaks you can tell config from version in seconds.
One plugin.json turns a shelf of skills into something you can switch off as a group
When I sorted my skills by what work they belong to, the set I open almost daily turned out to be 5 percent of the total. Here is how I dropped a .claude-plugin/plugin.json into each group so I could switch a whole shelf off, plus the two loading rules I tripped over on the way.
I counted 42 skills on my shelf, and four of them were just a note saying they had moved
Claude Code v2.1.261 added /skill-doctor. Before running it I counted my own skill shelf from the files, found four tombstones, and learned that the obvious awk one-liner for spotting duplicate plugin names quietly reports skills that are not duplicates at all.
My deny rule was watching a filename, not the routes that reach it
One line in deny let several other spellings of the same file walk right past. Here is the small matrix I build to list every route to a protected file, and how I re-check it on upgrade day.
The ~/.claude.json Rollback Is Fixed in v2.1.259. Putting Back What It Erased Is Still Your Job
Concurrent sessions used to silently roll back each other's ~/.claude.json changes. v2.1.259 fixed that, but nothing restores the trust settings and MCP servers you already lost. Here is how I find and rebuild them, with a small key-path diff script.
The One File I Keep Out of Claude Code's Reach: project.pbxproj
With Xcode project files, the breakage that still opens costs far more than the breakage that refuses to open. Here is what I measured before moving every edit behind a script, and where the line sits today.
Aligning Log Timezones at Display Time, or Fixing Them at Write Time
AdMob, the store reports, and my own logs each ended the day at a different moment. Here is how I went back and forth between display-side and write-side timezone handling, and what I settled on.
Two hooks that record every model switch and stop the ones you never agreed to
Build a PostModelSwitch hook that logs every model change and a PreModelSwitch hook that blocks unapproved switches during unattended runs. Complete scripts, measured timings, and the reason the two jobs must stay separate.
Drop the quotes on a heredoc and the prices in your log quietly change
An unquoted heredoc runs the variables and backticks inside its body. Here are the four ways my log got rewritten, how the three quoting forms compare, a safe placeholder-and-sed pattern, and a small script for auditing what you already have.
Once I passed a dozen MCP servers, I stopped trusting the startup list
Only some of the servers that say connection failed at startup are ones you can actually fix. Here is a probe that separates no-response, launch failure, and protocol rejection, measured across a 14-server fleet where sequential 22.03s became parallel 5.09s, and where trimming the deadline quietly turned healthy servers into failures.
The Same Announcement Reads as '+25%' and as 'a 17% Cut' — Checking the Math on Claude Code's September 14 Weekly Limit Change
From September 14, Claude Code's weekly limit becomes a permanent +25% over the pre-promo baseline. Here is why +25% and a 17% cut are the same change, and how to check your own exposure with /usage and a status line script.
Half of My Scheduled Runs Vanished Without a Single Error
A batch job set to run twice a day was only firing once. No errors, no failure alerts. Here is how to expand your own schedule, count expected runs, and reconcile them against execution records to catch silent misses.
Your Config Asks for effort xhigh With Thinking Off, and It Now Quietly Runs at high
Disabling thinking while asking for effort xhigh or max returns a 400. That failure now degrades silently to high instead, so here is a small preflight that catches the mismatch before you send the request.
A small script that catches invisible characters in plugin names before you install
Control characters and zero-width characters hiding in plugin or skill names are invisible in a terminal listing. I built six deliberately confusing names, compared what ls actually shows, and wrote a short check you can run before installing anything — plus an honest note on what that check misses.
Don't let your verification script's full output flow back through a hook
The check was working the whole time. The conversation was what ran out of room. Measured side by side: 58 bytes from one scan of 833 files, 42KB from another. Which paths actually reach the model, and how to enforce a budget on them.
Curating the /model picker with modelPicker, and what replacing the lineup hides
Claude Code v2.1.242 added modelPicker, which lets you write the /model lineup yourself. Here is how appending differs from replacing, why project settings are ignored, and where it quietly narrows what availableModels allows.
Trusting the allow rules in your repo, or moving them to the environment
On disposable machines, the permissions.allow rules committed to your repo are dropped while the workspace waits to be trusted. Here is what gets dropped and what survives on 2.1.246, where each kind of rule belongs, and a preflight that catches the gap before a run starts.
I decide the prompt cache TTL by where I come back to, not how long I was away
Claude Code v2.1.242 added promptCacheTtl and subagentPromptCacheTtl. Whether the one-hour cache pays off depends on returning to the same directory and the same git state, not on how long the break was. Here is the order I check things in.
A One-Letter Typo in settings.json Is Ignored Without a Single Warning
I diffed claude doctor output between a settings.json with misspelled keys and a correct one. There was no difference at all. Here is what actually gets validated, what slips through, and a small check that catches typos before they cost you a day.
One Space in a Folder Name Turned 80 Checks Into Zero
An inspection loop reported 80 files checked and 0 readable. The files were fine. Here is how word splitting turns path fragments into real directories, measured side by side, plus the count assertion I now put in front of every delete-heavy batch.
The same skill lived in two places, and only one copy still had its files
Two scopes held skills with identical names. The SKILL.md files matched down to the sha256, yet one copy was missing the files its own body points to. Here is how I scanned 66 skills and rewrote the detector three times to get from four hits to two real ones.
Handing a long job to another session — and the completion marker for when the notification never arrives
How to use notify_when_idle to hear when another Claude Code session finishes, and a small completion marker that keeps you from waiting forever when the notification is dropped.
Switching to headersHelper in Claude Code broke auth for project-scoped catalogs only
Moving a private plugin catalog to headersHelper worked at user scope and failed under the project directory. The cause was credential non-inheritance. Here are two working helpers, measured execution costs, and what unattended runs need.
Adding ANTHROPIC_DEFAULT_MODEL Changes Nothing While ANTHROPIC_MODEL Is Still Set
ANTHROPIC_DEFAULT_MODEL, added in v2.1.236, is not a replacement for ANTHROPIC_MODEL. Here is how the two differ, plus a Python script that lists every place a model can be pinned.
My read-deny rules never reached inside the folder I had allowed
An audit of how far permissions.deny Read rules actually reach in a working tree where secrets and source code live side by side, with a script you can run today.
Take Inventory of What You Allowed with Don't Ask Again in Claude Code
After clicking Don't ask again a few dozen times, can you still explain what you approved? Here is a script that counts your current rules, plus a way to rebuild permissions from the smallest possible set.