habitrack 1.0.0

A smart daily habit tracker — CLI, analytics, streaks, and daemon notifications

habitrack

A smart daily habit tracker for your terminal — CLI-driven, zero configuration, pure Python (stdlib only). Track habits, get streak analytics, view trend reports, and run a background notifier daemon.

Quickstart

pip install habitrack

# Or install from a local checkout
# git clone <repo-url>
# cd habit-tracker && pip install .

habitrack init         # Interactive setup — or skip for defaults
habitrack status       # Today's view
habitrack done all     # Mark everything done
habitrack report       # Analytics for the last 7 days

No external dependencies. No configuration files to edit. Just run it.

---

Installation

From PyPI

pip install habitrack

From source (development)

git clone <repo-url>
cd habit-tracker
pip install -e .

Requirements

• Python 3.8+
• No external packages required (stdlib only)
• pytest (optional, for running tests)

---

Commands

Command	Description
habitrack init	Interactive setup wizard — configure name, habits, and reminder times
habitrack status	Today's overview — ✅ completed / ⬜ pending tasks with icons
habitrack done <slug|all>	Mark one or more tasks as done (all marks everything)
habitrack undone <slug>	Revert a task back to pending
habitrack pending	Show only pending tasks (compact reminder view)
habitrack add <name> [--icon] [--times] [--category]	Add a new habit
habitrack remove <slug>	Archive a habit (keeps history, hides from status)
habitrack report [--days 7|14|30]	Trend report with completion bars, streaks, and trend arrows
habitrack reset	Clear all of today's completions
habitrack daemon [--background] [--stop]	Run background notifier (see Daemon Mode below)
habitrack export	Export all data as JSON (to stdout)
habitrack import <file>	Import data from a JSON file

---

Quickstart Walkthrough

1. Initialize

$ habitrack init

You'll be asked for your name and prompted to add habits interactively. If you skip the prompts, these defaults are seeded:

• 💊 Vitamin D (09:00, health)
• 💊 Zinc (09:00, health)
• 🎵 Vocal Exercise (10:00, health)

2. Check today's status

$ habitrack status
📋 Today — 2026-06-18
  1. ⬜ 💊 Vitamin D
  2. ⬜ 💊 Zinc
  3. ⬜ 🎵 Vocal Exercise

⏳ Pending: 3 item(s)

3. Mark tasks done

$ habitrack done vitd zinc
✅ Marked done: Vitamin D, Zinc

# Or mark everything:
$ habitrack done all
✅ Marked done: all

4. View a report

$ habitrack report --days 7
📊 Habit Report — last 7 days (2026-06-18)

| Task | Completion | Done | Streak 🔥 |
|---|---|---|---|
| 💊 Vitamin D | `█████░░░░░`  57.1% | 4/7 | 2d |
| 💊 Zinc | `█████░░░░░`  57.1% | 4/7 | 2d |
| 🎵 Vocal Exercise | `████░░░░░░`  42.9% | 3/7 | 1d |

📅 Today: 2/3 done (67%)

5. Add a new habit

$ habitrack add "Read 30 min" --icon 📖 --times 20:00 --category learning
➕ Added '📖 Read 30 min' as 'read30min' (reminders: 20:00)

---

Analytics

The report command gives you:

• Per-task completion % with a visual bar (█████░░░░░)
• Current streak — consecutive days (ending today) the task was done 🔥
• Trend arrows 📈📉➡️ comparing the current window vs the previous window
• Overall daily completion % for today

Trends are calculated for windows of 7, 14, or 30 days.

---

Daemon Mode

The daemon checks pending tasks at their scheduled times and sends desktop notifications.

# Start the daemon (foreground)
habitrack daemon

# Fork to background
habitrack daemon --background

# Stop the running daemon
habitrack daemon --stop

Notification methods (auto-detected):

• Linux: notify-send (libnotify)
• macOS: osascript -e 'display notification'
• Fallback: plain text to stdout

The daemon stores a PID file at ~/.smart-habits/daemon.pid so --stop can terminate the correct process.

---

Storage

Data lives in ~/.smart-habits/ by default. Override with the HABIT_DIR environment variable:

export HABIT_DIR=~/my-custom-path
habitrack status

Files

File	Purpose
habits.json	All habits and daily completion log
config.json	Preferences (reminder_enabled, notify_cmd, user_name)
backups/	Automatic daily backups (last 7 copies)

Atomic writes

All data mutations use an atomic write pattern (write to tempfile, then rename) to prevent data loss from crashes or concurrent access.

Auto-backup

Every day, when the first mutation occurs, the previous habits.json is automatically backed up to backups/. At most 7 backups are retained.

---

Development

# Editable install
pip install -e .

# Run tests
pip install pytest
pytest tests/

# Build distribution package
pip install build
python -m build

---

Project Structure

habit-tracker/
├── pyproject.toml
├── README.md
├── LICENSE
├── .gitignore
├── src/
│   └── habitrack/
│       ├── __init__.py
│       ├── __main__.py       # python -m habitrack
│       ├── cli.py            # argparse CLI
│       ├── storage.py        # JSON read/write, atomic saves, backups
│       ├── tracker.py        # Core habit logic
│       ├── defaults.py       # Default seed tasks
│       └── daemon.py         # Background notifier
└── tests/
    ├── __init__.py
    ├── test_tracker.py
    └── test_storage.py

---

License

MIT