ProgMap

LLM Disclaimer: This project was built with the help of LLMs and web-sources. The LLM contribution were closely reviewed by me (author) and I hope people find this project useful and may as well contribute to it.

ProgMap is a lightweight, terminal-native command-line utility designed to track daily task completion and visualize it using a GitHub-style contribution heatmap. Built in Rust.

Unlike Electron-based productivity suites, ProgMap compiles to a single, statically linked binary. It utilizes a bundled SQLite database for persistent and renders truecolor ANSI escape sequences to ensure accurate gradient mapping across modern terminal emulators.

Installation Guide

Because the project leverages the bundled feature of the rusqlite crate, the SQLite C library is compiled directly into the binary. This eliminates the need to install system-level database headers (e.g., libsqlite3-dev) or a C compiler toolchain beyond what Rust requires.

Prerequisites

• Rust-toolchain:
  Ensure you have the Rust toolchain installed on your system. If you do not have it installed, follow the guide on official rust-lang website:

• Linux:
  'Cause windows does not let you mess around the binary paths, maybe someone can contribute to the project to create a windows compatible version in the future :-).

Build and Install

1. Clone or download the source code to your local machine:

   git clone https://github.com/romanticNomad/ProgMap
   cd ProgMap

2. Compile the project in release mode to optimize for execution speed and binary size:

   cargo build --release

3. Install the binary to a system-wide executable path. On Ubuntu 24.04, /usr/local/bin is the standard location for user-compiled binaries:

   sudo cp target/release/progmap /usr/local/bin/

   Alternatively, if you prefer a user-local installation without sudo, you can copy it to ~/.local/bin/ (ensure this directory is in your $PATH).

4. Verify the installation:

   progmap --help

Usage Guide

ProgMap operates via a strict subcommand architecture. All data is stored locally in an SQLite database located at ~/.local/share/progmap/progress.db.

Logging Daily Progress

To record your daily task completion percentage, use the log subcommand. The tool enforces strict bounds checking, accepting only integer values between 0 and 100.

progmap log <percentage>

Example:

progmap log 85

Technical Details:

• Upsert Behavior: The underlying SQL query uses ON CONFLICT(date) DO UPDATE. If you log a percentage for a day that already has a recorded value, the new value overwrites the old one. This allows for corrections without generating duplicate database rows.
• Date Resolution: The tool automatically resolves the current date using the system's local timezone via the chrono crate.

Visualizing the Heatmap

To render the 53-week (~1 year) progress grid, use the view subcommand:

progmap view

Rendering Mechanics:

• Grid Layout: The tool calculates the Sunday of the week 52 weeks prior to the current date and generates a 7x53 matrix. Future dates (if the current day is not Sunday) are left blank.
• Color Mapping: The tool maps the stored integer to one of five distinct visual states using GitHub's exact dark-mode hex codes. It uses the ■ (U+25A0) Unicode block character colored via owo-colors truecolor methods to prevent terminal cell-padding misalignment.
  • 0% (or missing data): #161b22 (Background/Empty)
  • 1% - 25%: #0e4429 (Dark Green)
  • 26% - 50%: #006d32 (Medium Green)
  • 51% - 75%: #26a641 (Light Green)
  • 76% - 100%: #39d353 (Bright Green)

Direct Database Inspection

Because the storage layer is a standard SQLite database, you can bypass the CLI for advanced queries or data exports using the sqlite3 command-line tool:

sqlite3 ~/.local/share/progmap/progress.db "SELECT * FROM daily_progress ORDER BY date DESC LIMIT 10;"

Uninstallation Guide

Removing ProgMap requires deleting the compiled binary and the local data directory.

1. Remove the executable from your system path:

   sudo rm /usr/local/bin/progmap

   (If you installed it to ~/.local/bin/, use rm ~/.local/bin/progmap instead).

2. Remove the persistent data directory to delete your historical progress records and the SQLite database:

   rm -rf ~/.local/share/progmap

After completing these steps, the tool and all its associated state will be completely removed from your system.