Streak

A universal, flexible challenge tracking system for Claude Code. Track any personal challenge with intelligent insights and cross-challenge learning detection.

Works for any challenge type: Learning, Building, Fitness, Creative, Habit, or Custom.

Quick Start

Trigger phrases -> Flows:

Data Storage

All data in .streak/ folder:

.streak/
├── config.md                     # Global settings
├── active.md                     # Current challenge pointer
└── challenges/
    └── [challenge-id]/
        ├── challenge-config.md   # Metadata, goal, progress
        ├── challenge-log.md      # Progress log with summary
        ├── today.md              # Today's session context
        ├── backlog.md            # Ideas to try
        ├── preferences.md        # Type-adaptive setup
        ├── context.md            # Linked resources
        ├── insights.md           # Auto-generated insights
        └── sessions/
            └── session-XXX/
                └── notes.md      # Session notes

File templates: See references/file-templates.md

Challenge Types

Type details: See references/types.md

Flow 1: New Challenge

1. Initialize .streak/ folder if needed
2. Ask type: Learning, Building, Fitness, Creative, Habit, or Custom
3. Basic info: Name, goal, cadence (daily/every N days/weekly)
4. Type-specific questions: See references/types.md
5. Create files: All templates pre-filled based on answers
6. Set active and confirm

Detailed steps: See references/flows-detailed.md

Flow 2: Check-in

Two modes: Pre-session (planning) and Post-session (wrap-up)

Pre-Session Mode

1. Load context: Read active challenge, config, today.md, preferences, backlog
2. Show status: Session #, streak, days since last, on-track/due/overdue
3. Quick context: Energy/time, specific focus or "surprise me", constraints
4. Optional research: For Building/Learning types
5. Ideation: Type-adaptive suggestions based on energy and backlog
6. Prepare session: Create session folder and notes template

Post-Session Mode (user says "done")

1. Wrap-up questions: What worked on, how it went, what's next, key learning
2. Type-specific questions: See references/types.md
3. Save: Update session notes, challenge-config, challenge-log, backlog
4. Generate insights: Patterns, streaks, cross-challenge connections
5. Check achievements: See references/achievements.md
6. Completion message: Progress summary, achievements earned, insights

Shortcuts during flow:

Detailed steps: See references/flows-detailed.md

Flow 3: List Challenges

Display challenges grouped by status, sorted by priority then recency.

Default: Show active + paused challenges With --all flag: Include archived challenges

Sorting order (within each group):

1. Priority (higher number first, default 0)
2. Last check-in (most recent first)

Display format:

## Active Challenges
| | Name | Type | Pri | Streak | Last Check-in | Sessions |
|---|------|------|-----|--------|---------------|----------|
| * | python-courses | Learning | 10 | 5 days | 1 day ago | 3 |
|   | home-fitness | Fitness | 5 | 2 days | 2 days ago | 8 |

## Paused Challenges
|   | stories-to-novels | Writing | 0 | - | 10 days ago | 5 |

(2 archived challenges hidden - use --all to show)

* = Active challenge
Pri = Priority (edit in challenge-config.md)

With --all flag, also show:

## Archived Challenges
|   | old-project | Building | 0 | - | 2 months ago | 20 |

Flow 4: Switch Challenge

1. Validate challenge exists
2. Update active.md
3. Load new challenge context
4. Confirm with status

Flow 5: Statistics

Show for active challenge:

• Progress: Sessions, days since start, completion rate
• Streaks: Current, longest, average gap
• Patterns: Best day, best time, average length
• Achievements: Earned badges with dates
• Backlog: Completed, in-progress, pending items

Flow 6: Cross-Challenge Insights

Analyze ALL challenges to detect:

1. Compound Learning: Skills from one challenge enabling another
2. Skill Transfer: Same concepts across challenges
3. Cross-Domain: Correlations between different types
4. Patterns: Best days, productivity trends
5. Suggestions: Personalized recommendations

Insight formats: See references/achievements.md

Flow 7: Calendar Export

Generate .ics file with check-in reminders:

• Frequency based on cadence
• 30-day look-ahead (configurable)
• Works with Google, Apple, Outlook calendars

Template: See references/file-templates.md

Flow 8: Reset Challenge

Archives current progress and starts fresh:

• Archives log as challenge-log-archived-[date].md
• Archives sessions folder
• Resets streak counters
• Keeps preferences, context, backlog intact

Flow 9: Pause Challenge

Temporarily pause a challenge (plan to resume later):

1. Validate challenge exists and is active
2. Update challenge-config.md: set **Status:** paused
3. If pausing the active challenge:
   • List other active challenges
   • Prompt: "Paused [name]. Switch to another challenge?"
   • If yes, run Flow 4 (Switch)
4. Confirm: "Challenge [name] paused. Use /streak-resume [name] to reactivate."

Use cases: Seasonal challenges, focusing on other priorities, taking a break

Flow 10: Archive Challenge

Move challenge to long-term storage (out of daily view):

1. Validate challenge exists and is not already archived
2. Update challenge-config.md: set **Status:** archived
3. If archiving the active challenge:
   • List other active challenges
   • Prompt: "Archived [name]. Switch to another challenge?"
   • If yes, run Flow 4 (Switch)
4. Confirm: "Challenge [name] archived. Use /streak-list --all to see archived challenges."

Use cases: Completed goals, abandoned challenges, historical record

Flow 11: Resume Challenge

Bring a paused or archived challenge back to active:

1. Validate challenge exists and is paused or archived
2. Update challenge-config.md: set **Status:** active
3. Ask: "Make [name] your active challenge?"
   • If yes, update active.md
4. Check days since last check-in:
   • If 7+ days: Award :muscle: Comeback badge
5. Confirm: "Challenge [name] is now active. Ready to check in?"

Note: Resuming does NOT reset streak - it continues from where you left off.

Flow 12: Notifications Setup

Set up push notifications for due/overdue check-ins via Telegram.

Step 1: Create Telegram Bot

1. Open Telegram and message @BotFather
2. Send /newbot and follow prompts
3. Copy the bot token (looks like 123456789:ABCdefGHI...)

Step 2: Get Chat ID

1. Message @userinfobot on Telegram
2. Copy your chat ID (a number like 123456789)

Step 3: Configure

Add to .streak/config.md:

## Notifications (Optional)

- **Notifications:** enabled
- **Telegram Bot Token:** 123456789:ABCdefGHI...
- **Telegram Chat ID:** 123456789

Step 4: Schedule Notifications

Option A: Cron (Linux/Mac)

# Run daily at 9am
0 9 * * * cd /path/to/project && python .streak/../tools/streak-notify.py

Option B: GitHub Actions

# .github/workflows/streak-notify.yml
name: Streak Reminder
on:
  schedule:
    - cron: '0 9 * * *'  # 9am UTC daily
jobs:
  notify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      - run: python tools/streak-notify.py .streak

Step 5: Test

python tools/streak-notify.py /path/to/.streak

Detailed steps: See tools/streak-notify.py header comments.

Flow 13: Telegram Bot Deploy

One-command deployment of the interactive Telegram bot with Docker.

Prerequisites (User Must Complete First)

1. Create Telegram Bot: Message @BotFather → /newbot → save token
2. Get Chat ID: Message @userinfobot → save Id number
3. Message your bot: Send /start to your bot (required before it can message you)
4. Create .env file in your project root:

   cat > .env << EOF
   TELEGRAM_BOT_TOKEN=your-bot-token
   ALLOWED_USERS=your-chat-id
   EOF

5. Docker must be installed and running

Flow Steps

1. Verify prerequisites:
   • Check .env file exists in project root
   • Check TELEGRAM_BOT_TOKEN is set (not empty/placeholder)
   • Check Docker is available (docker --version)
   • If any missing, show specific instructions and stop
2. Locate skill tools directory:

   # Plugin location (typical paths)
   ~/.claude-code/plugins/ccc-skills@ccc/streak/tools/
   # Or within the ccc repo if running locally

3. Copy bot files to project root:

   cp [tools-dir]/streak-bot.py ./streak-bot.py
   cp [tools-dir]/Dockerfile ./Dockerfile
   cp [tools-dir]/docker-compose.yml ./docker-compose.yml

4. Ensure .gitignore protects secrets:

   # Add if not present
   echo ".env" >> .gitignore

5. Start the bot:

   docker-compose up -d --build

6. Verify bot is running:

   docker-compose ps
   docker-compose logs --tail=20

7. Confirm to user:

   ✅ Telegram bot deployed!
   
   Bot is running in Docker and will auto-restart on reboot.
   
   Commands:
   - docker-compose logs -f    # View logs
   - docker-compose restart    # Restart bot
   - docker-compose down       # Stop bot
   
   Open Telegram and send /start to your bot to test!

Error Handling

Achievements

Streak Badges

Milestone Badges

Special Badges

Full list: See references/achievements.md

Error Handling

Design Philosophy

Your challenges are interconnected. Your fitness affects your work. Your learning enables your building. Your habits shape your creativity.

Streak detects cross-challenge connections - patterns you might miss:

• "Morning workouts correlate with productive coding days"
• "Skills from 'Learn Rust' enabled progress in 'Build CLI Tools'"

This is the unique value - not just tracking, but understanding how challenges interact.

One Place, All Challenges

Put ALL challenges in ONE .streak/ folder, regardless of life area:

.streak/challenges/
├── work-project      # Work
├── morning-fitness   # Health
├── learn-rust        # Learning
└── daily-meditation  # Habit

Use /streak-switch to navigate. Use /streak-insights to discover connections.

Don't create separate .streak/ folders for different challenges. That defeats the purpose.

Best Practices

1. Keep challenges together - One .streak/ folder for ALL challenges (work, health, learning, etc.)
2. Be specific in goals - "Complete Rustlings" > "Learn Rust"
3. Start sustainable - Every 2-3 days is easier than daily
4. Use today.md - Set context before sessions
5. Maintain backlog - Ideas for low-energy days
6. Review insights - Check weekly to see patterns
7. Celebrate streaks - Achievements are real motivation
8. Reset guilt-free - Archiving is progress, not failure
9. Cross-pollinate - Run multiple challenges to find connections

Reference Files

For detailed content, see:

Examples

30 Days of AI/ML (Building)

Type: Building
Goal: Ship one AI-powered micro-app per day
Cadence: Daily
Stack: Python, TypeScript, Claude Code

Learn Rust (Learning)

Type: Learning
Goal: Complete Rustlings and build a CLI tool
Cadence: Every 2 days
Resources: Rustlings, The Rust Book

Morning Workout (Fitness)

Type: Fitness
Goal: Build consistent strength training habit
Cadence: Daily (with rest days)
Equipment: Home gym - dumbbells, pull-up bar

Daily Sketching (Creative)

Type: Creative
Goal: Draw one sketch per day for 100 days
Cadence: Daily
Medium: Digital art (Procreate)

Morning Meditation (Habit)

Type: Habit
Goal: Meditate 10 minutes every morning
Cadence: Daily
Trigger: After coffee, before email