Correctly Configure Claude Code Subagent Effort and Model Parameters

Workflow value: 85/100
Status: active · Freshness: 70/100 · Confidence: 0.95 · Level: intermediate
Categories: Quality Control, Context & Memory, Debugging, CLAUDE.md, Subagents
Original source: r/ClaudeCode post/comment

What problem this solves

Users often incorrectly assume that Claude Code subagent effort can be set at spawn time, leading to subagents running at unintended effort levels or requiring redundant agent files. This workflow clarifies the correct configuration for subagent effort and model parameters.

Summary

This workflow details how to correctly configure Claude Code subagent effort and model parameters. It clarifies that 'effort' must be defined in the subagent's .claude/agents/<name>.md file, while the 'model' can be overridden at spawn. It also highlights critical gotchas, such as agent files being read only at session start and the need to verify actual effort via JSONL transcripts rather than asking the subagent directly.

Why it is useful

This workflow is valuable because it addresses a critical misunderstanding in Claude Code subagent configuration, preventing users from wasting effort or resources due to incorrect settings. It provides clear, actionable steps and explains the underlying mechanics, leading to more efficient, predictable, and optimized subagent behavior. The practical benefit of reducing redundant agent files is also a strong indicator of its utility.

Workflow

1. Identify the need for a subagent with specific effort and/or model settings.
2. Create or modify the subagent's definition file at .claude/agents/<name>.md.
3. Set the desired effort: level (e.g., high, medium, low) in the frontmatter of the agent file.
4. Optionally, omit model: from the agent file to inherit the parent session's model.
5. Spawn the subagent, passing model: as an argument if a specific model override is desired (e.g., Agent({ subagent_type: "claude", model: "haiku", prompt: "..." })).
6. Restart the Claude Code session if any agent files were created or edited, as changes are only read at session start.
7. Verify the subagent's actual effort by inspecting its JSONL transcript under ~/.claude/projects/ for the "effort" and "perTurnEffort" fields, rather than asking the subagent directly.

Tools / artifacts

• Claude Code session
• Subagent definition files (.claude/agents/<name>.md)
• Subagent JSONL transcripts (~/.claude/projects/)
• VSCode extension LoopBoard (used for discovery)
• GitHub repository (for example agent files)

Validation signals

• Direct observation of subagent JSONL transcripts showing actual effort ("effort":"high")
• Comparison of expected vs. actual behavior (passing effort: "low" at spawn had no effect)
• Successful reduction of agent files from seven to three by applying the correct configuration strategy.

Limitations

• Low community engagement (score and comments) at the time of evaluation.
• Verification requires manual inspection of JSONL files, which could be cumbersome for complex multi-agent setups.

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.