Metadata-Version: 2.4
Name: habitrack
Version: 1.0.0
Summary: A smart daily habit tracker — CLI, analytics, streaks, and daemon notifications
Author: Shahriar Hussain
License: MIT
Project-URL: Homepage, https://github.com/shahriar/habitrack
Project-URL: Repository, https://github.com/shahriar/habitrack
Project-URL: Documentation, https://github.com/shahriar/habitrack#readme
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Office/Business :: Scheduling
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 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

```bash
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

```bash
pip install habitrack
```

### From source (development)

```bash
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

```bash
$ 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

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

⏳ Pending: 3 item(s)
```

### 3. Mark tasks done

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

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

### 4. View a report

```bash
$ 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

```bash
$ 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.

```bash
# 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:

```bash
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

```bash
# 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
