todo-hub 0.3.3

Cross-repository TODO aggregator with a deadline-first agenda view.

todo-hub

todo-hub is a lightweight CLI tool that aggregates TODO tasks across multiple projects and presents them as a deadline-focused agenda.

It scans TODO.md files from different repositories and shows tasks grouped by urgency in a clean, colorized terminal view.

Ideal for developers managing many small projects.

Features

• Scan TODO files across multiple projects
• Parse Markdown checkbox tasks
• Detect deadlines using @YYYY-MM-DD
• Optional priority tags: !high, !medium, !low
• Support nested tasks (parent tasks are ignored)
• Agenda-style weekly view
• Deterministic color per project
• Simple config.toml configuration
• Fast and dependency-light

Installation

Recommended (pipx)

pipx installs CLI tools in isolated environments.

pipx install todo-hub

Run:

todo-hub

If pipx is not installed:

python -m pip install --user pipx
pipx ensurepath

Using pip

pip install todo-hub

Development install

git clone https://github.com/cwahyu/todo-hub.git
cd todo-hub
pipx install -e .

Usage

Run:

todo-hub

Example output:

Overdue:
  - [ ] fix parser @2026-03-10 (-4d) #mudita

This week:
  Today
  - [ ] finish CLI @2026-03-14 (0d) #todo-hub

  Tomorrow
  - [ ] improve parser @2026-03-15 (1d) #mudita

Later:
  - [ ] redesign module @2026-03-25 (11d) #todo-hub

Unscheduled:
  - [ ] research API #blog

Additional commands

todo-hub today
todo-hub week
todo-hub projects
todo-hub doctor

TODO Format

todo-hub scans Markdown files named:

TODO.md
todo.md

Tasks use Markdown checkboxes:

- [ ] task description

Optional metadata:

@YYYY-MM-DD     deadline
!high           priority
!medium
!low

Examples:

- [ ] implement CLI @2026-03-20
- [ ] fix production bug !high @2026-03-16
- [ ] improve documentation

Nested tasks are supported:

- [ ] version 0.3.0
  - [ ] support indented tasks
  - [ ] priority tags !medium

Parent tasks without deadlines are ignored.

Completed tasks are skipped:

- [x] finished task

Configuration

Projects are defined in config.toml.

Example:

[[project]]
name = "mudita"
path = "~/projects/mudita"

[[project]]
name = "todo-hub"
path = "~/projects/todo-hub"

Each project directory is scanned recursively for TODO files.

Philosophy

todo-hub is designed around a few simple principles.

Deadlines over task lists

Most task tools focus on managing tasks inside a single project.

todo-hub focuses on deadlines across projects.

The goal is to answer one question quickly:

What needs my attention today?

Plain text first

Tasks live in simple Markdown files:

TODO.md

This keeps the workflow:

• transparent
• version-controlled
• editor-friendly
• portable

No databases, no lock-in.

Terminal-first workflow

todo-hub is intentionally simple and optimized for terminal use:

• fast startup
• minimal dependencies
• readable CLI output
• color used only to highlight urgency

Run:

todo-hub

and immediately see what needs attention.

Small and maintainable

The architecture is intentionally minimal:

config → scan → parse → schedule → present

Each module has a single responsibility.

Development

Install dependencies:

uv sync --extra dev

Run the CLI:

uv run todo-hub

Run tests:

uv run pytest

License

MIT License