headroom.walls.sh · tips

Claude Code tips and tricks

12 practical habits for power users — from rate limit management to context hygiene and shell integration.

01 Always know your headroom before a big task

Claude Code has two invisible limits: a 5-hour session window and a 7-day rolling weekly cap. Both stop you cold with no warning mid-task. Before you start a long refactor, check where you stand:

cat ~/.claude/headroom-usage.json | jq '{session: .sessionUsagePct, weekly: .weeklyUsagePct, resetIn: .sessionResetSec}'

Or run /usage inside any Claude Code session for the same numbers. If you're above 80% on either, consider finishing or queuing the task for after a reset.

02 Use /compact before long tasks, not after you're stuck

Claude Code's context window is separate from your rate limit. When context fills up, Claude Code auto-compacts — but mid-task compaction can lose important state. Run /compact yourself when:

• You're about to pivot to a new subtask
• The session has been going 30+ minutes
• You're seeing slower, less precise responses

Compaction summarizes completed work but preserves your open tasks and current goal. Your rate limit meters don't change — only context gets cleaned.

→ Full guide to /compact

03 Time your sessions around the 5-hour window

The session window is a rolling 5 hours — it doesn't reset at midnight. The earliest tokens you sent this session expire 5 hours after they were sent, gradually freeing capacity. If you hit 100% and need to work immediately, the reset isn't all-or-nothing:

cat ~/.claude/headroom-usage.json | jq '.sessionResetSec / 60 | floor | "(.) minutes until oldest tokens expire"'

Starting a session in the morning gives you a clean 5-hour window. Late-night sessions often inherit usage from evening work.

→ Deep dive: 5-hour session window

04 Watch both windows, not just the one you hit

Most people notice the 5-hour session limit first — it hits fast. But the 7-day weekly cap is the real trap: it drains slowly over a week and you won't notice until Thursday when you need to ship. Heavy Monday work can leave you rate-limited by Wednesday.

cat ~/.claude/headroom-usage.json | jq '{weekly: .weeklyUsagePct, weeklyResetDays: (.weeklyResetSec / 86400 | . * 10 | floor / 10)}'

→ Deep dive: 7-day weekly window

05 Commit frequently — Claude Code's memory is the session

Claude Code maintains state within a session, but a new session starts fresh. Commit your work often so if you have to let a session expire, you're not rebuilding context from scratch. Good git hygiene doubles as Claude Code hygiene.

git add -p && git commit -m "wip: checkpoint before context reset"

06 Use --print for scripts and CI

Don't wrap Claude Code in expect or interactive hacks for automation. The --print flag outputs the response to stdout and exits — perfect for CI pipelines, shell scripts, or one-shot queries:

claude --print "Summarize the changes in this diff: $(git diff HEAD~1)"

Combine with --model to use a cheaper model for scripted tasks and preserve your limit budget for interactive work.

07 Check the model before a big session

Claude Code defaults to a capable model, but different models have different costs and speed profiles. A long refactor session on Sonnet burns budget faster than the same session on a lighter model. Check what you're on:

cat ~/.claude/headroom-usage.json | jq '.modelName'

Switch with /model inside a session. Use a lighter model for exploration; escalate to a heavier model for the final implementation pass.

→ Model selection guide

08 Add usage to your shell prompt

The same data that Headroom shows in the menu bar is available for your shell prompt. A one-liner that shows session % in your PS1:

export PS1='$(jq -r ""CC (.sessionUsagePct|floor)%"" ~/.claude/headroom-usage.json 2>/dev/null || echo "CC --") $ '

For Starship users, there's a full custom module that color-codes based on thresholds. For tmux, there's a status-bar integration.

→ Starship module · tmux status bar · Shell prompt guide

09 Batch similar tasks to reduce context overhead

Each new session starts with zero context, which is both a reset and a cost. When you have a set of similar tasks (e.g., adding tests to multiple files), batch them into one session instead of starting fresh for each. Claude Code can hold multiple files and tasks in context simultaneously — use that.

claude "Add unit tests to src/auth.ts, src/session.ts, and src/user.ts — all three"

10 Set threshold notifications so limits don't surprise you

macOS's native notification system can fire when your usage crosses a threshold. A LaunchAgent that checks every 5 minutes and fires a notification when session usage crosses 80%:

cat ~/.claude/headroom-usage.json | jq -r 'if .sessionUsagePct > 80 then "warn" else "ok" end'

→ Full threshold notification setup

11 Use /cost to audit expensive sessions

Run /cost inside any session to see the token breakdown for that conversation. If a session is burning through budget faster than expected, /cost often reveals a file that's being re-read on every turn or a long context window that should have been compacted.

→ Cost tracking guide

12 Pipe usage data anywhere with jq

The ~/.claude/headroom-usage.json file (written by Claude Code's statusLineHook) is plain JSON. You can pipe it anywhere — Raycast, Alfred, a shell prompt, a tmux bar, a cron alert, a web dashboard:

cat ~/.claude/headroom-usage.json
# {
#   "sessionUsagePct": 34.2,
#   "weeklyUsagePct": 61.8,
#   "sessionCost": 0.42,
#   "modelName": "claude-sonnet-4-6",
#   "sessionResetSec": 9847,
#   "weeklyResetSec": 198432
# }

→ Hook setup · Raycast Script Command · Alfred workflow

One app that implements tips 01, 04, and 07 for you

Headroom is a free macOS menu bar app that keeps your Claude Code session (5h) and weekly (7d) usage visible at all times — color-coded before a limit stops you. No config, no API key, no network calls. It reads the same local file the tips above use.

brew install --cask patwalls/tap/headroom

Or download directly. Free, MIT, ~267 KB, native Swift, signed + notarized.