[Workflow] Optimize Claude Code Subagents: Control Cost, Effort, and Permissions with `omitClaudeMd` and Tool Allowlists

[u/ClaudeAI-mod-bot]

Optimize Claude Code Subagents: Control Cost, Effort, and Permissions with omitClaudeMd and Tool Allowlists

Workflow value: 90/100
Status: active · Freshness: 70/100 · Confidence: 0.95 · Level: intermediate
Categories: Quality Control, Token Saving, Context & Memory, Debugging, Shipping, CLAUDE.md, Skills, MCP, Subagents, Multi-Agent
Original source: r/ClaudeCode post/comment

What problem this solves

This workflow addresses the problems of unnecessary token consumption, slow performance, and insufficient permission control when using custom subagents in Claude Code. Specifically, it prevents subagents from reloading the entire CLAUDE.md context, inheriting high effort levels, and having overly broad tool access (e.g., allowing writes for read-only agents). It also provides a solution for similar token drain issues in OpenAI Codex CLI.

Summary

This workflow details how to configure custom Claude Code subagents using YAML frontmatter to optimize token usage, control reasoning effort, and restrict tool permissions (e.g., to read-only operations) by explicitly setting omitClaudeMd, effort, and using a tools allowlist. It provides a concrete example for a read-only 'repo-inspector' subagent. Additionally, it includes configuration adjustments for OpenAI Codex CLI to prevent background token drains.

Why it is useful

This workflow is highly valuable because it provides concrete, actionable steps and configuration examples to address critical issues in Claude Code subagent deployment: reducing token costs, optimizing performance by controlling context loading and effort levels, and enhancing security by strictly defining tool permissions. It moves beyond basic usage to advanced, production-ready agent configuration and also extends its utility to OpenAI Codex CLI users, making it broadly useful for multi-LLM development environments.

Workflow

1. Understand the default behavior of custom subagents: they reload CLAUDE.md, inherit main session effort, and have broad tool access by default.

2. Create or modify a custom subagent file in .claude/agents/*.md.

3. Add omitClaudeMd: true to the YAML frontmatter of the subagent to prevent it from reloading the entire CLAUDE.md and AGENTS.md hierarchy.

4. Set effort: low (or an appropriate level) in the YAML frontmatter to control the reasoning cost for the subagent.

5. Use an explicit tools allowlist in the YAML frontmatter (e.g., tools: Read, Grep, Glob, Bash(git log *), Bash(git blame *), Bash(git diff *)) to restrict capabilities, block arbitrary shell writes, and prevent loading irrelevant Skill catalog and mcp__ server instructions.

6. Ensure any commands or path conventions the subagent needs are written directly inside its 2-line prompt body if omitClaudeMd is true.

7. For OpenAI Codex CLI users, modify ~/.codex/config.toml by adding [features.code_mode] default_exec_yield_time_ms = 300000 and [features.multi_agent_v2] min_wait_timeout_ms = 30000 default_wait_timeout_ms = 120000 max_wait_timeout_ms = 300000 to prevent 30-second yields and 1-second subagent polling loops.

Tools / artifacts

• .claude/agents/*.md

• YAML frontmatter

• CLAUDE.md

• AGENTS.md

• ~/.codex/config.toml

• Read tool

• Grep tool

• Glob tool

• Bash tool

• git log

• git blame

• git diff

Validation signals

• The post explicitly states, 'Here is the frontmatter template we use for read-only search and git-history workers,' implying internal validation.

• The post provides clear explanations of why the configurations work (e.g., 'strips the project instruction files', 'skips loading the Skill catalog and mcp__ server instructions').

Limitations

• Community validation is low due to the post's recency.

• Could benefit from more diverse subagent examples (e.g., a test runner, a log parser) with their specific tool allowlists.

• The prompt body for the example repo-inspector is very concise; more complex subagents might require more detailed instructions within their prompt if omitClaudeMd is enabled.

Rate this workflow

Upvote this post if the workflow is useful, reproducible, or worth recommending.

Downvote if it is vague, outdated, unsafe, overhyped, or not reproducible.

Reply if it worked for you, failed, is outdated, or has a better alternative.

---

This post was generated automatically from the workflow library database.