pi-todo

Terminal-first TODO board for Pi — tasks, PR reviews, and project tracking, all without leaving the agent.

I built this because I wanted task management that lives where I actually work. Tasks are repo-scoped automatically (detected from git remote origin), PR reviews are first-class items with AI summary and clone-review actions, and the board shows up as a startup snapshot so I always know what's open.

Install

pi install npm:@pedro_klein/pi-todo

What it provides

Tools

• todo — Read and write tasks. The agent calls this to manage your board.
  • list — list tasks for the current repo (or all scopes with scope: "all")
  • add — create a task with title, type, priority, description, due date, url, note
  • update — update any field on a task by ID
  • complete — mark a task done by ID
  • delete — remove a task by ID

Commands

• /todo — Open the interactive board (TUI overlay)
• /todo <description> — AI-capture a task from natural language (e.g. /todo fix the auth bug before Friday)
• /todo <PR-URL> — Create a PR review task from a GitHub/GitHub Enterprise URL
• /todo-repo — Show the current repo scope used for task association

Shortcuts

• Ctrl+Shift+B — Open the board from anywhere

Startup snapshot

Every session start prints a multi-column board to the chat (grouped by task type, color-coded by urgency). The snapshot is filtered out of LLM context — the agent only sees tasks you explicitly surface via the todo tool.

Task model

Types

Type	Scope	Description
feature	repo	New capability or improvement
bug	repo	Something broken
chore	repo	Maintenance, refactoring
research	repo	Investigation or exploration
review	reviews (global)	PR review — always cross-repo
personal	personal (global)	Non-work task

Priorities: low · medium · high

Statuses: open · blocked · done

Urgency (drives sort order and color):

• overdue — past due date → red
• due-soon — within 48h → yellow
• blocked → muted
• normal → default
• done → dim

Scoping

Tasks are associated with the current git repo (detected from git remote origin). The repo slug format is owner__repo (e.g. pedroklein__dotfiles).

Special scopes that are always visible regardless of current repo:

• personal — personal/non-work tasks
• work — cross-project work tasks
• reviews — PR review tasks

When in a specific repo, the board shows that repo's tasks plus all three global scopes.

PR review workflow

Paste a PR URL into /todo to create a review task:

/todo https://github.com/owner/repo/pull/123

Pi fetches PR metadata (title, author, branch, state) from the GitHub API, creates a review task, and adds it to the reviews scope. From the board, review tasks have three actions:

Key	Action	Description
s	AI Summary	Fetch the PR diff and generate a structured review with Q&A
o	Open in browser	Open the PR URL
c	Clone & Review	Clone the repo to /tmp, open a new Pi session for deep review

Requires a GitHub token discoverable via gh auth token, GITHUB_TOKEN, or GH_TOKEN. Without a token, falls back to unauthenticated API calls (rate-limited).

AI task capture

/todo <text> uses a three-tier strategy to parse natural language into structured tasks:

1. BAML (if @pedro_klein/pi-baml is installed) — typed structured extraction
2. LLM — call Pi's current model with a structured prompt
3. Heuristics — keyword matching fallback (always available)

The parsed task shows in a preview modal where you can edit fields before saving. Relative dates ("next Friday", "in 2 weeks") are resolved to YYYY-MM-DD.

Board TUI

Open with /todo or Ctrl+Shift+B.

List view

Key	Action
h / l	Switch scope tab
j / k	Move task selection
Enter	Open task details
d	Toggle done
x	Delete task
n	Add/edit note
f	Cycle status filter (active → open → blocked → done → all)
i	Inject task into conversation
o	Open URL in browser
s	AI summary (review tasks)
c	Clone & review (review tasks)
Esc / q	Close

Details view

Key	Action
j / k	Navigate fields
Enter	Edit text fields / cycle enum fields
d	Toggle done
o / s / c	Same as list view
Esc / q	Back to list

Persistence

Tasks are stored in ~/.config/todo/ as per-scope JSON files:

~/.config/todo/
├── pedroklein__dotfiles.json   # repo-specific tasks
├── global.json                 # personal tasks
├── reviews.json                # PR reviews
└── work.json                   # work tasks

This is the same storage used by the todo CLI — they share the same data. You can use the standalone TUI (todo) to manage tasks from the terminal, and this extension to manage them from inside pi. Changes made in either are immediately visible to the other.

IDs are per-scope (each scope has its own 1-based numbering).

Migrates automatically from the old single-file format at ~/.pi/agent/todo/pi-todo.json on first run.

GitHub integration

Supports GitHub.com and GitHub Enterprise. Token discovery order:

1. gh auth token (GitHub CLI)
2. GITHUB_TOKEN env var
3. GH_TOKEN env var
4. Unauthenticated (rate-limited to 60 req/hr)

GitHub Enterprise URLs (https://github.yourcompany.com/...) are detected automatically from the PR URL host.

Configuration

No required configuration — works out of the box with git repos.

Optional integrations:

• @pedro_klein/pi-baml — enables BAML tier for AI task capture and PR review summaries. Install separately:

  pi install npm:@pedro_klein/pi-baml
  

Development

pnpm test           # run tests
pnpm build          # build for publish
pnpm typecheck      # type-check without emitting

License

MIT