🎉 Habitctl

Habitctl is a portable command-line habit tracker for Windows. It lets you create recurring tasks with reminders and pomodoro timers, mark them done, and track your progress with per-task streaks and a 365-day contribution heatmap.

• Recurring tasks: daily, weekly, specific weekdays (mon,wed,fri), or a one-off once
• Optional reminder time (--time HH:MM) and a per-task pomodoro length (default 25 min)
• today lists tasks due today with completion state and streak metadata
• done marks a task complete and reports its current streak
• timer start runs a live countdown pomodoro with a progress bar, then auto-marks the task done
• stats --heatmap shows total completions, current streak, longest streak, and a 365-day contribution heatmap
• Colored terminal output that auto-detects a real console — enables ENABLE_VIRTUAL_TERMINAL_PROCESSING on Windows, and falls back to plain text automatically when output is redirected or piped
• Ships as a single portable .exe — no installer required
• Data persists as JSON under %APPDATA%\habitctl\

• Windows 10/11 (x64)
• Go 1.25+ — only needed to build from source

go build -o habitctl.exe ./cmd/habitctl

Cross-compile from another OS:

GOOS=windows GOARCH=amd64 go build -ldflags "-s -w" -o habitctl.exe ./cmd/habitctl

Publish or update the winget package manifest after cutting a new GitHub release. Requires the wingetcreate CLI:

winget install wingetcreate

First-time publish — generates a manifest from the release asset and saves it locally for review, then submits it as a PR against the community winget-pkgs repo.

wingetcreate new --out ./manifest-out https://github.com/natthasath/habitctl/releases/download/v1.0.0/habitctl.exe
wingetcreate submit --prtitle "New package: Natthasath.HabitCtl version 1.0.0" ./manifest-out

Check the currently published manifest, then submit the new release's URL and version (replace <NEW_VERSION> with the release you're publishing):

winget show --id Natthasath.HabitCtl --source winget
wingetcreate update Natthasath.HabitCtl --version <NEW_VERSION> --urls https://github.com/natthasath/habitctl/releases/download/v<NEW_VERSION>/habitctl.exe --submit

habitctl CLI

Usage:
habitctl [OPTIONS]
habitctl <COMMAND> [ARGS]

Commands:
  task             Add or configure a task (see 'habitctl task --help')
  today            List tasks due today
  done             Mark a task complete
  timer            Run a pomodoro timer for a task
  stats            Show completion totals, streaks, and a 365-day heatmap
  help             Print this message or the help of the given subcommand(s)

Options:
  -h, --help
          Print help (see a summary with '-h')

  -V, --version
          Print version

Notes:
  task add requires --recurrence <daily|weekly|mon,wed,fri|once>; --pomodoro defaults to 25 minutes if omitted.
  done and timer accept a task id or a case-insensitive substring of the task name.
  Every completion is recorded to a date-keyed history, which powers 'stats --heatmap' (current streak, longest streak, total completions).
  Ctrl+C during timer cancels the countdown without marking the task done.
  Exit codes: 0 = success, 1 = error, 2 = invalid usage/arguments.
  Data file: %APPDATA%\habitctl\data.json

Run habitctl task --help for the add/set subcommand flags — every command supports -h/--help.

habitctl task add "Read 20 minutes" --recurrence daily --time 21:00
habitctl task add "Gym" --recurrence mon,wed,fri --pomodoro 45
habitctl today
habitctl done a1f9
habitctl timer start a1f9 --minutes 25
habitctl stats --heatmap

1.0.0 — initial release: task add/task set, today, done, timer start, and stats --heatmap commands for a Windows habit tracker, with per-task streaks, a 365-day contribution heatmap, and colored terminal output that respects redirected/piped stdout.

This project is licensed under the MIT License.

Natthasath Saksupanara — Computer Technical Officer, NIDA
natthasath.sak@gmail.com