[FEATURE] Per-agent frontmatter option to skip CLAUDE.md / git status injection for custom subagents
Problem
Per the sub-agents docs, every subagent except the built-in Explore and Plan loads all CLAUDE.md files (user-global, project, local) and the parent session's git status snapshot at startup, and the docs explicitly state:
There is no frontmatter field or per-agent setting to change which agents skip them.
For narrow, single-purpose custom agents this context is pure overhead. A typical example: a Haiku-based "runner" agent whose only job is to execute build/test/lint commands and report back pass/fail. It needs none of the user's global instructions, project conventions, or git status — yet it pays the token cost and context-window occupancy for all of them on every invocation.
Proposal
Add an opt-out in the agent definition frontmatter, e.g.:
---
name: runner
description: Runs build/test commands and reports results
model: haiku
tools: Bash, Read, Grep, Glob
loadClaudeMd: false # skip CLAUDE.md injection for this agent
loadGitStatus: false # skip git status snapshot (optional, separate flag)
---Naming is up to you — a single context: minimal style field that matches the existing Explore/Plan behavior would also work.
Benefits
- Smaller initial context and lower cost for high-frequency, cheap-model agents
- Faster effective startup for fire-and-forget agents
- Prevents instructions written for the main agent (language/style rules, delegation policies, workflow rules) from leaking into single-purpose agents where they are irrelevant or even contradictory
- The mechanism already exists internally (Explore and Plan use it) — this only exposes it to custom agent definitions
Workarounds today
- Use Explore for read-only research (skips CLAUDE.md), but there is no equivalent for command-execution or write-capable agents
- Keep CLAUDE.md small — limited, since it serves the main agent
Related
- #24773 asked for the inverse (use the sub-agent MD instead of CLAUDE.md as primary context); this request is narrower: just an opt-out flag per agent.
3 Comments
Strong +1, with measured data from a large project (root
CLAUDE.md~31K tokens).Sub-agent / workflow fan-out is the dominant token cost, and it's driven almost entirely by this: across ~3,900 sub-agent contexts, 80.7% re-paid the full ~31K
CLAUDE.mdon bootstrap (median first-input ~114K tokens). A controlled trivialExplorerun — the onlyCLAUDE.md-free path today — measured ~15K vs ~114K, i.e. ~99K tokens/agent. BecauseExplore/Planare hardcoded read-only, there is no lean path for write-capable custom agents, so the win is unreachable exactly where most fan-out lives.Concrete ask (same as this issue): a per-agent-definition frontmatter option controlling project-memory injection, e.g.
nonefor read-only research/verify fan-out,full(default) unchanged.Even a plain boolean
skipProjectMemory: truefor custom agents would capture most of the benefit. Today the only workarounds are trimming the rootCLAUDE.md(helps every agent but bounded) or running an out-of-band Agent-SDKquery()withsettingSources: []. For any project with a substantialCLAUDE.mdand heavy subagent use, this is a large, compounding saving.Adding a different axis to @Alex00000111's numbers rather than more of the same — their fan-out measurement is stronger than anything I can offer on cost, so this is about which part of the payload is the problem.
The distinction that makes this worse than "unneeded for this task": in a project whose
CLAUDE.md/@importchain is written partly for a coordinating agent — dispatch rules, merge and push gating, how to hire and brief other agents, cross-repo sequencing — a subagent is not paying for content it merely doesn't need right now. It is paying for instructions it can never act on, for any task, because a subagent does not start or stop itself; those decisions structurally belong to the orchestrator. So the ceiling on what a per-agent opt-out could reclaim is not "whatever this agent happens not to use" — there is a floor of content that is unusable by every subagent, always.Measured on our own multi-repo setup: per-spawn governance payload 33K–55K tokens, of which ~13K–17K is orchestrator-only — roughly two thirds of the extra over a bare agent is structurally unusable by the agent receiving it. Method differs from Alex's (byte-sum over the
CLAUDE.mdchain plus the auto-memory index, tokens estimated), so treat it as a complementary ratio, not a second cost figure./contextinside a session is the CLI's own authoritative breakdown and would beat both estimates.Re-verified today, still current. The sentence this issue quotes is verbatim in
docs/en/sub-agents.md→ Manage subagent context → What loads at startup: "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." The 15-field frontmatter table in the same doc has no matching field, and a full-text search ofCHANGELOG.mdonmain(top entry v2.1.220) forloadClaudeMd,skipClaudeMd,instructionScope, or acontext: minimal-style key returns nothing.On the fix shape: #77261 asks for the same opt-out on the auto-memory axis, and it is worth noting the two are not independent — we observe auto-memory arriving in custom subagents today (details in that issue). Alex's
memoryScope: full | none | <path>and a CLAUDE.md switch would end up as two knobs over one question; a single field spanning both axes — mirroring the existing Explore/Plan behaviour at the lean end — may age better. Either shape solves what is described here.Reproduction, if useful: spawn any custom subagent and, before it uses a tool, ask it to report whether specific strings from your
CLAUDE.mdchain are already in its context.I run with a single workspace and nested projects with an orchestrator that manages it all. All the subagents do not need the full claude.MD injected as they never use it and it can cause some odd behaviour. So this is my +1 for this level of control on what an agent reads as its instructions. I am using the cli if that helps at all. Same issue as https://github.com/anthropics/claude-code/issues/78974#issuecomment-5082088587 describes.