How to start Claude Code subagents without CLAUDE.md using omitClaudeMd

Custom subagents in Claude Code load your user, project and local CLAUDE.md files at startup, just like the main session. If a subagent only needs the delegation prompt, add omitClaudeMd: true to its definition so it starts without those files. The built-in Explore and Plan agents already work this way.

Add one line to the frontmatter of an agent file under .claude/agents/.

---
name: lean-scanner
description: Scans files and returns only a summary of what it found
tools: Read, Grep, Glob
model: haiku
omitClaudeMd: true
---
Read only the files in the delegated scope and report findings briefly, with file paths.

The field has the same name when you pass agents as --agents JSON.

claude --agents '{"lean-scanner":{"description":"Scans files and summarizes findings","prompt":"Report findings briefly, with file paths","tools":["Read","Grep","Glob"],"omitClaudeMd":true}}'

Listing only the tools it needs in tools also leaves out MCP tools, so it runs lighter still. Managed policy files still load. A subdirectory's CLAUDE.md and path-scoped rules (.claude/rules) also still load when the subagent works with files there.

The main session reads the results with your full CLAUDE.md, so most rules don't need to reach the subagent. Restate only the rules that must hold (for example, don't touch vendor/) in the delegation prompt.

The field is ignored when the agent runs as the main session agent via --agent. Requires Claude Code v2.1.271 or later.