headroom.walls.sh · agent

Claude Code agent mode

How autonomous subagents work, how they share your session and weekly quota, and what to watch when running long agent tasks.

What agent mode is

When you give Claude Code a complex multi-step task, it can decompose the work and spawn subagents — separate Claude instances that each handle a focused subtask in parallel or in sequence. This is agent mode (sometimes called agentic mode).

Examples that trigger subagent spawning:

• Refactoring multiple files across a large codebase
• Running a research task that reads many files before writing
• A long autonomous loop (like /loop or a custom /go command)
• Any task where Claude Code decides parallel work is faster

Each subagent is a full Claude invocation — it sees its own context window and produces its own output. The orchestrating session coordinates them and synthesizes the results.

How subagents affect your rate limits

Every subagent draws from the same session (5h) and weekly (7d) usage pool as your main session. There's no separate quota for agents — it's one shared meter.

This is the main reason to monitor your usage before starting an agent task. The worst case: you launch an autonomous agent at 70% session usage, it runs for 20 minutes, and hits the limit mid-task with no clean stopping point.

Check usage before starting an agent task

Run /usage inside any Claude Code session before a big agentic task:

/usage
# Session (5h):  34% used · resets in 2h 44m
# Weekly (7d):   61% used · resets in 2d 7h

Or read the file directly:

jq '{session: "(.sessionUsagePct | floor)%", weekly: "(.weeklyUsagePct | floor)%", sessionResetsIn: "(.sessionResetSec / 3600 * 10 | floor / 10)h"}' ~/.claude/headroom-usage.json

Rule of thumb: don't start a long agent task above 60% session. If the task is critical, wait for a reset.

→ 5-hour session window explained · 7-day weekly window explained

The --print flag for scripted agents

For non-interactive agent use in scripts or CI, use --print to get Claude Code's response on stdout and exit:

claude --print "Analyze the security of this file: $(cat src/auth.ts)"

Combine with --model to use a lighter model for scripted tasks and preserve session budget for interactive work:

claude --model claude-haiku-4-5-20251001 --print "Summarize the diff: $(git diff HEAD~1 --stat)"

Custom agent commands

You can define your own agentic workflows as slash commands in .claude/commands/. Each .md file becomes a /command-name with the file content as the prompt template:

# .claude/commands/audit.md
Do a full security audit of the codebase:
1. Check for SQL injection in all database queries
2. Review authentication and session handling
3. Look for hardcoded credentials or secrets
4. Check dependency versions against known CVEs
Report each finding with file + line number and severity.

Run with /audit. These commands can trigger multi-step agentic flows automatically.

→ All slash commands reference

Autonomous loops

Claude Code's /loop command runs a prompt repeatedly, self-pacing between iterations. An autonomous loop that spawns subagents in every iteration can consume your weekly limit across a day if left running unsupervised.

Before running a long autonomous loop:

• Check weekly usage — not just session
• Set a time limit or iteration cap if possible
• Monitor the weekly meter, not just session (session resets every 5h; weekly doesn't)

→ 7-day weekly limit — the slow drain trap

Monitoring usage during agent runs

Because agent tasks run unattended, you can't manually run /usage mid-task. Two approaches:

Shell poll (while the agent runs in another pane)

watch -n 30 "jq '{s: "(.sessionUsagePct | floor)%", w: "(.weeklyUsagePct | floor)%"}' ~/.claude/headroom-usage.json"

Menu bar (always visible, no extra window)

Headroom shows your session (5h) and weekly (7d) usage as a live % in the macOS menu bar. It updates as Claude Code runs — even during unattended agent tasks. Color-coded: calm → amber at 70% → red at 90%. No polling command, no extra terminal pane.

brew install --cask patwalls/tap/headroom

The meter updates because Headroom reads ~/.claude/headroom-usage.json, which Claude Code refreshes during active sessions including agent runs. Zero network calls.

→ Rate limits explained
→ When do limits reset?
→ /compact to free context mid-agent
→ Claude Code tips and tricks