A CLI for tracking projects across multiple areas of work and life.

hq reads markdown files with YAML frontmatter from a directory of "tracks" (e.g., research/, funding/, personal/) and gives you a portfolio-level view of everything you're working on.

cargo install --path .
# or from GitHub:
cargo install --git https://github.com/yy/project-hq

1. Create a directory with track subdirectories:

my-projects/
  work/
    website-redesign.md
    api-migration.md
  personal/
    tax-filing.md

2. Each .md file has YAML frontmatter:

---
title: "Website redesign"
track: work
status: active
my_next: finalize mockups
deadline: 2026-04-15
---

Freeform notes, context, links...

3. Run commands:

cd my-projects
hq summary        # counts by status per track
hq my-plate       # my-plate projects (ball in your court)
hq waiting        # everything in waiting/submitted
hq stale          # waiting > 30 days
hq all            # everything grouped by status
hq undefer        # deferred projects ready to resume
hq serve          # start web dashboard on http://localhost:3001
hq serve --port 8080  # custom port

hq serve starts a local web server with a kanban board UI:

• Columns for each status (configurable order and set)
• Drag cards between columns to change status
• Drag cards within a column to reorder by priority
• Click a card to open a detail panel with rendered markdown notes
• Filter by track using the tabs at the top
• Color-coded cards by track
• Live reload when .md files change on disk

The repo includes a lightweight native macOS wrapper around the web dashboard. It bundles the Rust hq server into dist/HQ.app and points at the default data repo ~/git/hq (override with HQ_DIR).

./script/build_and_run.sh            # build and launch dist/HQ.app
./script/build_and_run.sh --verify   # build, launch, and confirm the server is up
./script/build_and_run.sh --logs     # launch and stream app logs
HQ_DIR=/path/to/hq ./script/build_and_run.sh

After building, copy the bundle into /Applications so it shows up in Spotlight and Launchpad:

# first install
cp -R dist/HQ.app /Applications/

# upgrade in place (works even if the old bundle has restrictive perms)
pkill -x HQ; rsync -a --delete dist/HQ.app/ /Applications/HQ.app/
killall Dock                         # refresh the icon cache

The app starts hq serve --port 3001 when it opens and terminates that child server when it quits. If another server is already listening on the configured port, the app attaches to it and leaves that external process alone — so running hq serve from a terminal and launching the app side-by-side is fine.

The app icon is bundled from macos/Assets/AppIcon.icns. To regenerate the checked-in icon assets, run script/make_icon.swift.

Optionally create hq.toml in your data directory:

tracks = ["work", "personal", "side-projects"]
skip_files = ["notes.md", "template.md"]
stale_days = 14
statuses = ["my-plate", "active", "waiting", "deferred", "submitted", "done", "dropped"]

Without a config file, hq auto-discovers tracks by scanning subdirectories for markdown files with frontmatter.

• title — project name
• status — one of the configured statuses (default: my-plate, active, waiting, deferred, submitted, done, dropped)

• track — inferred from directory name if omitted
• owner — who's responsible (omit if it's you)
• priority — integer, default 50
• waiting_on — who/what you're waiting on
• waiting_since — date (YYYY-MM-DD), used by stale
• my_next — your next concrete action
• last — most recent completed action
• deadline — date
• deferred_until — date, used by undefer

--dir <PATH>    Path to the data directory (default: current directory)
                Also settable via HQ_DIR environment variable

MIT