pitodo/README.md

TodoApp

A terminal app for Pi project todos. The Bubble Tea UI browses and searches a project's .pi/todos directory, shows full Markdown bodies, and creates, edits, closes, and reopens todos. The internal/todos storage package uses Pi-compatible Markdown files, .lock files, and atomic replacements for edits.

Run

Requires Go 1.24 or newer and a terminal.

go build -o bin/todoapp .          # build the executable
./bin/todoapp                     # inspect the current project
./bin/todoapp --project /path/to/repo # inspect another project
go test ./...                     # run unit and compatibility tests

go run . works too. --project selects the project root, not the todo directory. TodoApp always uses that project's .pi/todos directory, the Pi todo extension's default.

If .pi/todos does not exist, the app shows an empty state without creating files; creating a todo will create the directory. Bad todo files are reported as warnings without hiding valid todos. If the project path is invalid or the todo directory cannot be read, it exits with an error.

The interface uses Lip Gloss for its compact panels, selection, status badges, and warnings. On small terminals it drops the panel borders and shortens hints rather than requiring a fixed width. Set NO_COLOR=1 (or use TERM=dumb) for an uncolored layout; selection and status remain visible in text.

Todo files are named <8-hex-id>.md. Each starts with a JSON object (id, title, tags, status, created_at, optionally assigned_to_session), followed by a blank line and optional Markdown body. TodoApp preserves the ID, creation time, and Pi session assignment on edits. An existing .lock prevents changes; TodoApp does not steal locks. It does not change Pi's settings.json.

Compatibility was checked in both directions: TodoApp read a real file created by Pi's todo extension (kept as internal/todos/testdata/pi-created.md), and Pi's todo tool successfully read a temporary file created by TodoApp. The temporary compatibility items were deleted; the project's existing todos were not modified.

Controls

• ↑/↓ or j/k: select a todo; Enter: view its full Markdown body.
• /: search titles, IDs, tags, statuses, and body text. Type to filter, then Enter or Esc to finish. In the list, Esc clears the filter.
• In detail view, use ↑/↓, PgUp/PgDn, Home/End to scroll; Esc returns to the list.
• n: create a todo; e: edit the selected todo (also works in detail view).
• In the editor, Tab/Shift+Tab moves between title, comma-separated tags, and Markdown body. Enter adds a line in the body. ←/→ moves the cursor; Ctrl+S saves. Esc cancels, with confirmation if there are unsaved changes.
• x: close the selected todo; o: reopen a closed todo. Both ask for confirmation (y/n).
• r: reload todos from disk; q or Ctrl+C: quit.