GitHub - timf34/habit-wallpaper: Habit tracker you can't hide from

Track daily habits with a GitHub-style heatmap rendered directly on your desktop wallpaper.

Because you'll ignore every other habit tracker. This one lives on your desktop and emails you daily. You can't hide.

A daily email sends you a link. Click it, check off your habits, and your wallpaper updates with a heatmap overlay showing your progress.

Getting Started

1. Sign up

Head to habits.timfarrelly.com/signup and enter your email and the habits you want to track.

You'll get a token on the welcome page (don't worry about saving it, your daily email contains it too).

Note: This is a hobby project running on a personal server. Don't use sensitive information as habit names. The server operator can see all data. See Self-Hosting if you'd prefer to run your own.

2. Log your habits

You'll receive a daily email with a link. Click it, check off what you did, done. You can also log directly at any time via the link.

3. View your dashboard

Visit your dashboard at habits.timfarrelly.com/dashboard?token=YOUR_TOKEN to see GitHub-style heatmaps and current streaks for each habit. You can add, remove, or reorder habits from Settings.

4. (Optional) Desktop wallpaper

Want the heatmap rendered directly on your desktop? Set up the local client:

git clone https://github.com/timf34/habit-wallpaper.git
cd habit-wallpaper
uv sync --extra client

Prerequisite: uv package manager. Install with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex" (Windows).

Create ~/.habit-wallpaper/config.json:

{
  "server_url": "https://habits.timfarrelly.com",
  "auth_token": "your-token-from-signup",
  "background_image": "/path/to/your/photo.jpg",
  "panel_position": "top-right",
  "panel_margin": 40
}

Test it:

uv run python -m client.main

Your wallpaper should update with the heatmap overlay. Now set up automatic updates:

schtasks /create /tn "HabitWallpaper" /tr "cmd /c cd /d C:\path\to\habit-wallpaper && .venv\Scripts\python.exe -m client.main" /sc minute /mo 30 /f

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.habit-wallpaper</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd /path/to/habit-wallpaper && .venv/bin/python -m client.main</string>
    </array>
    <key>StartInterval</key>
    <integer>1800</integer>
    <key>RunAtLoad</key>
    <true/>
</dict>
</plist>

crontab -e
# Add: */30 * * * * cd /path/to/habit-wallpaper && .venv/bin/python -m client.main

Client Config Reference

Self-Hosting

Want to run your own server? You'll need:

• Python 3.12+ and uv
• A VPS (e.g., DigitalOcean droplet)
• A domain name pointed at your VPS
• A Resend account with a verified domain

Server Setup

1. Clone and install:

   git clone https://github.com/timf34/habit-wallpaper.git
   cd habit-wallpaper
   uv sync --extra server

2. Create config.json:

   cp config.example.json config.json

   Field	Description
   server_url	Your server's URL (e.g., https://habits.yourdomain.com)
   resend_api_key	Your Resend API key
   email_from	Sender email on your verified domain
   email_send_hour	Hour (0-23, UTC) to send daily emails

3. Set up nginx + HTTPS:

   sudo cp deploy/nginx-habits /etc/nginx/sites-available/habits
   sudo ln -s /etc/nginx/sites-available/habits /etc/nginx/sites-enabled/
   # Edit /etc/nginx/sites-available/habits - set your domain
   sudo nginx -t && sudo systemctl reload nginx
   sudo certbot --nginx -d habits.yourdomain.com

4. Set up the systemd service:

   sudo cp deploy/habit-wallpaper.service /etc/systemd/system/
   # Edit the service file - set the correct paths
   sudo systemctl enable --now habit-wallpaper

5. Visit https://habits.yourdomain.com/signup to create your account.