Skip to main content

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.

Metadata

Release files for Hearth-CLI 1.0.2

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for Hearth-CLI 1.0.2
File Size Uploaded Provenance Actions
hearth_cli-1.0.2.tar.gz 25.4 kB With provenance Details for hearth_cli-1.0.2.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for Hearth-CLI 1.0.2
File Interpreter ABI Platform Actions
hearth_cli-1.0.2-py3-none-any.whl Python 3 none any Details for hearth_cli-1.0.2-py3-none-any.whl

Total release size: 55.6 kB

Release files / hearth_cli-1.0.2.tar.gz

Download URL hearth_cli-1.0.2.tar.gz
Size 25.4 kB
Tags Source
SHA-256 checksum
How to use checksums
7f207a59cf22d11e2fb61b57ab1d49ea4949bdfdf1a8d13f8acbd3348249307f
BLAKE2b-256 checksum
How to use checksums
f38a8bb910071951a4af3c1e56722668889569d631eb07326a8094b11e2c3c27
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Release files / hearth_cli-1.0.2-py3-none-any.whl

Download URL hearth_cli-1.0.2-py3-none-any.whl
Size 30.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
322053e44de8b3fc0464afd5f95abcc6bd4452b4458730eed9728523dc527f28
BLAKE2b-256 checksum
How to use checksums
cb5131fe18c1fa1f10b6996ca1ca32a3b016a908827accb643847264028364fd
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

Security for Hearth-CLI 1.0.2

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for hearth_cli-1.0.2.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 2, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.0.2 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page