# pi-todo

Manage and plan multiple tasks and checklists in pi. Tasks are stored in the current session, progress is recorded without changing the original text, and state follows pi's session branches.

## Features

- One native `todo` tool with five actions: `create`, `list`, `add`, `complete`, and `cancel`
- Multiple free-form tasks and checklists
- Exact text preservation, including whitespace and formatting
- Session and `/tree` branch-aware persistence through tool-result events
- A fixed recovery hint after compaction when unfinished tasks exist
- A compact TUI widget showing up to three recently updated active tasks
- A read-only `/todos` TUI view for full task and progress details

## Tool

### Create a task

```json
{ "action": "create", "text": "Implement the feature:\n- storage\n- tool\n- tests" }
```

### List unfinished tasks

```json
{ "action": "list" }
```

The list ends with a one-line summary of completed tasks; cancelled tasks are excluded.

Pass an ID to inspect one task, including its complete progress history:

```json
{ "action": "list", "id": "a13f92bc" }
```

### Add progress

```json
{ "action": "add", "id": "a13f92bc", "text": "Finished the state layer and tests." }
```

### Complete a task

```json
{ "action": "complete", "id": "a13f92bc" }
```

### Cancel a task

```json
{ "action": "cancel", "id": "a13f92bc" }
```

Cancelling abandons a task without marking it done. Cancelled tasks leave the active list, do not appear in the completed summary, and reject further progress. A completed task cannot be cancelled.

Task and progress text is stored exactly as received. The extension does not trim, normalize, parse, or rewrite it. Display-only previews may wrap or truncate without changing stored content.

## TUI

When unfinished tasks exist, a widget above the editor shows up to three recently updated tasks and their latest progress. Run `/todos` for the read-only full view. The widget and command output are TUI-only and are not added to the model context.

## Persistence and compaction

Mutation events are stored in `todo` tool-result details and replayed from the active session branch on startup and `/tree` navigation. No project or global task file is created.

After a compaction occurs while unfinished tasks exist, the extension appends this fixed line to subsequent system prompts:

```text
There are unfinished tasks in todo. Use todo with action "list" to view them.
```

No task content is injected into the system prompt.

## Installation

With pi:

```bash
pi install npm:@4fu/pi-todo
```

Or link the repository locally:

```bash
pi config set extensions./path/to/pi-todo
```

## Development

Requires Node.js 22.19 or newer.

```bash
npm install
npm run typecheck
npm test
```

Pi loads `src/index.ts` directly; there is no build step.

## License

MIT