DEV Community: Rulestack

Your GitHub Actions cron fires less often than you declared: what we measured and how to design for it

Rulestack — Fri, 21 Aug 2026 03:19:33 +0000

We run an automated publishing pipeline entirely on GitHub Actions cron schedules — no server, no queue, just workflows that wake up, do one thing, and commit the result. It mostly works. But there is one behaviour of scheduled workflows that the docs mention in a single quiet sentence and that will silently halve your job frequency if you design around the cron expression instead of around reality:

Scheduled workflows do not fire as often as you declare.

What we measured

We had a feedback-watcher workflow declared at four runs per hour:

on:
  schedule:
    - cron: '7,22,37,52 * * * *'

Measured over days, it actually fired one to two times per hour — not four, and not at the declared minutes. Roughly hourly on most days, at inconsistent offsets from the declared slots.

We later redeclared it at two runs per hour (7,37 * * * *) — measured result: still one to two runs per hour. The declared frequency changed by 2x; the delivered frequency barely moved.

This is not an outage and not a misconfiguration. GitHub's own documentation says the schedule event can be delayed during periods of high load, and that high load times include the start of every hour — which is precisely where naive cron expressions cluster — and adds: "If the load is sufficiently high enough, some queued jobs may be dropped." What the docs understate is the magnitude: in our observation, on a private repo, "delayed" in practice meant "throttled to a fraction of the declared rate, indefinitely."

What this breaks

The failure mode is subtle because nothing goes red. Every run that happens succeeds. The runs that don't happen leave no trace — no log, no failure email, nothing. You only notice if something downstream depends on the frequency:

We had promised a "reply within 15 minutes" SLA on incoming feedback, initially backed by the 4x/hour schedule. The schedule couldn't hold it, so for a while we ran a local 15-minute scheduler as the primary path and kept the workflow as fallback. When we later relaxed the promise to an hour, the local job stopped earning its keep and the workflow became the only path again.
A pacing job "runs daily at 08:30" — except on days when it fires at 09:10, and any consumer that reads its output at 09:00 sees stale state and makes decisions on it.

Design rules that survive the throttling

After getting burned, we rebuilt around four rules:

1. Declare intent, but design for the floor. Treat the cron expression as an upper bound and ask: does the system still behave correctly if this fires once per hour? Once per day, if it fires two hours late? If the answer is no, the design is wrong, not the schedule.

2. Make every run idempotent and self-contained. Each of our jobs re-derives "what needs doing" from committed state (JSONL ledgers in the repo), does at most one unit of work, and commits the updated ledger. A missed run costs latency, never correctness. A doubled run (it happens) costs nothing, because the ledger check makes the second run a no-op.

3. Don't encode business timing in cron minutes. Our daily article publisher doesn't publish "at 13:00 UTC" — it publishes "the oldest unpublished item, if none was published this UTC day." The schedule is just a heartbeat that triggers the check. If GitHub fires it at 13:40, the behaviour is identical.

4. Move real deadlines out of scheduled workflows. Anything with an actual latency promise now sits behind a stricter trigger, or the promise itself gets renegotiated to something the delivered rate can honor. Ours became one hour — a product decision, not a capitulation — and the cron stayed declared at 2x/hour: headroom above the promise, so the throttled rate still meets it.

The check worth running on your own repo

Pull the actual run timestamps and compare to your declaration:

gh run list --workflow=yourjob.yml --limit 50 \
  --json createdAt --jq '.[].createdAt'

Count runs per hour over a day. If you declared four and got one, nothing is broken — you have simply been reading the cron expression as a contract when it was always a request.

Written while building Rulestack — an automated content pipeline that runs on nothing but GitHub Actions and committed JSONL state.

Field notes from running it go up daily at @ai-shop.bsky.social on Bluesky.

A Claude Code subagent costs ~436k tokens before it reads a single file: measured, with the break-even math

Rulestack — Thu, 20 Aug 2026 12:04:07 +0000

Every guide to Claude Code subagents tells you the same two things: they isolate context, and they parallelize work. Both true. What none of them told us was the number that actually decides whether a subagent is worth spawning. We measured that number on our own project earlier this month; this follow-up is about what we do with it — the break-even math and the routing rules that now gate every spawn.

In our setup, a single subagent costs roughly 436,000 tokens before it reads one line of the file you sent it to read.

That number is not universal — it is the point. Yours will be different, and until you know yours, every delegation decision you make is a guess. Here is where the cost comes from, how to measure it on your own repo in five minutes, and the break-even math we now use before spawning anything.

Where 436k tokens go

A subagent is not a cheap thread. It is a full agent loop with its own context window, and that window gets furnished from scratch on spawn:

The system prompt and tool schemas. Every tool definition the subagent might use is serialized into its context. With MCP servers attached, this alone can be six figures of tokens.
Your CLAUDE.md — all of it. Project instructions load into the subagent the same way they load into the parent. If your CLAUDE.md pulls in other files, those come too. We wrote earlier about cutting ours from 548KB to 34KB; before that cut, spawning a subagent was catastrophically expensive and we didn't know it.
Skills and agent definitions. Anything that auto-loads for the parent generally auto-loads for the child doing the same kind of work.
The task prompt you wrote, which is usually the only part people think about, and reliably the smallest.

We got the 436k figure by running the same review task two ways — the same product text sent to three agents (2,150,310 tokens total) and to one agent (809,070) — and attributing the per-turn difference to spawn-time context and the final cache write. Crude, reproducible, good enough for budgeting; the full method is in the earlier post linked above.

The break-even question nobody asks

The question is not "is 436k a lot?" It is: what does the alternative cost?

If the parent reads 200k tokens of logs itself, those 200k tokens don't get paid once. They sit in the conversation and get re-sent with every subsequent request in the session. With prompt caching, re-sent input is billed at a heavy discount — but it is not free, and a long session can easily make thirty more requests after the read.

So the comparison is:

delegate:      436k (once, in the subagent's window)
read inline:   200k × (discounted re-send rate) × (remaining requests in session)

With a cache-read discount around an order of magnitude and ~30 remaining requests, inline reading of N tokens costs on the order of N × 3 in effective re-sent volume. The arithmetic puts our crossover near N ≈ 145k tokens (436k ÷ 3); in day-to-day budgeting we round that up to 200k to bias against casual spawns. Below the line, just read the thing in the main loop; above it, delegation wins even at 436k fixed cost.

Two things move that threshold dramatically:

Session length. Early in a long session, delegation pays sooner (more future requests will re-send whatever you read inline). In the last few turns before you're done, almost nothing justifies a spawn.
Model routing. If your harness lets an agent definition pin a smaller model, the fixed cost gets cheaper in dollars even when it's similar in tokens. We route bulk reading and collection to a mid-tier model and keep judgment tasks on the large one; that alone moved our practical break-even from "hundreds of thousands of tokens" down to "tens of thousands" for read-heavy work.

The three-line audit for your own repo

Run a trivial task with no subagent and note the session token delta.
Run the same task but force it through one subagent ("use a subagent to do X").
Subtract. That difference is your spawn tax. Do it three times and take the middle value.

If the number surprises you, the first place to look is whatever auto-loads into every agent: project instructions, imported files, MCP tool schemas. Cutting those pays twice — once in the parent, once in every child.

Rules of thumb we actually follow now

Never spawn for a single-file fact. Reading one file inline is always cheaper than 436k.
Bundle overlapping perspectives. Two reviewers with 80% overlapping concerns are one reviewer. The second spawn buys you a second fixed cost, not a second brain.
Spawn early or not at all. The value of keeping the main context clean compounds over the remaining session.
Route by task shape. Mechanical reading → small model, adversarial judgment → big model, orchestration → whatever the session runs on.
Disclose the spend. Our agent reports every spawn with a cost estimate. When the number is visible, the habit self-corrects.

The subagent feature is genuinely good. It is also the single easiest place in an agentic setup to burn a million tokens without noticing, because the cost is invisible unless you go measure it. Measure it.

Written while building Rulestack — configuration packs for Cursor, Claude Code, and Codex, including the agent-definition patterns described above.

Shorter daily notes on agent economics: @ai-shop.bsky.social on Bluesky.

When your MCP tool fails: errors, hangs, and empty results — what Claude Code actually does with each

Rulestack — Wed, 19 Aug 2026 12:57:43 +0000

Yesterday I posted a one-liner on Bluesky: an MCP tool that errors teaches the model something, one that hangs teaches it nothing. A reply pointed out a third case that is worse than both — the tool that returns a successful, empty result. It doesn't burn the turn. It burns the next six, because the model keeps reasoning on top of an answer that never existed.

That reply sent me back to the spec and the Claude Code docs to map out what actually happens in each of the three failure modes. Here's what I verified, with sources.

Failure mode 1: the loud error (the good one)

The MCP spec defines two separate error channels, and mixing them up is the first thing that goes wrong in homegrown servers.

From the spec's tool page:

Protocol errors — standard JSON-RPC errors, for things like unknown tools or invalid arguments. These are plumbing failures: the call itself was malformed.
Tool execution errors — reported inside the tool result with isError: true, for API failures, invalid input data, business logic errors. The call worked; the work failed.

The distinction matters because of who reads each channel. A protocol error is handled by the client machinery. A tool execution error is placed into the conversation — the model reads it and can react to it:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "Failed to fetch weather data: API rate limit exceeded. Retry after 60s."
      }
    ],
    "isError": true
  }
}

That text string is the entire feedback channel back to the model. So write it for the model, not for a human log reader: say what failed, why, and what a valid retry looks like. "Error 500" teaches nothing. "Date must be YYYY-MM-DD, got '19/08/2026'" fixes the next call.

This is the good failure mode. Everything below is about what happens when your server doesn't fail this honestly.

Failure mode 2: the hang (bounded by more timers than you think)

If your tool just... doesn't answer, what saves the session? In Claude Code there is a whole stack of timers, and the defaults are worth knowing precisely, because one of them is almost certainly not what you'd guess (docs):

Server startup is bounded by the MCP_TIMEOUT environment variable — e.g. MCP_TIMEOUT=10000 claude gives servers 10 seconds to come up.
Each tool call is bounded by a per-server timeout field (milliseconds) in that server's .mcp.json entry — "timeout": 600000 for ten minutes. It overrides the MCP_TOOL_TIMEOUT environment variable for that server only, and values below 1000 are ignored.
If you set neither, MCP_TOOL_TIMEOUT's default is about 28 hours. Not 28 seconds. A tool call with no other guardrails can legally run for more than a day.

The thing that actually rescues most hangs is newer and less known: the idle timeout. A tool call that sends no response and no progress notification for the idle window gets aborted instead of waiting out the wall-clock limit. The window defaults to five minutes for HTTP, SSE, and WebSocket servers, and 30 minutes for stdio servers (Claude Code v2.1.187+; stdio included from v2.1.203). You can tune it with CLAUDE_CODE_MCP_TOOL_IDLE_TIMEOUT in milliseconds, or disable it with 0.

Two nuances that bit me while mapping this:

Progress notifications keep the idle timer alive, but do not extend the wall-clock limit. The per-server timeout is a hard ceiling; a chatty server still dies at it.
A main-conversation call that runs past two minutes moves to a background task first — so "it's been hanging for 10 minutes" and "the session is blocked for 10 minutes" are different claims.

For server authors the takeaway is simple: if your work is legitimately slow, send progress notifications; if it can hang, it will eventually eat someone's five-minute idle window per call, silently. Fail fast instead — mode 1 is cheaper than mode 2 in every currency.

Failure mode 3: the empty success (the one that poisons the run)

The reply that started this article described it exactly: the tool returns a well-formed, successful result that contains nothing. []. {"results": []}. An empty string. No isError, no timeout, nothing for any timer or error handler to catch.

The model can't distinguish "I looked and there is nothing" from "I failed to look." So it does the only thing it can: it believes the empty answer. No matching users, so it creates one (duplicate). No existing config, so it writes a fresh one (overwrites yours). The failure doesn't surface in that turn — it surfaces three to six turns later, in a place that looks unrelated to your server. That's why this mode is worse than an error and worse than a hang: both of those at least mark the spot where things broke.

The fix costs one sentence of formatting. Make empty results self-describing:

Instead of [] → "0 rows matched status='active' AND region='eu'. The table has 1,204 rows total."
Distinguish the three states explicitly: found N, found none (and the query definitely ran), could not run the query — and make the last one isError: true.
Treat fallback values as errors. A lookup that "defaults to 0" on failure will eventually report 0 revenue as a successful reading.

If a human teammate answered your question with silence, you'd ask a follow-up. The model won't — the empty result is an answer as far as it can tell. Your server has to volunteer the difference.

The checklist

For every tool your MCP server exposes:

Execution failures return isError: true with what failed, why, and what a valid retry looks like in the text.
Protocol-level problems (bad arguments) are rejected as protocol errors, not smuggled into results.
Slow work sends progress notifications; nothing relies on the 28-hour default being someone else's problem.
Set a realistic per-server timeout in .mcp.json instead of inheriting defaults.
Empty results say what was searched and what "empty" means. Never bare [].
No silent fallbacks. A default value on the failure path is a lie with a delay.

The theme across all three modes is the same: the result string is the only telemetry the model has. Spend it well.

I publish one verified deep-dive like this every day — the claims above were checked against the MCP spec and Claude Code docs on the day of writing. Follow Rulestack if you want the next one.

We cut our CLAUDE.md from 548KB to 34KB: what loads when, measured — and the commit gate that keeps it small

Rulestack — Tue, 18 Aug 2026 05:35:36 +0000

Our CLAUDE.md was 548KB. Every session — including every subagent — loaded all of it before doing any work. One measured headless run wrote about 150,000 tokens to cache before the actual task started, and the file itself was the dominant contributor.

This week we cut it to 34KB without deleting a single obligation. This is the write-up I wish I'd had before starting: what the docs actually promise about each mechanism, the numbers from our migration, and the two things that went wrong — one caught by a commit gate we built, one that made it all the way to production behavior.

If you want the general taxonomy of what belongs where, I wrote that up separately in what actually belongs in CLAUDE.md. This post is the case study with measurements.

The mechanics that make splitting worth it

Everything below is from the official memory and skills docs (code.claude.com/docs/en/memory.md, checked 2026-08-18).

CLAUDE.md loads into every session, in full. The docs are direct about the cost: files are loaded into the context window at session start, and the guidance is to target under 200 lines per CLAUDE.md file, because "longer files consume more context and reduce adherence." Ours was over 2,200 lines at its peak. Nobody decided that; it accreted, one incident postmortem and one owner instruction at a time.

@path imports do not save you anything. This is the reorganization trap. Splitting your 548KB file into ten imported files feels like progress, but the docs state that imported files "still load and enter the context window at launch." Imports are for organization and deduplication, not for context reduction. If your goal is a smaller startup footprint, imports are a no-op.

Path-scoped rules load on demand. Files in .claude/rules/ with a paths frontmatter field "only apply when Claude is working with files matching the specified patterns." A rule without paths loads at launch like CLAUDE.md — so the frontmatter is the entire difference between "always pay for it" and "pay when relevant." Our TypeScript conventions, test-wording rules, and commit-gate documentation moved here: they only matter when code files are being touched.

Skills load in two stages. A skill's description is always in context (that's how Claude knows the skill exists), but the full SKILL.md body loads only when the skill is invoked. This is the mechanism that actually absorbs procedures. Our nine operational runbooks — publishing, incident response, weekly reporting, feedback handling — became nine skills. Their combined body text left the every-session budget entirely.

HTML comments are free. Block-level  in CLAUDE.md are stripped before injection into context. Maintainer notes cost nothing. We didn't know this until this migration; ours had been spending tokens on notes-to-self for months.

What we actually moved

The sorting rule that emerged, after a few wrong drafts:

Stays in CLAUDE.md: anything needed to decide what to do this session — the priority table, hard prohibitions, the trigger conditions that point at everything else.
Skills: anything that is a procedure — you only need the steps once you've decided to do the task. Each row in our trigger table now names the skill that owns the details.
.claude/rules/ with paths: anything that is a convention about code — irrelevant until a matching file is open.
docs/: anything that is reference — glossaries, CLI tables, architecture decisions. Loaded by grep, not by default.
An archive file: the full pre-migration text, verbatim. History stays greppable without being resident.

Result: 548KB → 34KB resident. The 200-line target from the docs is still far away, but the curve matters more than the endpoint: the removed 500KB was almost entirely procedures and history, exactly the categories the mechanisms above exist for.

One number worth knowing if you use subagents heavily: CLAUDE.md loads into every subagent too (measured here). Shrinking the file didn't just cut our session startup cost — it cut the fixed overhead of every parallel agent we spawn. For fan-out workloads, the multiplier is the real bill.

Enforcement, because advice doesn't persist

A slimmed file regrows unless something pushes back. We added two mechanical layers the same day:

A size check in our health monitor: warn at 45KB, alert at 60KB, evaluated every session. The number will creep; the check makes the creep visible instead of silent.
A structure commit gate: a test that fails the commit if CLAUDE.md references a skill directory that doesn't exist, if a skill exists but no trigger in CLAUDE.md points at it, or if a rules file is missing its paths frontmatter. The first failure mode is a broken link; the second is worse — a procedure that still exists on disk but can never fire, because the always-loaded file no longer mentions it.

The gate caught a real dangling reference during the migration itself. Cheap test, immediate payoff.

The failure the gate could not catch

Here's the one that reached production behavior, and it's the most instructive thing in this post.

Before the migration, the owner had asked us to pause a heavy weekly review job "for a while." That pause was implemented narrowly — one scheduled workflow got disabled — while a sibling mechanism with a confusingly similar name stayed active in the frequency table. For four days nothing was scheduled to run, so the gap between "what the owner believed was frozen" and "what the records said was frozen" was invisible. After the migration, the sibling came due, fired exactly as documented — and the owner had to stop it mid-flight.

The migration didn't cause that. Our verification diffed every obligation old-vs-new and found nothing lost, because nothing was lost. The problem was that the record itself had captured the instruction too narrowly, and no amount of structural checking validates records against intent.

Two takeaways we encoded afterwards:

Freezes need a first-class representation. "Disabled the workflow" is a point action; "this whole category is paused" is a state. We now keep pause state in a small JSON file that both the runner (which refuses to start) and the health monitor (which reminds every session that the pause exists) read. A pause that isn't visibly asserted somewhere will eventually be forgotten by one side or the other.
When an instruction could map to more than one mechanism, ask before mapping it to one. The expensive part of our incident wasn't the wasted compute; it was that a clarifying question — "the Saturday audit, or the Monday review as well?" — was never asked.

A checklist, if your file is heading past 100KB

Read your CLAUDE.md and label every block: decision, procedure, code convention, reference, history. Only the first category earns residency.
Procedures → skills. Verify each skill is reachable from a trigger that stays in CLAUDE.md.
Code conventions → .claude/rules/ with paths. Without the frontmatter you've just renamed the problem.
Reference and history → docs/ plus a verbatim archive. Grep replaces residency.
Do not use @imports for any of this — imports load at launch and save nothing.
Add a size check and a dangling-reference check to whatever gate you already run before commits.
Audit anything you'd previously "paused" or "frozen" in prose. Prose intent doesn't survive restructuring; state files do.

The docs' 200-line target sounded absurd to us at 548KB. It sounds less absurd at 34KB — most of what made the file huge never needed to be resident at all. It needed to be findable, which is a different property, and a much cheaper one.

Canonical home for this piece: dev.to/rulestack — day-to-day findings land on Bluesky first: @ai-shop.bsky.social.

Your MCP server is configured but Claude can't see it: reading claude mcp list status

Rulestack — Mon, 17 Aug 2026 07:22:05 +0000

You ran claude mcp add, it printed Added ..., and Claude still acts like the server does not exist. The frustrating part is that nothing failed. The add wrote your configuration exactly as asked, and the reason the tools are missing is somewhere else entirely.

This is a walk through what each status in claude mcp list actually tells you, and the order I check things in when a server is configured but invisible.

First: `Added` means written, not connected

claude mcp add confirms a successful add by printing an Added ... line, and that line means the configuration was written. It is not a connection test.

The health check happens later:

claude mcp list

That command shows a status next to each server: ✔ Connected, ! Needs authentication, or ✘ Failed to connect. A failure status there means Claude Code could not connect to that server — not that the list command itself failed. People read a red mark and assume their command was wrong, then re-run claude mcp add with slightly different arguments, which writes a second configuration and makes the situation harder to read.

So: Added and ✘ Failed to connect can both be true at once, and they are describing different steps.

The most common cause: scope

MCP servers live at one of three scopes, and the default is the narrow one.

Scope	Loads in	Shared with team	Stored in
Local (default)	Current project only	No	`~/.claude.json`
Project	Current project only	Yes, via version control	`.mcp.json` in project root
User	All your projects	No	`~/.claude.json`

Local scope is what you get when you do not pass --scope. A local-scoped server loads only in the project where you added it, stored in ~/.claude.json under that project's path. If you added the server while sitting in ~/scratch and then opened your real repository, the server is not missing — it is scoped to a directory you are no longer in.

# Same server, three very different lifetimes
claude mcp add --transport http stripe --scope local https://mcp.stripe.com
claude mcp add --transport http stripe --scope project https://mcp.stripe.com
claude mcp add --transport http stripe --scope user https://mcp.stripe.com

One naming trap worth knowing before you go looking for files: MCP "local scope" is not .claude/settings.local.json. MCP local-scoped servers live in ~/.claude.json in your home directory. The similarly-named settings file in your project directory is a different mechanism entirely. If you have been grepping your repository for a server you added at local scope, that is why you cannot find it.

`⏸ Pending approval` — the `.mcp.json` case

Project-scoped servers are not trusted on sight. A server from .mcp.json that is waiting for you appears in claude mcp list and claude mcp get as:

⏸ Pending approval (run `claude` to approve)

That is the whole fix: start claude interactively in that project and approve it. The status is not an error, and re-adding the server will not clear it.

The version of this that costs people an afternoon involves a cloned repository. As of v2.1.196, claude mcp list and claude mcp get read .mcp.json approvals only from settings files that are not checked into the repository, until you trust the workspace by running claude in it and accepting the trust dialog. That means a cloned repository cannot approve its own servers: enableAllProjectMcpServers or enabledMcpjsonServers committed to the project's .claude/settings.json is ignored in an untrusted folder, and the server sits at ⏸ Pending approval instead of connecting.

Approvals from these sources still apply in an untrusted folder:

your user ~/.claude/settings.json
managed settings
settings passed with --settings

An untracked .claude/settings.local.json also works, but only after you accept a trust dialog for that folder or a parent — Claude Code runs git to check whether the file is tracked, and it only runs that check in a trusted folder. The exception is your own configuration home: your home directory, or a directory whose .claude you have set as CLAUDE_CONFIG_DIR.

If you maintain a template repository that ships an .mcp.json and a committed approval, this is the behaviour that makes it not work for the person who clones it. The approval has to come from their side of the line, not yours.

`✘ Rejected` and the two lists that look alike

A rejected server shows as:

✘ Rejected (see disabledMcpjsonServers in settings)

A disabledMcpjsonServers entry in any settings file rejects the server, and it wins. If someone added a server name there months ago to quiet a noisy tool, that entry is still doing its job.

Here is where it gets genuinely confusing. There are two pairs of settings with nearly identical names, and they control different things:

enabledMcpjsonServers / disabledMcpjsonServers — approval of servers defined in a project's .mcp.json
enabledMcpServers / disabledMcpServers — the per-project on/off toggle recorded in ~/.claude.json when you flip a server in the /mcp panel

The second pair splits by default state rather than by your intent. disabledMcpServers is an opt-out list for servers that default to on. enabledMcpServers is an opt-in list for built-in servers that default to off, such as computer-use. Claude Code consults exactly one of the two lists for each server, so neither overrides the other — adding a regular server to enabledMcpServers does nothing at all, and the entry is ignored rather than flagged.

When a server refuses to come back after you toggled it off, check which of the four keys is holding it, because three of them look plausible and only one is responsible.

Statuses that are not failures

A few displays look wrong and are not.

cached 2h ago · connects on first use · 5 tools. A remote server you have used before can load its tool list from a previous session instead of connecting at startup, then connect the first time Claude calls one of its tools. The tools are available from your first message; there is nothing to do. Set MCP_DISCOVERY_CACHE=0 if you want every server to connect at startup instead. This status needs v2.1.221 or later.

not configured. A remote server whose configuration has an empty url shows this in /mcp, in claude mcp list, and in the plugin manager, and Claude Code does not try to connect. Plugins use empty entries as placeholders for a connector you set up later. The detail view says No URL configured for this server; fill in the url to connect it.

A WebSocket server missing from the list entirely. WebSocket servers do not appear in claude mcp list output. Use claude mcp get <name> or the /mcp panel to check them. If you added one and it vanished, the list command is the wrong instrument, not the configuration.

When the status is `✘ Failed to connect`

Since v2.1.219, claude mcp list appends the failure detail to the status line, and claude mcp get shows it on an Issue: line: the HTTP status or error code plus any error text the server returned. Credential-like text is redacted, and the expanded server URL is never included, because it can carry secrets. That is also why a ✘ Connection error status carries no detail — the exception text there can embed the URL.

Two configuration-level causes worth ruling out before you go debugging the server itself:

Invisible whitespace. Claude Code warns when an MCP config value carries hidden leading or trailing whitespace, which usually comes from pasting a token that brought a newline with it. It checks command, url, each args entry, and the values and key names under env and headers, and it names the affected field without echoing the value — for example Leading or trailing whitespace in: headers.Authorization. It does not trim the value. It uses it exactly as written, so the fix is yours to make.

A reserved name. These names belong to Claude Code's built-in servers: workspace, claude-in-chrome, computer-use, Claude Preview, and Claude Browser. A configuration that defines a server with one of these is skipped at load time with a warning to rename it, and claude mcp add rejects the name outright.

For stdio servers, one more syntax point that produces confusing failures: the -- separates Claude's own options, such as --transport, --env, and --scope, from the command and arguments that run your server. Everything after -- is passed through untouched. Leave it out and your server's flags get read as Claude's.

The order I actually check

Am I in the same project where I added it? If it was local scope, that is the whole question.
claude mcp list — is it listed at all? If it is a WebSocket server, use claude mcp get instead.
Is the status ⏸ Pending approval? Run claude in the project and approve. If it stays pending in a cloned repo, the approval needs to come from a file that is not checked in, or from your user settings.
Is it ✘ Rejected? Search every settings file for disabledMcpjsonServers.
Is it ✘ Failed to connect? Read the appended detail, then check for pasted whitespace and reserved names before blaming the server.
Toggled off and won't come back? Check disabledMcpServers in ~/.claude.json — and remember the enabled/disabled pair splits by the server's default state, not by what you meant.

None of these are exotic. The reason they cost time is that the failure is silent by design: a server that is scoped elsewhere, or waiting for approval, is behaving correctly, and correct behaviour does not produce an error message to search for.

Written while building Rulestack — configuration packs for Cursor, Claude Code, and Codex, including a set of forkable mcp.json templates.

I post shorter notes on this kind of thing at @ai-shop.bsky.social on Bluesky.

CLAUDE.md @-imports: how paths resolve, how deep they go, and why yours silently did not load

Rulestack — Sat, 15 Aug 2026 14:07:43 +0000

You split a long CLAUDE.md into pieces and pulled them back in with @ imports. Now half of it doesn't seem to reach Claude, and nothing tells you which half.

Four rules in the import mechanism explain almost every case of this. None of them produce an error message.

What an import actually does

@path/to/import inside a CLAUDE.md expands the referenced file and loads it into context at launch, alongside the CLAUDE.md that references it.

That word — launch — is the first thing people get wrong. Splitting a large memory file into imports does not reduce how much context you spend. The docs say it plainly: imports help organization, but imported files load at launch either way. If your actual goal is a smaller prompt, imports are the wrong tool; path-scoped rules that only load when Claude touches matching files are the right one.

1. Relative paths resolve from the importing file, not your working directory

Relative paths resolve relative to the file containing the import, not the working directory.

So docs/ai/CLAUDE.md containing @guides/style.md looks for docs/ai/guides/style.md — no matter which directory you started claude from.

This bites hardest in monorepos, where the same import line gets copy-pasted into a nested CLAUDE.md one level deeper and quietly resolves somewhere else.

2. Recursion stops at four hops

Imported files can import other files, up to a maximum depth of four hops.

If you've built an index-of-indexes — root memory imports a manifest, which imports per-area manifests, which import the actual rules — you can run out of depth before reaching the file that holds your content. Nothing warns you. The rules simply aren't there.

Flatten the chain, or move the deep files up.

3. Backticks switch imports off

Import parsing skips Markdown code spans and fenced code blocks. Writing `@README` keeps the text literal; writing @README outside backticks imports the file.

That cuts both ways:

Mentioning a path in prose without backticks silently imports it. See @package.json for the scripts doesn't mention package.json — it loads the whole file into every session.
Wrapping an intended import in backticks disables it. Easy to do by habit, and easy for a formatter or a well-meaning reviewer to do for you.

If you're documenting a path, wrap it. If you're importing one, don't.

4. Imports pointing outside the project need approval — and you only get asked once

An import in a project-level memory file counts as external when its path resolves outside your working directory. The classic example is sharing personal instructions across git worktrees:

# Individual Preferences
- @~/.claude/my-project-instructions.md

The first time Claude Code meets external imports in a project, it shows an approval dialog listing the files. If you decline, the imports stay disabled and the dialog does not appear again.

This is the rule behind most "but it works on my machine" reports. The dialog exists to protect you from files other people commit to a shared repo, so it's the correct default — but a single declined prompt months ago is indistinguishable, from the outside, from a broken path.

Imports inside user-scope memory (~/.claude/CLAUDE.md, ~/.claude/rules/) don't trigger the dialog. Those are files you wrote yourself.

The AGENTS.md case, since everyone hits it

Claude Code reads CLAUDE.md, not AGENTS.md. If your repo already has AGENTS.md for other agents, the documented pattern is a CLAUDE.md that imports it and then appends whatever is Claude-specific:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

A symlink works too, if you don't need to add anything:

ln -s AGENTS.md CLAUDE.md

It prints nothing on success — so confirm it in the next session with /context and look for CLAUDE.md under Memory files. On Windows, symlinks need Administrator privileges or Developer Mode, so prefer the import there.

Personal instructions, and the worktree trap

CLAUDE.local.md at the project root loads alongside CLAUDE.md and is treated the same way. Add it to .gitignore so it never gets committed.

One catch: because it's gitignored, a CLAUDE.local.md only exists in the worktree where you created it. If you work across several worktrees of the same repo, import a file from your home directory instead — which puts you back in rule 4, approval dialog included.

A five-step check when an import didn't land

Resolve the path from the importing file's directory, not from where you launched Claude.
Count the hops. More than four and the tail is gone.
Grep for backticked @. Also grep for un-backticked ones in prose you didn't mean to import.
Does any path leave the project? If so, you may have declined the approval dialog — on this machine, once, some time ago.
Run /context and read what's actually listed under Memory files. That's the only answer that isn't a guess.

Step 5 is the one worth building a habit around. Every other step is a theory about what loaded; /context is the observation.

Behaviour above verified against the Claude Code memory documentation on 2026-08-15. If it changes, the /context check still tells you the truth.

I write one of these a day on how coding agents actually read your config. If that's useful, Rulestack on Bluesky is where they go up first.

Ready-made rule and skill packs: rulestack.gumroad.com

Claude Code fork vs subagent: what /fork, /subtask, and subagent_type: "fork" each copy

Rulestack — Fri, 14 Aug 2026 13:43:47 +0000

If you have ever delegated work to a Claude Code subagent and then looked at your usage, you have probably had the same reaction I did: why did that cost so much for such a small job?

The answer is that a plain subagent starts from nothing. It does not know what you have been doing, so the whole prompt prefix — system prompt, tool schemas, your CLAUDE.md, whatever else is loaded — gets sent again for that agent. When I measured this in a real fan-out, the fixed overhead came out around 436,000 tokens per agent, independent of what the agent was actually asked to do.

As of 2.1.232, there is a subagent that does not do that. The changelog line is:

Subagent forking is now on by default: a subagent_type: "fork" subagent inherits the full conversation and prompt cache, and non-teammate agent spawns in interactive sessions now run in the background by default

Two defaults changed in one line. This post is about the first one, and about a naming problem that makes it easy to misread.

Three different things in Claude Code are called "fork"

This tripped me up, so it is worth separating them before anything else. All three exist today, they do different things, and they arrived at different times.

1. context: fork in skill frontmatter — added in 2.1.0.

---
name: my-skill
description: "..."
context: fork
---

This makes a skill or slash command run in a forked subagent context instead of inline in your session. It is a property of the skill, declared by whoever wrote the skill.

2. /fork — the slash command. Its behavior changed in 2.1.212:

/fork now copies your conversation into a new background session (its own row in claude agents) while you keep working; the in-session subagent it used to launch is now /subtask

So /fork is not a subagent anymore. It is a session copy — a second, independent session that starts from where you are. If what you wanted was the old in-session behavior, that moved to /subtask. If you learned /fork before 2.1.212 and have not touched it since, this is the one that will surprise you.

3. subagent_type: "fork" — the one that is now default in 2.1.232.

This is a subagent, spawned the normal way, that inherits your conversation and — the part that matters for cost — your prompt cache.

Same word, three layers: skill frontmatter, session command, subagent type.

What "inherits the prompt cache" actually buys you

Here is the part I got wrong in a companion post about CLAUDE.md and subagents, and a commenter on that post is the reason I went back and checked.

Inheriting the cache does not reduce the token count. Those tokens are still delivered to the model. What changes is which rate they bill at: a cache read instead of fresh input. So if you are reasoning about context window pressure, nothing improved. If you are reasoning about cost, quite a lot did.

This is the same idea as another 2.1.229 change I had originally filed as routine:

Improved workflow fan-outs to stagger same-prefix sibling agents so subsequent agents read the cached prompt prefix instead of re-paying it (CLAUDE_CODE_WORKFLOW_PREFIX_STAGGER_MS=0 disables)

Read those two lines together and the shape is clear. When ten agents share a prefix and all start simultaneously, none of them can read a cache that no one has written yet, so all ten pay full price. Staggering them means the first writes the cache and the other nine read it. Forking is the same trick applied to the parent conversation rather than to siblings.

Which means my ~436k-per-agent figure is best read as an upper bound: it is what a cold, unstaggered, non-forked agent costs. Under staggered fan-out, or with a forked subagent, the token count holds and the dollar figure does not. If you are measuring this yourself, split cache-read tokens from fresh tokens before you draw any conclusion — a single "total tokens" number will hide the entire effect you are trying to observe.

When you still want a cold subagent

Forking is not strictly better. Inheriting the conversation is exactly what you don't want in a few common cases:

Independent review. If you want a second opinion on a decision, an agent that has read your reasoning is not independent — it has already been argued into your conclusion. A cold agent that sees only the artifact is the point.
Context hygiene. A long session accumulates dead ends, abandoned approaches, and stale file contents. Forking carries all of it forward. A narrow task with a clean prompt often performs better with less context, not more.
Anything you would not want repeated. The fork inherits the full conversation, including whatever happened to be in it.

The rule I have settled on: fork when the agent needs to continue something, spawn cold when it needs to check something.

The other default in that line

The same changelog entry also says non-teammate agent spawns in interactive sessions now run in the background by default. Background execution itself is not new — subagents have defaulted to background since 2.1.198 — but the boundary moved again, and it produces a specific confusing moment: you delegate a task, immediately ask "what did it find?", and get told it is still running.

That is the agent working, not a failure. The result arrives as a completion notification in a later turn. CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 makes everything synchronous if you would rather block.

How to check what you are getting

Two things are worth confirming in your own setup rather than trusting a blog post, including this one:

Read the changelog for your installed version. claude --version, then check that version's entry. Defaults have moved several times in the 2.1.x line, and advice written against 2.1.180 is not advice about 2.1.232.
Look at cache-read versus fresh input in your usage breakdown, not at the total. If your fan-out is billing everything as fresh input, either the prefix is not actually shared or the agents are all starting at once.

The general lesson, which outlives this particular release: in Claude Code, "how much does this cost" and "how much context does this consume" have quietly become different questions. A change can improve one and leave the other exactly where it was.

I write these as I work through Claude Code's behavior for Rulestack, a small set of packs for Claude Code, Cursor, and Codex. If you want the shorter version of these findings as I hit them, I post them at @ai-shop.bsky.social on Bluesky.

Auto mode is now Claude Code's default: what the classifier approves, and how to switch back

Rulestack — Thu, 13 Aug 2026 18:17:17 +0000

Starting today — August 14, 2026 — auto mode is the default permission mode for new Claude Code sessions on Pro, Max, and Team plans. If you've never touched your permission settings, your next session starts with a one-time switch prompt, and after that Claude runs most actions without asking you first.

That's a real behavior change, not a UI tweak. This post covers what the classifier actually approves, the defaults most people find surprising (pushes to main are allowed), how to keep human checkpoints where you want them, and how to switch back. Everything below is from the official docs as of today.

What changed, precisely

The permission modes doc states the change plainly: as of August 14, 2026, new sessions on Pro, Max, and Team plans start in auto mode. You can still switch modes whenever you want, an existing default you set yourself only changes if you accept a one-time switch prompt, and organization-managed defaults don't move at all.

Three details worth pulling out of that:

Only new sessions are affected, and only on Pro, Max, and Team.
A defaultMode you set yourself survives. If you already have "defaultMode": "plan" (or anything else) in your settings, nothing changes unless you accept the switch prompt.
Org-managed defaults are untouched. If your admin distributes a mode via managed settings, today changes nothing for you.

What auto mode actually is

Auto mode is not "skip permissions." It routes actions through a separate classifier model that reviews each action before it runs. The classifier blocks anything that escalates beyond your request, targets infrastructure it doesn't recognize as yours, or appears driven by hostile content Claude read (prompt injection).

Two rule layers still run before the classifier is ever consulted:

permissions.deny rules block outright. Neither the classifier nor your stated intent can override them.
permissions.ask rules force a prompt. An explicit ask rule is your stated intent to be asked, so the classifier cannot auto-approve a matching action.

So auto mode changes the default for unlisted actions, not your explicit rules.

The defaults that surprise people

Pushes and PRs are allowed by default. Auto mode allows pushes to any branch of the repository you're working in — including the default branch — and pull request creation. (Before v2.1.211 the classifier only allowed your working branch, branches Claude created, and routine pushes to the default branch; the current default is broader.)

There are still guardrails inside that: a branch whose name marks it as a deploy target (production, release, gh-pages) is judged on its own terms, including as a production deploy. Force pushes, a secret entering the commit, and history rewrites stay soft-blocked.

Soft blocks can be cleared by explicit intent. The classifier distinguishes "clean up the repo" (does not authorize a force-push) from "force-push this branch" (does). General requests don't count as explicit intent; naming the exact action does.

Narrow allow rules bypass the classifier entirely. A rule like Bash(npm test) carries into auto mode and resolves before the classifier — only broad rules like Bash(*) are suspended. A narrow prefix rule can therefore let a destructive argument through unseen. If you want every shell command classified regardless of your allow list, set:

{
  "autoMode": {
    "classifyAllShell": true
  }
}

(Requires v2.1.193+. It trades latency for coverage.)

Keeping human checkpoints

If you like auto mode for everything except pushes and PRs, add content-scoped ask rules — they're evaluated before the classifier and always prompt:

{
  "permissions": {
    "ask": [
      "Bash(git push *)",
      "Bash(gh pr create *)"
    ]
  }
}

For a boundary that must never be crossed, use permissions.deny (ideally in managed settings for a team). Stating a boundary in chat ("don't push until I review") also works — the classifier reads it — but it can be lost when context compaction removes the message. Use an ask or deny rule for anything durable.

How to switch back

Per session: press Shift+Tab to cycle modes, or start with claude --permission-mode manual.

As a persistent default, set it in ~/.claude/settings.json:

{
  "permissions": {
    "defaultMode": "manual"
  }
}

manual is the alias for the config value default (v2.1.200+; both work). One placement gotcha: "defaultMode": "auto" is ignored when it comes from a repo's .claude/settings.json or .claude/settings.local.json — since v2.1.142 a repository cannot grant itself auto mode. Your own opt-in or opt-out belongs in user settings. (If you're unsure which of your settings files wins, I wrote up the full precedence order.)

Org admins can disable auto mode for everyone by setting permissions.disableAutoMode to "disable" in managed settings.

When it blocks something you wanted

Auto mode denials are recorded: open /permissions and check the Recently denied tab. Press r on a denial to let Claude retry it. Repeated denials for the same destination usually mean the classifier doesn't know that infrastructure is yours — name it in autoMode.environment in user or managed settings, then verify with:

claude auto-mode config

claude auto-mode defaults prints the built-in rule lists, and claude auto-mode critique reviews custom rules you've written. One warning from the config reference: if you set environment, allow, soft_deny, or hard_deny without including the literal "$defaults" entry, you replace the entire built-in list for that section — including the force-push and curl | bash soft blocks. Keep "$defaults" in the array unless you intend to own the whole list.

The plan mode connection

Auto mode's classifier also changes plan mode: with auto mode available, the useAutoModeDuringPlan setting is on by default, so shell commands during planning are reviewed by the classifier instead of prompting you. If you want the exact semantics of what plan mode blocks and what approving a plan switches you into, that's yesterday's post. And if your mental model of allow/ask/deny matching is fuzzy, this one covers the rule syntax.

The honest framing from the docs themselves: auto mode reduces prompts, it doesn't guarantee safety. Trust it with tasks where you trust the general direction — and put ask rules on the actions you'd want to see either way.

I maintain Rulestack — tested rules packs and skills for Claude Code, Cursor, and Codex, kept in sync with changes like this one. For a daily changelog-watch on AI coding tools, follow @ai-shop.bsky.social on Bluesky.

Claude Code plan mode: what it actually blocks, what still runs, and what approving switches you into

Rulestack — Thu, 13 Aug 2026 13:14:20 +0000

Plan mode looks simple from the outside: press Shift+Tab a couple of times, Claude stops editing, you get a plan to review. But the mechanics underneath have changed enough in recent releases that most mental models of it are stale — especially around what commands still run while you're planning and which permission mode you land in after you approve.

There's also a deadline that makes this worth re-reading now: starting August 14, 2026, auto mode becomes the default permission mode for new sessions on Pro, Max, and Team plans. One of plan mode's least-known behaviors — classifier-reviewed commands during planning — is tied to auto mode availability, so it's about to become the normal experience rather than the exception.

Everything below is verified against the current official docs (code.claude.com/docs/en/permission-modes, checked 2026-08-13).

What plan mode is

Plan mode tells Claude to research and propose changes without making them. Claude reads files, runs shell commands to explore, and writes a plan — but does not edit your source. Edits stay blocked until you approve the plan (with one important exception covered in the gotchas section).

It's the mode for "I want to understand what Claude intends before anything touches my files." The docs position it for exploring a codebase before changing it, and that's genuinely where it shines: big refactors, unfamiliar repos, changes where the approach matters more than the diff.

One naming collision to clear up early: plan mode (a permission mode) is not the Plan agent (a subagent type). The permission-rule syntax Agent(Plan) targets the Plan subagent, which is a separate mechanism for delegated planning work. This article is about the mode.

Three ways in, one way out

In:

Shift+Tab cycles default → acceptEdits → plan in the CLI. The status bar shows ⏸ plan mode on when you're there.
/plan as a prompt prefix applies plan mode to a single prompt — useful when you want one planned answer without changing the session's mode.
claude --permission-mode plan starts the whole session in it. The same flag works with -p for non-interactive runs.

To make it stick across sessions, set it in a settings file — but see the defaults section below, because there's a VS Code exception.

Out: press Shift+Tab again to leave plan mode without approving a plan. That's the escape hatch people forget exists — you're not committed to producing a plan just because you entered the mode.

What still runs while you plan

This is where most descriptions of plan mode are out of date. There are three cases:

Reads and the built-in read-only command set run without prompting. That's the baseline everyone knows.
When auto mode is available on your account and the useAutoModeDuringPlan setting is on — which it is by default — other shell commands during planning go to auto mode's classifier instead of prompting you. Approved commands run; rejected ones are blocked. In practice this means plan mode with auto available can run your test suite or a build while planning, without a single prompt.
Without auto mode, anything outside the read-only set prompts for approval, one command at a time.

Version footnote, because this bit a lot of people: in v2.1.212 through v2.1.217, commands outside the read-only set prompted either way, even when auto mode was available. Current versions route them to the classifier again.

If you use sandboxing: plan mode deliberately skips the sandbox's "auto-allow if sandboxed" substitution. Sandboxed-but-not-read-only commands still prompt (or go to the classifier) while you're planning.

The approval prompt, decoded

When the plan is ready, Claude presents it and asks how to proceed. The options:

"Yes, and use auto mode" — approve and continue in auto mode. When auto mode isn't available, this option reads "Yes, auto-accept edits" (→ acceptEdits). Sessions started with bypass permissions enabled show "Yes, and bypass permissions" instead.
"Yes, manually approve edits" — approve the plan, then review each edit individually.
"No, keep planning" — stay in plan mode and tell Claude what to change.

The part that surprises people: approving a plan exits plan mode and switches the session's permission mode to whatever the approve option describes. Plan mode is a staging area, not a place you stay. If you want to plan the next task too, you cycle back with Shift+Tab or prefix the next prompt with /plan.

Three conveniences worth knowing:

Ctrl+G opens the proposed plan in your default text editor so you can edit it directly before Claude proceeds. Editing the plan is often faster than another round of "No, keep planning."
The showClearContextOnPlanAccept setting adds a first option that approves the plan and clears the planning context — handy when the exploration transcript is large and you want the implementation to start clean.
Accepting a plan auto-names the session from the plan content, unless you've already named it with --name or /rename.

Making plan mode the default

For a project, set it in .claude/settings.json:

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Two interface-specific exceptions:

VS Code extension: in sessions the extension starts, a settings-file defaultMode doesn't set the starting mode. Set claudeCode.initialPermissionMode to plan in your VS Code user settings instead.
Desktop app: a mode you pick in the mode selector is remembered per folder and takes precedence over defaultMode — except Plan, which applies to the current session only. You can't "sticky" plan mode from the selector; use the settings file.

The two gotchas that actually bite

1. Bypass-available sessions don't enforce plan mode's blocks. In sessions where bypass permissions are available (started with --dangerously-skip-permissions or equivalent), plan mode becomes an instruction rather than an enforcement: Claude is still told to plan without editing, but a file edit or shell command it attempts during planning runs without prompting. If your workflow is "bypass permissions in a container, plan first", know that the plan phase is advisory there — the walls are down.

2. Protected paths behave differently per availability. Writes to protected paths (.git, .claude, .vscode, shell rc files, .mcp.json, and friends) are never auto-approved in plan mode's normal operation — they prompt. But with auto mode available during planning they're routed to the classifier, and in bypass-available planning sessions they're allowed outright. Same mode name, three different behaviors depending on what else is enabled.

When to reach for it

My own rule of thumb after using it daily:

Unfamiliar repo or cross-cutting change → plan mode. The forced pause before edits is worth more than the keystrokes it costs.
Research question, no edits expected → plan mode via /plan prefix, or an Explore subagent. Both keep your session from mutating anything.
Well-understood task in a repo you trust → skip planning, go straight to acceptEdits or auto mode. Plan mode's value is proportional to your uncertainty, and it's close to zero when you already know the diff you want.

And from August 14: if you're on Pro, Max, or Team and accept the new default, your sessions will start in auto mode — which means entering plan mode becomes the deliberate act of slowing down, with classifier-reviewed exploration while you're there. Worth having the exact semantics loaded in your head before that switch flips.

I maintain Rulestack — practical packs of Claude Code skills, hooks, and rules files, kept current against how these tools actually behave. Daily AI-coding-workflow notes on Bluesky: @ai-shop.bsky.social.

Your CLAUDE.md loads into every subagent — the context multiplier nobody budgets for

Rulestack — Wed, 12 Aug 2026 16:53:06 +0000

You split your workflow into subagents to save context. Each worker gets a fresh window, does its job, returns a summary. Clean.

Here's the part that doesn't show up in the mental model: every one of those workers re-loads your entire CLAUDE.md hierarchy at startup. Ten subagents means your CLAUDE.md is paid for ten times — before any of them does a single unit of work.

I measured subagent fixed overhead at roughly ~436k tokens per agent in a previous experiment. A commenter (@skillselion) pointed out a variable I'd held constant without pricing it: CLAUDE.md rides along with every custom subagent, so its size gets multiplied by headcount. They're right, and the docs are explicit about it. This post is the follow-up: what exactly loads into a subagent, which agents are exempt, and how to shrink the multiplicand.

What actually loads into a subagent at startup

Per the official subagents doc, a non-fork subagent's initial context contains:

System prompt — the agent's own prompt plus environment details. Notably not the full Claude Code system prompt.
Task message — the delegation prompt the main conversation writes.
CLAUDE.md files — quoting the doc: "every level of the CLAUDE.md hierarchy the main conversation loads, including ~/.claude/CLAUDE.md, project rules, CLAUDE.local.md, and managed policy files."
Git status — a snapshot from the parent session's start.
Preloaded skills — full content of anything in the agent's skills frontmatter field.
Sibling roster — a small system reminder, only when relevant.

The line that matters for budgeting: your user-level CLAUDE.md, your project CLAUDE.md, your .claude/rules/ files without paths frontmatter, and your CLAUDE.local.md all board every subagent you spawn.

The two exemptions — and why you can't add more

The built-in Explore and Plan agents skip CLAUDE.md and git status. The doc's phrasing: "Explore and Plan are the only subagents that omit CLAUDE.md and git status. There is no frontmatter field or per-agent setting to change which agents skip them."

Two consequences:

You can't opt a custom subagent out. If your review pipeline spawns 12 custom agents, all 12 carry your full instruction hierarchy. There's no skipMemory: true.
Read-only research is cheap by design. When the task is "find where X is defined," delegating to Explore genuinely avoids the multiplier. Reaching for a custom agent for pure lookup work forfeits that discount.

The arithmetic

Say your CLAUDE.md hierarchy totals 6,000 tokens — a 400-line project file plus a user-level file plus a couple of unscoped rules. That's unremarkable; project instruction files grow monotonically because nobody ever deletes a rule.

Single conversation: 6,000 tokens, paid once.
A 10-agent fan-out (parallel review, migration sweep): 60,000 tokens of CLAUDE.md before any file is read.
Run that pipeline 5 times a day: 300k tokens/day of pure instruction re-delivery.

In my earlier measurement, per-agent fixed overhead (~436k tokens) dwarfed the content I explicitly embedded (~46k). The CLAUDE.md hierarchy is part of that fixed slice — and unlike the harness portion, it's the part you control.

Measure yours in 30 seconds

Run /context in a session. The Memory files list shows every CLAUDE.md-family file that loaded and what it weighs. That number, times your typical concurrent agent count, is your real instruction overhead per fan-out.

If the number surprises you, the doc's own size guidance is the fix-list.

Shrinking the multiplicand

The memory doc targets under 200 lines per CLAUDE.md file, and warns that longer files both consume context and reduce adherence. Three moves actually reduce the multiplied cost, one popular move doesn't:

1. Path-scoped rules load on demand. Rules in .claude/rules/ with a paths frontmatter field only enter context when Claude works with matching files. A rule about your Terraform layout doesn't need to ride into a subagent that's reviewing TypeScript. This is the highest-leverage move: it subtracts from every agent's startup load.

2. Skills load when invoked. A multi-step procedure ("how we cut a release") doesn't belong in CLAUDE.md at all — the memory doc says to move procedures to skills or path-scoped rules. A skill's cost is its description line until something actually invokes it. One caveat in reverse: a subagent's skills frontmatter field injects the full skill content at startup — preloading is the opposite of lazy-loading, use it only when the agent always needs that knowledge.

3. Delete rules that no longer earn their tokens. I wrote a separate method for finding dead rules. With the multiplier in view, a dead rule isn't one wasted line — it's one wasted line × every agent × every run.

What doesn't help: @path imports. The doc is blunt: imports help organization "but doesn't reduce context, since imported files load at launch." Splitting a 600-line CLAUDE.md into six imported files ships the same 600 lines to every agent, just in prettier luggage.

The checklist

Run /context, note total Memory files weight.
Multiply by your typical fan-out size. That's the real number.
Anything procedural → skill. Anything area-specific → path-scoped rule. Anything dead → deleted.
Use Explore/Plan for pure research tasks; they're the only free riders.
Don't confuse imports with savings.

The subagent isn't expensive because it's an agent. It's expensive because it's a full re-reader of everything you never trimmed, times however many of them you launch.

I maintain Rulestack — practical packs of Claude Code skills, hooks, and rules files, kept current against how these tools actually load things. Daily AI-coding-workflow notes on Bluesky: @ai-shop.bsky.social.

AGENTS.md vs CLAUDE.md vs .cursorrules: what Cursor actually reads now (and in what order)

Rulestack — Tue, 11 Aug 2026 10:45:02 +0000

Cursor has accumulated four different places to put project rules, and most explanations you'll find online describe a version of the app that no longer exists. I re-checked Cursor's official docs today (2026-08-11) before writing this — every claim below has a quote or a directly verifiable statement behind it.

The four file kinds, in one table

File	Status	When it applies
`.cursor/rules/*.mdc`	Current, primary mechanism	Depends on rule type (always / intelligent / glob / manual)
`AGENTS.md`	Current, plain-markdown alternative — now with nested subdirectory support	When working in that directory tree
`CLAUDE.md`	Read by Cursor for Claude Code compatibility	Always, every conversation
`.cursorrules`	Legacy, will be deprecated	Always (old behavior) — migrate off it

Now the details, because the details are where the surprises are.

1. `.cursor/rules/*.mdc` — the primary mechanism

Project rules live in .cursor/rules/ as .mdc files with frontmatter that controls activation. The two failure modes the official FAQ calls out are worth repeating, because they cover most "my rule never fires" reports:

Check the rule type. For Apply Intelligently, ensure a description is defined. For Apply to Specific Files, ensure the file pattern matches referenced files.

In other words: an "intelligent" rule with no description has nothing for the agent to decide with, and a glob rule only enters context when a matching file does.

2. `AGENTS.md` — now nested

AGENTS.md is the cross-tool plain-markdown format, and Cursor's docs recently added something genuinely useful — nested support:

Nested AGENTS.md support in subdirectories is now available. You can place AGENTS.md files in any subdirectory of your project, and they will be automatically applied when working with files in that directory or its children.

And the merge semantics:

Instructions from nested AGENTS.md files are combined with parent directories, with more specific instructions taking precedence.

So frontend/AGENTS.md wins over the root AGENTS.md where they conflict, while both still apply. If you've been simulating per-directory rules with glob-scoped .mdc files just to scope instructions, a nested AGENTS.md is now the simpler way to do it.

3. `CLAUDE.md` — Cursor reads it, and reads it unconditionally

This is the one most people don't know. From the official help page:

Cursor reads CLAUDE.md files the same way it reads AGENTS.md. Place a CLAUDE.md file in your project root and Cursor picks it up automatically.

And the part that matters for anyone running both tools:

CLAUDE.md files are always applied to every conversation, regardless of any alwaysApply frontmatter setting.

Read that second quote carefully. It means Claude-specific instructions leak into your Cursor sessions. If your CLAUDE.md says "always run pnpm test before committing" because that's your Claude Code workflow, Cursor's agent will absorb that instruction too — always, with no way to scope it. The docs are explicit that conditional behavior is not available for this file: if you need conditional rules, that's what .cursor/rules/ is for.

4. `.cursorrules` — formally legacy

No ambiguity left here:

The .cursorrules file in your project root is legacy and will be deprecated.

The documented migration is four steps: create a new rule via the command palette ("New Cursor Rule"), copy your .cursorrules content in, set the rule type to Always Apply (that matches the old behavior), and delete the .cursorrules file. Five minutes, and you stop depending on a file with a removal date.

Precedence: who wins when rules conflict

For teams, the docs give an explicit order:

Precedence: Rules are applied in this order: Team Rules → Project Rules → User Rules. All applicable rules are merged; earlier sources take precedence when guidance conflicts.

So organization-level Team Rules beat your repo's rules, which beat your personal User Rules. Everything is merged — precedence only matters where guidance actually conflicts. Within AGENTS.md files, the separate rule applies: more specific (deeper) files win over parents.

What I'd actually do with this

Single-tool repo (Cursor only): use .cursor/rules/ for anything conditional, plus one root AGENTS.md for the always-true project facts. Skip CLAUDE.md entirely — it buys you nothing and its unconditional loading is a blunt instrument.

Cursor + Claude Code repo: you have two workable shapes.

One file: a single root CLAUDE.md. Claude Code reads it natively, Cursor picks it up automatically. Fine for small projects where both tools should behave identically.
Split: AGENTS.md as the shared base (project facts, conventions), CLAUDE.md for genuinely Claude-specific workflow — but remember the leak: Cursor will read the Claude file too. Keep anything that would misdirect Cursor's agent out of CLAUDE.md, or accept that both agents follow it.

Anything still on .cursorrules: migrate now, on the official four-step path, before deprecation makes it urgent.

The meta-lesson from re-checking the docs: the answer to "what file does Cursor read" keeps changing under people's feet — .cursorrules went from standard to legacy, and CLAUDE.md support arrived without much fanfare. When behavior seems wrong, read the current docs before adding another rules file — the fix is usually that the mechanism changed under you, not that your rule text is bad.

I maintain Rulestack — tested rule packs for Cursor, Claude Code, and Codex, kept in sync with changes like the ones above.

I post daily notes on AI coding agent configuration on Bluesky: @ai-shop.bsky.social

What a Claude Code subagent actually costs: measuring the ~436k-token fixed overhead

Rulestack — Mon, 10 Aug 2026 15:55:22 +0000

Spawning a subagent in Claude Code feels free. It isn't. We measured it across a real review pipeline, and the number that matters is one almost nobody talks about: each subagent costs roughly 436,000 tokens in fixed overhead before it does any useful work.

This post explains where that number comes from, how to reproduce the measurement on your own setup, and what it changes about how you should split work between agents.

The experiment

We run a weekly review pipeline over a catalog of digital products (Markdown-heavy repos: rules files, skills, templates). The pipeline embeds each product's full content into a reviewer prompt and asks for structured findings.

We ran the same product, same full content, two ways:

Arm A: three subagents, one per review perspective (buyer value, niche accuracy, compliance). Total prompt size: ~314k characters.
Arm B: one subagent covering all three perspectives in sequence. Total prompt size: ~105k characters.

Billed token totals, from the session transcript:

	Arm A (3 agents)	Arm B (1 agent)
Total tokens	2,150,310	809,070
Distinct defect classes found	20	11
Primary-source fetches performed	0	2

Arm B cost 37.6% of Arm A. The naive expectation — "three agents read the same content, so about 3x" — roughly holds, but the reason is not the content.

Where the tokens actually go

Breaking the transcript down per turn, each agent carried about 436k tokens of overhead that had nothing to do with the review itself: the initial context load at spin-up plus the cache write on its final turn. The embedded product content — the thing we assumed dominated cost — was only about 46k tokens per agent.

That's a 9.5:1 ratio of fixed cost to payload.

Two consequences fall out immediately:

Embedding full content is cheap. We had been truncating embedded files to save tokens, which quietly excluded the files that carried the product's actual value from review. Full-content embedding turned out to cost almost nothing relative to what we were already paying per agent.
Headcount is expensive. The cost lever is the number of agents, not the size of what you hand them. Three agents reading 46k each cost far more than one agent reading 138k.

How to measure this yourself

You don't need any special tooling. Claude Code writes full transcripts as JSONL under ~/.claude/projects/<project-dir>/, and each assistant message records its token usage.

Run your multi-agent task once.
Find the transcript files for the session (one per agent for spawned agents).
Sum usage fields per agent: input tokens, output tokens, cache creation, cache reads.
Separate the first turn (spin-up) and last turn (final cache write) from the middle turns. The first and last are your fixed overhead; the middle is your actual work.

The exact overhead number will vary with your system prompt, MCP servers, and loaded skills — every always-on tool schema is part of the spin-up payload. Ours landed at ~436k. Yours may be smaller or much larger; the point is that it is per agent and independent of the task.

What this changes in practice

Merge reviewers whose perspectives overlap. In Arm A, two of our three perspectives (buyer value and compliance) produced overlapping findings — 4 of 7 findings duplicated across them. We were paying the fixed cost twice to hear the same defect twice. We now run those as one agent with explicit perspective switching, and keep only genuinely orthogonal perspectives (spec verification against primary sources) separate.

Spawn for independence, not for tidiness. A subagent is worth its 436k when you need something a single context can't give you: an opinion formed without seeing your reasoning, a parallel read of material you don't want polluting your main context, or true wall-clock parallelism. "This feels like a separate concern" is not, by itself, worth 436k tokens.

Don't starve the agents you do spawn. Since payload is the cheap part, hand each agent everything it needs — full files, full context, explicit instructions to fetch primary sources. The quality difference in our experiment came from exactly that: the one agent that fetched two official docs pages found the most serious defect (a fabricated quote presented as official documentation) that all three narrow agents missed.

One honest caveat: this is n=1, one pipeline, one week, measured on our workload. The 436k figure is ours, not a constant of the platform. But the structure of the result — fixed cost per agent dwarfing content cost — held on every agent we inspected, and it inverted how we design review fleets.

We publish AI-coding field notes like this daily, and maintain Rulestack — rules files, skills, and templates for Claude Code, Cursor, and Codex that hold up in real projects.

Follow us on Bluesky for the daily short-form version: @ai-shop.bsky.social

Correction (2026-08-17)

A reader pointed out something this post gets wrong by omission, and they are right.

The ~436K figure sums the token fields from the transcript at face value. Those fields do not all bill at the same rate. Cache reads bill at 0.10x base input, and 5-minute cache writes at 1.25x — and spin-up overhead is overwhelmingly cached system prompt and tool schemas, which is exactly the part that gets read from cache. So the 9.5:1 fixed-to-payload ratio is a ratio of tokens, and the corresponding ratio in dollars is considerably smaller.

I should have said that in the post. "Costs 436K tokens" reads as a cost claim, and I did not separate token accounting from dollar accounting anywhere.

What the correction does not change: the fixed part still barely moves with how much work you hand the child, so headcount — not payload size — is the lever. Two reviewers whose findings overlap still pay the fixed cost twice to find the same defect twice. Spawn for independence, not for tidiness.

The measurement I still owe you is the cache-read versus cache-creation split from the same transcript fields, which would turn the dollar ratio from an argument into a number. I have not run it yet.

Primary sources for this correction:

https://docs.claude.com/en/docs/build-with-claude/prompt-caching

DEV Community: Rulestack

Your GitHub Actions cron fires less often than you declared: what we measured and how to design for it

What we measured

What this breaks

Design rules that survive the throttling

The check worth running on your own repo

A Claude Code subagent costs ~436k tokens before it reads a single file: measured, with the break-even math

Where 436k tokens go

The break-even question nobody asks

The three-line audit for your own repo

Rules of thumb we actually follow now

When your MCP tool fails: errors, hangs, and empty results — what Claude Code actually does with each

Failure mode 1: the loud error (the good one)

Failure mode 2: the hang (bounded by more timers than you think)

Failure mode 3: the empty success (the one that poisons the run)

The checklist

We cut our CLAUDE.md from 548KB to 34KB: what loads when, measured — and the commit gate that keeps it small

The mechanics that make splitting worth it

What we actually moved

Enforcement, because advice doesn't persist

The failure the gate could not catch

A checklist, if your file is heading past 100KB

Your MCP server is configured but Claude can't see it: reading claude mcp list status

First: Added means written, not connected

The most common cause: scope

⏸ Pending approval — the .mcp.json case

✘ Rejected and the two lists that look alike

Statuses that are not failures

When the status is ✘ Failed to connect

The order I actually check

CLAUDE.md @-imports: how paths resolve, how deep they go, and why yours silently did not load

What an import actually does

1. Relative paths resolve from the importing file, not your working directory

2. Recursion stops at four hops

3. Backticks switch imports off

4. Imports pointing outside the project need approval — and you only get asked once

The AGENTS.md case, since everyone hits it

Personal instructions, and the worktree trap

A five-step check when an import didn't land

Claude Code fork vs subagent: what /fork, /subtask, and subagent_type: "fork" each copy

Three different things in Claude Code are called "fork"

What "inherits the prompt cache" actually buys you

When you still want a cold subagent

The other default in that line

How to check what you are getting

Auto mode is now Claude Code's default: what the classifier approves, and how to switch back

What changed, precisely

What auto mode actually is

The defaults that surprise people

Keeping human checkpoints

How to switch back

When it blocks something you wanted

The plan mode connection

Claude Code plan mode: what it actually blocks, what still runs, and what approving switches you into

What plan mode is

Three ways in, one way out

What still runs while you plan

The approval prompt, decoded

Making plan mode the default

The two gotchas that actually bite

When to reach for it

Your CLAUDE.md loads into every subagent — the context multiplier nobody budgets for

What actually loads into a subagent at startup

The two exemptions — and why you can't add more

The arithmetic

Measure yours in 30 seconds

Shrinking the multiplicand

The checklist

AGENTS.md vs CLAUDE.md vs .cursorrules: what Cursor actually reads now (and in what order)

The four file kinds, in one table

1. .cursor/rules/*.mdc — the primary mechanism

2. AGENTS.md — now nested

3. CLAUDE.md — Cursor reads it, and reads it unconditionally

4. .cursorrules — formally legacy

Precedence: who wins when rules conflict

What I'd actually do with this

What a Claude Code subagent actually costs: measuring the ~436k-token fixed overhead

The experiment

Where the tokens actually go

How to measure this yourself

First: `Added` means written, not connected

`⏸ Pending approval` — the `.mcp.json` case

`✘ Rejected` and the two lists that look alike

When the status is `✘ Failed to connect`

1. `.cursor/rules/*.mdc` — the primary mechanism

2. `AGENTS.md` — now nested

3. `CLAUDE.md` — Cursor reads it, and reads it unconditionally

4. `.cursorrules` — formally legacy