---
slug: "structupath-pi-tilldone"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/StructuPath/pi-tilldone@main/README.md"
repo: "https://github.com/StructuPath/pi-tilldone"
source_file: "README.md"
branch: "main"
---
# pi-tilldone

Task discipline for the [Pi coding agent](https://pi.dev): the agent **must declare what it's going to do before it's allowed to do it** — and gets nudged until it's actually done.

"todo" → "tilldone": work *till* it's *done*.

By [StructuPath](https://structupath.ai).

## Install

```bash
pi install npm:@structupath/pi-tilldone
```

## Why

Todo-list extensions record what the agent plans to do. TillDone **enforces** it:

- **Hard gate** — write/execute tools are blocked until the agent creates a task list and marks a task in-progress. Read-only tools (read, grep, find, ls, glob) stay open so it can explore before planning.
- **Single focus** — only one task can be in-progress at a time; toggling a new one auto-pauses the old one.
- **Completion nudge** — if the agent stops with incomplete tasks, it gets pushed back to work: *"Don't stop until it's done!"* (once per user turn, so it can't loop forever).
- **Survives everything** — state is reconstructed from the session on start, switch, fork, and tree navigation.

## UI

- **Footer** — live task list with title, progress `[done/total]`, and per-status counts
- **Widget** — prominent `● WORKING ON #3 <task>` banner below the editor
- **Status line** — compact summary
- **/tilldone** — full-screen overlay with every task

The agent drives it through a single `tilldone` tool: `new-list`, `add` (single or batch), `toggle` (cycles idle → inprogress → done), `update`, `remove`, `list`, `clear`. Destructive actions (`new-list` over an existing list, `clear`) ask **you** to confirm first.

## Bonus: cmux integration

If you run Pi inside [cmux](https://cmux.io), the bundled `cmux-status` extension syncs task state to your workspace tabs — at a glance, across every parallel agent:

| Tab color | Meaning |
|---|---|
| 🟡 yellow | working — a task is in progress |
| 🟢 green | all tasks done (+ desktop notification) |
| 🟠 orange | blocked — tasks exist, none in progress |
| ⚪ gray | idle — no tasks yet |

Tab title shows `⚡ <list> [2/5]`, tab description shows the current task. Outside cmux it no-ops silently — zero overhead.

## License

MIT

---

More Pi packages from StructuPath: [`@structupath/pi-steel`](https://pi.dev/packages/@structupath/pi-steel) — structural steel estimating skills.