Feature: Configurable effort levels for plan/spin commands, swarm orchestrator, and agents

[acreeger]

Diagnostic Information

Property	Value
CLI Version	0.13.2
Node.js Version	v22.17.0
OS	darwin
OS Version	25.2.0
Architecture	arm64
Capabilities	web
Claude CLI Version	2.1.81 (Claude Code)

Context: How Claude Code effort levels work (source code analysis)

Analysis of the Claude Code v2.1.81 source to understand how effort levels propagate, for reference when implementing configurable effort in iloom.

Valid effort levels

Claude Code supports these effort levels: low, medium, high, max (or integer values).

• low → "Quick, straightforward implementation with minimal overhead"
• medium → "Balanced approach with standard implementation and testing"
• high → "Comprehensive implementation with extensive testing and documentation"
• max → "Maximum capability with deepest reasoning (Opus 4.6 only)"

How effort flows to the API

Effort is sent as output_config: { effort: "low"|"medium"|"high"|"max" } in the Messages API request body. This is a server-side parameter that controls Claude's reasoning depth.
Key resolution logic (NJ_ function):

1. CLAUDE_CODE_EFFORT_LEVEL env var (highest priority, "unset"/"auto" clears it)
2. Session effort (set via /effort command)
3. Model default (e.g. Opus 4.6 defaults to "medium" for new claude.ai users)
   Critical: "max" is only kept as "max" for Opus 4.6. For all other models, it is silently downgraded to "high".

How subagents inherit effort

When the Agent tool spawns a subagent, the effort is resolved from app state in the c0 function:

let effortValue = agentDefinition.effort !== undefined
? agentDefinition.effort // agent's own frontmatter wins
: appState.effortValue; // otherwise inherit parent's

So subagents inherit the parent's effort level unless overridden.

Per-agent effort override

Effort can be overridden per-agent via frontmatter in .claude/agents/*.md files:

---
name: my-researcher
description: Research agent that runs at low effort
effort: low
---

The schema accepts:

effort: "low" | "medium" | "high" | "max" | <integer>

This also works in skill/command .md files and JSON agent definitions in settings.

Thinking tokens vs effort

The older ultrathink keyword mechanism (setting budget_tokens: 31999) still exists but effort levels (output_config.effort) are the primary mechanism in v2.1.81+. They are server-side and handled by the API, not by adjusting thinking token budgets client-side.

Proposed feature for iloom

Requirements

1. Global effort setting — configurable default effort level for il plan and il spin commands (e.g. via iloom config or CLI flag --effort)
2. Per-command override — il plan --effort low / il spin --effort max
3. Swarm orchestrator — ability to set effort for the orchestrator agent separately from worker agents
4. Per-agent effort — different agents in a swarm could run at different effort levels (e.g. the planner at high, implementers at medium, reviewers at low)
5. Environment variable support — respect CLAUDE_CODE_EFFORT_LEVEL for compatibility

Implementation notes

• Since effort is passed via output_config.effort in the API, iloom can set this when constructing API requests or by setting agent frontmatter
• For Claude Code-backed agents, iloom can set effort via the agent definition's effort frontmatter field
• The "max" level should probably warn or auto-downgrade when not using Opus 4.6, matching Claude Code's behavior
• Consider defaulting to "high" for cost/speed optimization in swarm workers, with documentation suggesting "max" for critical-path agents like analyzers and planners