Claude Code
Hands-on articles for the Claude Code CLI — installation, CLAUDE.md design, subagents, hooks, CI integration, and fixes for common errors.
The Biggest Section in Your SKILL.md Is Usually the One to Keep
A skill I run every week cost about 10K tokens just to load. Measuring it section by section showed why the largest block was the one I had to leave in place, and what splitting by reach actually saved.
Fixing the Code Doesn't Evict a Broken Page From the Edge Cache
I shipped a fix and the broken page kept serving. The problem was not the code but the edge cache, which had stored a broken HTML response because the store decision looked only at the status code. Here is the integrity guard I now run before every cache write, and the thresholds I had to tune in production.
Choosing a WebFetch Cache TTL That Fits the Way You Research
Claude Code lets you tune the WebFetch URL cache TTL. Here is how to see the shape of your own research sessions with a tiny observation server, then trade fetch count against freshness with numbers instead of guesswork.
Now that forking is the default, review agents are the ones I still call by name
Subagent forking became the default, so delegated work now inherits the parent conversation. Work can inherit context. Judgment cannot. Here is how I declare that boundary in the repository and catch it drifting.
A Runaway Build Dies Very Differently Under cgroup Than Under ulimit
Claude Code v2.1.233 added opt-in memory cgroup support for Bash tool commands on Linux. Capping virtual address space with ulimit -v and capping physical memory with a cgroup produce completely different failures — and only one of them lets your Node build start at all.
Tracking Multi-Step Work in Claude Code Now That the Todo Tools Are Off by Default
Since Claude Code v2.1.233, TodoWrite and the Task tools are left out on the newer models. Here are the three branches to check before you set the opt-in variable, the PostToolUse ledger I put in their place, and the measured point where that ledger quietly corrupts under parallel agents.
If You Walk Away While Claude Code Is Running, Turn On Remote Control First
Hand off a long task, step out, and you often come back to a session that stalled at the very first approval prompt. Remote Control lets you reach the Claude Code session running on your own machine from your phone or a browser. Here is how to set it up and what to know before you rely on it.
One generated file outweighed all 70 hand-written source files, so I redrew what Claude Code may read
I profiled a repository I actually run to see which areas consume the most context. Here is what I found, the deny rules I settled on, how search selectivity changes the math, and the options I considered but rejected.
When Paying Users Still See Ads: Collapsing the Ad-Free Check Into One Place
A user who paid to remove ads still sees them. The cause is rarely a missing flag — it is a check that lives in too many places. Here is how I inventoried every ad call with Claude Code and folded the decision into a single gate.
The Same rm -rf Was Recoverable in Ten Places and Unrecoverable in Five — Measuring Reversibility Before Auto Mode Becomes the Default
Auto mode became the default on Pro, Max and Team on August 14. It stops on operations judged irreversible, destructive, or outward-facing — but reversibility turned out to be a property of state, not of commands. Here is the probe and the measurements.
One Transient 401 Replaced My Long-Lived Token — Giving Credentials a Provenance Field
A shared credential file can lose its long-lived token to a single transient 401. I injected exactly one 401 into a 24-worker fleet, measured the blast radius, and compared a provenance guard against full isolation.
Same Content, Different SHA-256: Making Pinned Plugin Archives Reproducible
Plugins can now be installed from an HTTPS zip with an optional SHA-256 pin. Building the same tree twice produced archives that differed in 50 bytes out of 22,669 and broke the pin every time. Here is the byte-level measurement and a packaging recipe that produced an identical hash 20 times out of 20.
The Write Your Permission Mode Never Stops — Auditing an Agent-Scoped PreToolUse Gate Across 150 Payloads
Workflow subagents auto-approve file edits regardless of your session permission mode. I measured the remaining boundary — an agent_id-scoped PreToolUse hook — across 150 payloads, found 54 silent pass-throughs, and rebuilt it to fail closed.
The Skill Call That Returned Nothing — Pinning Down Name Resolution Before an Unattended Run
A skill whose name collides with a built-in terminal command may never resolve in a non-interactive session. Here is a preflight that builds the effective-name table before launch, plus the measured run where the checker itself silently skipped two entries.
Passing the Request, Not the Secret — Where Sandbox Credential Masking Works and Where Substitution Breaks
Claude Code's sandbox credential masking lets processes read sentinel values while a proxy swaps in the real secret at send time. I rebuilt it as a minimal proxy and measured which auth schemes survive the swap, which break, what happens when the secret rides in the body, and where chunked framing makes the substitution miss entirely.
Tightening Filesystem Isolation Separately from the Network — Collect the Paths, Then Squeeze the Write Surface
Claude Code v2.1.216 lets you control filesystem isolation independently from network isolation. Before tightening anything, I traced what a real job actually touches, split reads from writes, and measured how stable the path set is across repeated runs. The numbers changed how I wrote the allowlist.
Existence Checks Pass, Writes Fail — Probing Capabilities Before an Unattended Run
A directory existing and a directory being writable are two different facts. Measured results from five broken-environment cases, why static clues cannot predict the worst of them, and a capability-probe preflight for unattended Claude Code runs.
Resuming After a Budget Stop: What 36 Enumerated Stop Points Taught Me
A budget cap that halts a headless run is neither success nor failure. I enumerated every stop point, measured resume integrity and total spend, and ended up changing what the cap applies to.
You Added a Second Working Root — Now Ask How Far Your Ignore Rules and Deny Patterns Actually Reach
Adding a working root mid-session does not carry your ignore rules or deny patterns with it. Measured evidence from git check-ignore and a three-way matcher comparison, plus the scope-delta audit script I now run from the DirectoryAdded hook.
The MCP Server Connects Fine and Still Hands Back Zero Tools — Catching Silent Capability Drift with a Tool Manifest Diff
A missing credential does not break the MCP handshake. initialize succeeds, tools/list succeeds, and the array comes back empty. Here is the measured behaviour, and a preflight that locks the expected tool surface and fails closed before the agent ever starts.
Whose Environment Expands That Variable? Fingerprinting Your Effective Managed MCP Policy
Variable references in the Managed MCP allowlist and denylist now resolve from the startup environment and the managed-settings env block. I rebuilt both resolution orders locally to see where verdicts diverge, then wrote a preflight check that reduces the effective policy to a comparable fingerprint.
Locking down Claude Code sandbox egress with strictAllowlist
Tightening automation egress with strictAllowlist in Claude Code v2.1.219, plus measured failure timings that tell a policy deny from DNS and real outages, and three defects that made my own recon scripts return nothing.
A Committed Symlink That Points Outside the Worktree — Auditing Repos Before You Let AI Spin Up Parallel Trees
Claude Code 2.1.212 fixed a bug where a committed symlink under .claude/worktrees could be followed during worktree creation and write outside the repo. The patch closes the following side. Here is an audit script for the committed side, plus a quarantine workflow.
I Could No Longer Remember What I'd Changed in Auto Mode — Where claude auto-mode reset Fits In
Running nightly automation for weeks, I kept nudging my auto-mode settings one at a time. One morning a small oddity made me realize I could not recall what I had changed. Here is how I rebuilt my configuration around claude auto-mode reset as a known-good baseline, from a solo developer's field notes.
I Stopped the Headless Claude Code Job, but the Build Kept Running — Designing Teardown Around exit 143
In headless mode, a SIGTERM received while Claude Code was mid-Bash used to orphan the command's process tree. The 2.1.212 fix changes that to a clean exit 143. Here is how to redesign your supervisor and cleanup around that contract.
I Believed Plan Mode Only Read — Replacing That Belief With Machinery
Claude Code 2.1.212 fixed a bug where plan mode ran file-modifying Bash commands without the permission prompt or the SDK canUseTool callback. Here is what could happen while that assumption was broken, how to verify your own setup, and how to stop leaning on a mode name for safety.
Branch with /fork, Delegate with /subtask — Two Commands That Traded Jobs
In Claude Code 2.1.212, /fork now clones your conversation into a background session, and in-session subagents moved to /subtask. Here is how I decide between them, and the budgets worth setting before you start branching freely.
The MCP Server I Declared Vanished from the List — Designing Config for a Namespace You Share with the Vendor
When a vendor reserves an MCP server name, your .mcp.json declaration goes quiet instead of failing. Here is the preflight check and prefix convention I use to turn that silent gap into a loud stop before an unattended run.
The String I Approved Wasn't the String I Read — Testing a Relayed Permission Prompt with Deceptive Characters
I pushed bidi overrides and zero-width characters through my own approval relay. NFKC normalization caught 0%. Here is why, and the implementation that catches 100% with zero false positives.
My Nightly Subagents Ran, and I Couldn't Retrace Them — Trimming the Logs That --forward-subagent-text Unleashed
Subagent text and thinking can now flow into stream-json output, and unattended log volume climbs sharply with it. Here are measured numbers, a three-tier retention filter that keeps only what postmortems need, and a correlation ID design that survives missing fields.
The Morning My Table Ended in "… 2,847 more rows" — Separating Render Caps from Token Cost in Tool Output
Claude Code 2.1.209 caps markdown tables at 200 rows plus a remainder count. Only the rendering is capped — the model still receives every row. Here is how to measure the gap and redesign tool output around aggregates.
The Permission Rules You Added for Safety Are Taxing Every Turn — Auditing the Ruleset Without Loosening It
Version 2.1.209 fixed the per-turn slowdown from large deny/ask rulesets, but the design debt in your rules is still yours. Here are the audit scripts, a shadowing detector, a turn-timing harness, and how to fold enumerated rules into prefix rules safely.
Your Overnight Session Wakes Up at 3GB — Four Places Memory Piles Up, and How to Tell Them Apart
The Claude Code process I left running overnight had grown to 3.4GB of resident memory by morning. Here are the four accumulation sources closed in 2.1.209, how to separate what's left in your own setup by sampling RSS slope, and a watchdog pattern that folds a session before it hurts.
Switching Claude Code to Plain-Text Rendering — Three Ways In, and What Your Logs Actually Weigh
I opened last night's Claude Code log and found the same spinner line stacked dozens of times. Here are the three ways to turn on screen reader mode, a short script that measures what escape sequences and redraws really cost you, and what you give up when the rendering goes plain.
Keeping Unattended Logs Readable — Measuring axScreenReader's Plain-Text Rendering Before Adopting It
Piping Claude Code into a log file leaves you with escape codes and redraw debris instead of an answer. Here is how I enabled axScreenReader across its three entry points, measured the difference on one real task, and moved my unattended runs over to it.
Choosing Dynamic Workflow Size and Effort From a Ledger, Not a Hunch
Dynamic Workflows went generally available, handing you the workflow size and effort dials. After a week of picking large and watching only the bill grow, here is how to turn Claude Code's OpenTelemetry console output into a ledger and assign size and effort per task type.
Answering auto mode's confirmation prompts in headless runs — a deny-by-default permission-prompt-tool
auto mode's confirmation step is a friend when you're at the keyboard, but in an unattended midnight run it becomes the reason a job sits waiting until morning. Here is how I catch those prompts with permission-prompt-tool, decide deny-by-default, and log every ruling — with working code.
The Types Landed, but Nothing Got Safer — Where I Delegated a JS→TS Migration to Claude Code, and Where I Didn't
A green tsc run does not mean any is gone. Measuring a migration by type coverage, drawing a clear line between what Claude Code handles well and what a human must decide, and a CI ratchet that refuses regressions.
One Day My Push Had an Extra Destination — Guarding Against /commit-push-pr Pushing to Remotes Beyond origin
The July 14 update made /commit-push-pr push to configured push remotes in addition to origin. Convenient, but if you keep a mirror or backup as a second remote, unintended pushes quietly multiply. Here is how to inventory which remotes you can push to, block anything off the allowlist with a pre-push hook, and keep unattended runs safe — with working code.
An Empty Variable and rm -rf: How Claude Code's Auto Mode Preflight Saved My Late-Night Cleanup
An empty variable nearly turned rm -rf into a wide delete. Why set -u lets an empty string pass, and the cleanup script I rebuilt with dry run as the default.