Claude Code Streak Tracker 🔥

Just show up every day. Track your daily Claude Code usage with a simple streak system.

Like going to the gym - consistency beats intensity. This tracker helps you build the habit of using Claude Code daily, naturally discovering more valuable use cases along the way.

Quick Start

📖 Detailed Installation Guide →

One-Line Install

curl -fsSL https://raw.githubusercontent.com/ussumant/claude-code-streak-tracker/main/install.sh | bash

Manual Install

git clone https://github.com/ussumant/claude-code-streak-tracker.git
cd claude-code-streak-tracker
./install.sh

What You Get

🔥 Streak Tracking + Daily Quota Progress

Track consistency + daily pace - see your progress in real-time! 📊

1. Status Line (Always Visible)

Settings  Status  Config  Usage  │ 🔥 4 day streak | 📊 43/15 today

2. Welcome Message (Every Session)

🔥 12 day streak
⭐ Best: 18 days

3. /streak Command (Full Details)

🔥 12 day streak

October 2024
Mo Tu We Th Fr Sa Su
    🔥 🔥 🔥 🔥 🔥
🔥  🔥 ⬜ 🔥 🔥 🔥 🔥
🔥  🔥 🔥 🔥

⭐ Best: 18 days
📊 Total active: 23 days

How It Works

• Automatic Tracking: Analyzes ~/.claude/history.jsonl
• Streak Day: At least 1 Claude Code conversation
• Smart Calculation: Current streak + best streak + 30-day calendar
• Performance: <50ms with intelligent caching
• Smart Nudges: Gentle reminders when your streak needs attention (optional)

Milestones

Celebrate achievements as you build the habit:

• 🎉 7 days - Week Warrior
• 🎊 14 days - Two weeks strong!
• 💎 30 days - Month mastery!
• 🏆 50 days - Legend status!
• 🚀 100 days - Absolutely phenomenal!

Smart Nudge System

Context-aware nudges that help you code better, not just maintain streaks.

Unlike generic reminders, our nudge system analyzes your real developer activity to offer help when you actually need it.

What Triggers a Nudge?

Priority System: Productive flow → Bug spiral → Analysis paralysis → Other signals → Streak reminders

🟢 Productive Flow (suppress all nudges)

• Recent commit + active editing? → No nudges (don't interrupt!)
• Steady progress on current task? → No nudges (you're in the zone)

🔴 Bug-Fixing Spiral (highest priority)

• Same test command failed 3+ times in 45 min? → "npm test failed 5 times in 30 min. Ask: 'Why is this failing?'"
• Repeated build failures? → "Debugged for 45 min with 4 failures. Want Claude's help?"

🟠 Analysis Paralysis (high priority)

• 8+ file reads/searches with no commits in 45 min? → "Explored 12 commands in 35 min with no commits. Ready to build?"
• Lots of exploration, little building? → "Reading code for 40 min. Ask: 'Where should I start implementing?'"

🟡 Stuck Signals

• Been working on same file for 2+ hours with no commit? → "Stuck on auth.ts? Claude can review your approach"
• 5+ git status calls in 10 minutes? → "Ready to commit or need a sanity check?"
• Lots of grep/find commands? → "Searching through code? Ask Claude to explain the structure"
• Bouncing between directories? → "Lost in the codebase? Claude can help navigate"

🔵 Victory Moments

• Just committed code? → "Nice commit! Document what you learned while it's fresh?"
• Tests just passed? → "Testing complete? Document what this test covers"

🟣 Work Transitions

• Returning after 2+ hour break? → "Welcome back! Pick up where you left off on feature/auth?"
• Late night coding (10 PM+)? → "It's 11:30 PM. Quick ask: 'Review my changes before I commit?'"
• Context switching (5+ files in 30 min)? → "Bouncing between files? Ask: 'How do auth.ts and api.ts connect?'"

⚪ Streak Reminders (fallback only)

• Only used when no real developer signal detected
• High risk: End of day with no activity
• Milestones: 1 day away from achievement

Why This Works

Traditional streak trackers focus on vanity metrics. We focus on actual work patterns:

• ✅ Detects bug-fixing spirals → Suggests asking Claude to debug before you waste more time
• ✅ Detects analysis paralysis → Nudges you to start building instead of just reading
• ✅ Respects productive flow → Won't interrupt when you're making steady progress
• ✅ Suggests asking Claude when you're stuck → Real value, not vanity metrics
• ✅ Encourages documentation after victories → Builds knowledge
• ✅ Helps you resume work after breaks → Saves time
• ❌ Doesn't nag about maintaining streaks → Not gimmicky

Nudge Features

• Analyzes shell history and git activity locally (privacy-first)
• Context-based messages with specific file names and suggestions
• macOS notifications with actionable next steps
• Respects quiet hours (11 PM - 7 AM)
• Max 2 nudges per day
• Flow-state aware (won't interrupt active work)

Enable Nudges

# Install hourly check (runs in background)
(crontab -l 2>/dev/null; echo "0 * * * * ~/.claude/nudge-scheduler.sh") | crontab -

# Test nudge engine manually
node ~/.claude/nudge-engine.js

# Check what signals are detected right now
node ~/.claude/context-analyzer.js

Example Nudges

Bug-Fixing Spiral:

• ❌ "Keep trying!"
• ✅ "npm test failed 5 times in 30 min. Ask: 'Why is this failing?'"

Analysis Paralysis:

• ❌ "Time to code!"
• ✅ "Explored 12 commands in 35 min with no commits. Ready to build?"

Productive Flow:

• ❌ "Your streak needs attention!"
• ✅ No nudge (you're in the zone - no interruption)

Stuck on Task:

• ❌ "Your 12-day streak expires in 4 hours!"
• ✅ "Been on auth.ts for 2h? Claude can review your approach."

Victory Moment:

• ❌ "Keep going!"
• ✅ "Just committed! Add a comment explaining the approach?"

Daily Quota & Pace Tracking

Real-time feedback on whether you're on track to hit your daily usage quota.

How It Works

The system tracks your conversations throughout the day and shows whether you're ahead, on pace, or behind schedule.

Status Line shows progress:

🔥 4 day streak | 📊 43/15 today

Quota Configuration

Default Settings:

• Daily quota: 15 conversations
• Working hours: 7 AM - 11 PM
• Pace check threshold: -20% (nudges when 20%+ behind)

Customize in ~/.claude/nudge-config.json:

{
  "dailyQuota": 15,
  "quotaWorkingHours": {
    "start": 7,
    "end": 23
  },
  "quotaPaceNudgeThreshold": -20,
  "features": {
    "quotaPaceChecks": true
  }
}

Pace-Based Nudges

Behind pace (20%+ behind):

• "60% of day done, only 40% to quota. Time to tackle that task?"
• "Behind pace today - 5/15 conversations. What are you working on?"
• "Need 10 more conversations to hit quota. Quick win?"

Ahead of pace (15%+ ahead):

• "Crushing it! 12/15 conversations - 20% ahead of schedule 🔥"
• "Way ahead of pace! 25% ahead - keep this energy! ⚡"

On track:

• No nudge (you're doing fine!)

/streak Command Shows Full Details

🔥 4 day streak

## Today's Progress
📊 43/15 conversations (100% to quota)
⏱️ 48% through working hours
✅ 52% ahead of pace! Crushing it! 🔥

October 2024
...

Why This Works

• Actionable in real-time: Know if you need to pick up the pace
• Respects working hours: Only checks pace during 11 AM - 8 PM
• Celebrates wins: Positive reinforcement when ahead
• Non-judgmental: Gentle nudges, not nagging
• Configurable: Adjust quota to your needs

Philosophy

The power of showing up.

You don't track gym results daily - you track showing up. Same here. Consistency creates the habit. The habit creates discoveries. The discoveries create value.

Even a single Claude Code conversation counts. You'll naturally find yourself reaching for AI assistance more often, discovering use cases you never considered.

Requirements

• Claude Code installed (~/.claude directory exists)
• Node.js (any recent version)
• macOS or Linux

What Gets Installed

~/.claude/
├── streak-lib.js              # Core calculation engine
├── streak-statusline.sh       # Status line script (shows streak + quota)
├── quota-tracker.js           # Daily quota & pace tracking
├── context-analyzer.js        # Developer signal detection (includes pace)
├── nudge-messages.js          # Contextual message templates
├── nudge-engine.js            # Nudge decision engine
├── nudge-scheduler.sh         # Hourly cron runner
├── nudge-deliver.sh           # Notification delivery
├── nudge-config.json          # User preferences (includes quota settings)
├── hooks/
│   └── streak-welcome.sh      # Session start hook
├── commands/
│   └── streak.md              # /streak slash command (shows pace details)
└── settings.json              # Updated with hooks + statusLine

~/.claude-streak-cache.json    # Performance cache (auto-created)
~/.claude/nudge-history.jsonl  # Nudge delivery log (auto-created)

Customization

Change Timezone

Edit ~/.claude/streak-lib.js:

const TIMEZONE = 'America/New_York'; // Change to your timezone

Disable Features

Remove from ~/.claude/settings.json:

// Disable welcome message
"hooks": { ... }

// Disable status line
"statusLine": { ... }

Troubleshooting

Streak not updating?

# Force recalculation
rm ~/.claude-streak-cache.json
node ~/.claude/streak-lib.js

Welcome message not showing?

1. Restart Claude Code
2. Check ~/.claude/settings.json has hooks configured
3. Test: ~/.claude/hooks/streak-welcome.sh

Status line not appearing?

1. Restart Claude Code
2. Check ~/.claude/settings.json has statusLine configured
3. Test: ~/.claude/streak-statusline.sh

Uninstall

# Restore backup
cp ~/.claude/settings.json.backup ~/.claude/settings.json

# Remove files
rm ~/.claude/streak-lib.js
rm ~/.claude/streak-statusline.sh
rm ~/.claude/hooks/streak-welcome.sh
rm ~/.claude/commands/streak.md
rm ~/.claude-streak-cache.json

Contributing

This is a personal project, but feel free to fork and adapt for your needs!

License

MIT

---

Start your streak today! 🔥

Open Claude Code → See your current streak → Build the habit of daily AI-assisted development.