Streak

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