Hearth CLI — Project & Sprint Awareness System

Hearth CLI is a local project and sprint awareness tool for the terminal. It keeps a YAML registry of active work, calculates a lightweight cognitive-load signal, records context switches, and presents the same data through a Rich CLI and a Textual dashboard.

Created by Toshon Jennings.

The PyPI distribution is named hearth-cli; the installed command is hearth.

Install

Hearth CLI requires Python 3.11 or newer. Installing it as an isolated command-line tool is recommended:

pipx install hearth-cli

or:

uv tool install hearth-cli

You can also install it into an existing Python environment:

python -m pip install hearth-cli

First use

hearth add

hearth status

hearth dashboard

Hearth CLI starts with an empty registry. Its local data lives in ~/.config/hearth/ by default. Set HEARTH_DATA_DIR to use another directory.

Commands

• hearth status shows project health, sprint capacity, and priority actions.
• hearth sprint shows committed projects and cognitive-load guidance.
• hearth switch <id> records a context switch and updates the project date.
• hearth add registers a project interactively.
• hearth add --from-json <json> registers a project non-interactively.
• hearth edit <id> opens a project's YAML in $EDITOR.
• hearth md writes PROJECTS.md in the Hearth CLI data directory.
• hearth md --output <path> writes the report to a specific path.
• hearth md --json prints the registry as structured JSON.
• hearth agent-link <id> <type> <path> associates an agent log with a project.
• hearth scan discovers candidate repositories directly under your home and ~/projects directories and asks before importing them.

Run hearth --help or hearth <command> --help for the complete interface.

Data and privacy

Hearth CLI is local-first. Registry data is stored as plain YAML and context-switch history is appended to a plain JSON Lines file. It does not encrypt those files or send them to a remote service. Protect the data directory with normal filesystem permissions and full-disk encryption if it contains sensitive project information.

Development

uv sync --extra dev

uv run pytest

uv build

License

Hearth CLI is source-available proprietary software. Personal, educational, and internal operational use is permitted with named credit. Reselling it, charging for access to it, including it in a paid product or service, or otherwise monetizing Hearth CLI requires a separate written commercial agreement with Toshon Jennings. See LICENSE for the complete terms.