breather
Stop AI brain fry. Automatic break reminders for Claude Code.
AI coding tools make you a 100x developer, great! AND make it 100x harder to stop. HBR calls it "AI brain fry": the mental fog, headaches, and decision fatigue from nonstop AI-assisted development. UC Berkeley found the developers burning out first are the power users, not because anyone pressured them, but because they couldn't stop doing more.
Sound familiar? Breather is the brake pedal your AI coding setup is missing.
How it works
After a quick one-time setup (/breather:setup), breather runs automatically. No discipline required. That's the point. If you had the discipline to take breaks, you wouldn't need this.
Always on (zero effort)
| Feature | What it does |
|---|
| Daily fatigue tracking | Tracks total AI work time across ALL your Claude Code sessions, not just one terminal |
| Status line | breather session: 45m | today: 3h 12m | 1 break. Session time is info, daily total goes green/yellow/red. |
| Smart nudges | Weaves break suggestions into Claude's responses at 25/50/90 min thresholds based on daily total |
| Inactivity detection | Long gaps (30+ min) between prompts are detected as breaks automatically. No commands needed. |
| Velocity detection | Flags rapid-fire prompting (5+ prompts/min) as a sign of reactive coding |
| Overnight reset | 8+ hour gap = fresh start. Yesterday's fatigue doesn't carry over. |
| Session logging | Logs every session to JSONL for future pattern analysis |
When you're ready to stop (or stretch)
| Command | What it does |
|---|
/breather:stretch | Quick break. No context saving, no ceremony. Partial fatigue reset (+10 min). |
/breather:pause | Full break. Saves YOUR mental context (what you were doing, where you left off, what's next). Fully resets the fatigue clock. |
/breather:back | Restores YOUR mental context. Not a code dump, but what you need to know to pick up where you left off. 5 seconds to get back in flow. |
/breather:checkin | Session + daily stats. Honest numbers, no guilt. |
/breather:reflect | End-of-session summary: what you shipped, open threads, weekly trends. |
You don't need to remember commands
Breather detects long gaps between prompts automatically. If you step away for 45+ minutes, it counts as a break. No commands needed.
/breather:pause is there for when you want the context-saving full stop (so /breather:back can restore exactly where you were). For shorter breaks, /breather:stretch is a quick one-liner.
The research behind it
This isn't vibes-based. Every threshold is backed by research:
The key insight
The fear of losing context is what keeps developers from taking breaks.
If resuming costs 20 minutes of "where was I?", you'll skip the break. If /breather:back restores YOUR mental context in 5 seconds, breaks are free. That's the lever.
Multi-session aware
Most devs run 3-8 Claude Code terminals simultaneously. Breather tracks fatigue globally via a single shared state file:
- One
state.json tracks all fatigue, breaks, and nudge state
- A break in one window resets the fatigue clock everywhere
- No double-counting. Three terminals open for an hour = 1 hour, not 3.
The number that matters is your total AI work today, not how long one terminal has been open.
Nudge thresholds
Based on daily total since last break across all sessions:
