Skip to content

Quick Start Guide

Get up and running with Streaklet in 5 minutes.

1. Start Streaklet

Choose your preferred method:

docker run -d -p 8080:8080 -v ./data:/data ghcr.io/ptmetcalf/streaklet:latest

Option 2: Local Development

Prerequisites: Python 3.12+, python3-venv (Ubuntu/Debian: apt install python3.12-venv)

# Clone repository
git clone https://github.com/ptmetcalf/streaklet.git
cd streaklet

# Create data directory
mkdir -p data

# Create and activate virtual environment
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# Windows: .venv\Scripts\Activate.ps1

# Install dependencies
pip install -r requirements.txt

# Run database migrations (use local path)
DB_PATH=data/app.db alembic upgrade head

# Start development server (use local path)
DB_PATH=data/app.db uvicorn app.main:app --reload --host 0.0.0.0 --port 8080

See Local Development Setup for detailed instructions.

2. Open in Browser

Navigate to http://localhost:8080

3. Create Your Profile

You'll be redirected to the Profiles page. A "Default Profile" is automatically created.

  • Click Edit to customize the name and color
  • Or click Add Profile to create additional profiles for family members

4. Add Your Tasks

Click Settings in the bottom navigation and:

  1. Click Add New Task and choose task type:
  2. Daily Recurring - Habits you do every day (meditation, exercise, reading)
  3. One-Off (Todo List) - Errands and reminders (call dentist, fix faucet)
  4. Scheduled Recurring - Periodic tasks (take out trash weekly, change filter monthly)
  5. Mark tasks as Required (must complete for streak) or optional
  6. Save changes

See the Task Types Guide for detailed information.

5. Start Tracking

Click Today in the bottom navigation to view your tasks organized by type:

  • Daily Tab - Your daily habits and any scheduled tasks due today
  • Todo List Tab - One-off errands and reminders
  • Scheduled Tab - View upcoming recurring tasks

Using the Today Page

  • Tap tasks to mark them complete
  • See your progress bar fill up (based on required daily tasks)
  • Complete all required tasks to continue your streak
  • Todo list items don't affect your streak - complete them at your own pace

Understanding Streaks

  • Day 1: Complete all required tasks
  • Streak continues: Keep completing all required tasks daily
  • Streak breaks: Miss any required task on any day
  • Today incomplete: Streak shows Day 1 until today is complete

Multi-User Setup

Each family member can have their own profile:

  1. Go to Profiles page
  2. Click Add Profile
  3. Choose name and color
  4. Each profile gets independent:
  5. Tasks
  6. Check history
  7. Streak count
  8. Calendar

Next Steps