streak

Minimalist habit tracker and life logger. Terminal-first, plain-text storage, beautiful heatmaps.

Install

pip install streak-cli

Quick Start

# Add habits to track
streak add "exercise"
streak add "read" --target 30  # 30 min daily goal
streak add "no-sugar" --type binary

# Log today
streak log exercise
streak log read 45             # 45 minutes
streak log no-sugar            # binary: done

# View progress
streak status                  # today's overview
streak heatmap exercise        # GitHub-style heatmap
streak stats                   # all habits summary

Output

$ streak status

  📊 Today (2024-08-19)     ████████░░ 3/4 habits

  ✅ exercise      — 1h gym session
  ✅ read          — 45 min (goal: 30 ✓)
  ✅ no-sugar      — day 12 streak 🔥
  ⬜ meditate      — not logged

$ streak heatmap exercise

  exercise (last 12 weeks)

  Mon ░░█░██░█░░██
  Tue ░█░██░░█░███
  Wed ██░░█░██░░██
  Thu ░█░█░██░░███
  Fri █░██░█░██░░█
  Sat ██░█░░░█░█░█
  Sun ░░█░░░█░░░██

  Current streak: 5 days | Best: 21 days | Rate: 74%

Commands

# Manage habits
streak add <name> [--target N] [--type binary|counter|duration]
streak rm <name>
streak list

# Log entries
streak log <habit> [value]     # log for today
streak log <habit> --date 2024-08-15  # backfill
streak undo <habit>            # remove today's entry

# View progress
streak status                  # today overview
streak heatmap <habit>         # weekly heatmap
streak stats [habit]           # statistics
streak history <habit> [--days 30]
streak best                    # longest streaks

# Export
streak export --format csv > habits.csv
streak export --format json > habits.json

Storage

Plain-text JSON — easy to backup, version, or script against:

~/.streak/
├── habits.json      # habit definitions
├── log/
│   ├── 2024-08.json # one file per month
│   └── 2024-07.json
└── config.yaml

Config

# ~/.streak/config.yaml
display:
  week_start: monday
  heatmap_weeks: 12
  colors: [dim, green, bright_green]  # intensity levels

notifications:
  enabled: true
  time: "21:00"          # evening reminder
  method: terminal       # or "ntfy", "telegram"

streaks:
  freeze_days: 1         # allow 1 missed day without breaking streak

Integrations

# Daily cron: morning status
echo "0 8 * * * streak status" | crontab -

# Pipe into other tools
streak export --format json | jq '.[] | select(.streak > 7)'

# Waybar/polybar module
streak status --format json | jq -r '.completed'

License

MIT