pi-til-done

A pi-coding-agent extension that provides an iterative todo list — tracks tasks and automatically loops the agent until every task is marked done.

Features

• Three tools — write_todos, list_todos, edit_todos for create, read, and update task lists
• Four statuses — not_started (–), in_progress (●), completed (✓), abandoned (✗)
• Auto-continue engine — after each agent turn, a 3-second countdown fires if incomplete items remain; the user can interrupt by typing
• Circuit breaker — caps auto-continue at 20 consecutive iterations to prevent runaway loops
• Hidden context injection — before_agent_start hook injects the full todo list into each agent turn (when incomplete items remain) as a non-displayed system message
• Status bar — progress counter (setStatus) and active items display (setStatus); countdown widget above editor (setWidget)
• Event-sourced state reconstruction — state is rebuilt from session history on session_start / session_tree, surviving branch switches
• Atomic batch edits — edit_todos validates all indices before any mutation; if any index is invalid, no changes are applied
• Security — todo text is excluded from the instruction portion of the auto-continue prompt (only the 'Remaining items' display contains the actual text)
• Dual-mode rendering — plain-text formatting for LLM content, themed (colored, strikethrough) rendering for the TUI

Installation

This extension requires the following peer dependencies:

• @earendil-works/pi-coding-agent
• @earendil-works/pi-ai
• @earendil-works/pi-tui
• typebox

Install via npm:

npm install pi-til-done

The extension auto-registers when placed in a pi-coding-agent project via the pi.extensions field in package.json:

{
  "pi": {
    "extensions": ["./src/index.ts"]
  }
}

Quick Start

The agent uses the three tools to plan and track work:

1. Write the full todo list:

{
  "tool": "write_todos",
  "parameters": {
    "mode": "replace",
    "todos": [
      { "text": "Read requirements from docs/" },
      { "text": "Implement the core logic in src/" },
      { "text": "Write tests" },
      { "text": "Update README" }
    ]
  }
}

All items start with status not_started.

2. Start working on the first task:

{
  "tool": "edit_todos",
  "parameters": {
    "action": "start",
    "indices": [0]
  }
}

The item at index 0 transitions to in_progress.

3. Agent performs the work (writes code, creates files, etc.).

4. Mark the task complete:

{
  "tool": "edit_todos",
  "parameters": {
    "action": "complete",
    "indices": [0]
  }
}

5. Auto-continue fires — when the agent's turn ends and incomplete items remain, a 3-second countdown begins. The agent is then prompted to continue with the next item. The user can interrupt by typing during the countdown.

This loop continues until all items are either completed or abandoned, or until the 20-iteration circuit breaker trips.

Tools Overview

Tool	Purpose	Key Parameters
write_todos	Manage the todo list via modes: replace (clear & replace), append (add to end), insert (insert at index). New items start as not_started.	mode: "replace" | "append" | "insert", todos: { text: string }[], index?: number
list_todos	View the current list with statuses and indices.	(none)
edit_todos	Apply a status action to items by index. Batch operations are atomic.	action: "start" | "complete" | "abandon", indices: number[]

See docs/TOOLS.md for full tool reference and schema details.

Architecture Overview

The extension consists of 7 source modules organized around a single entry point:

Module	Responsibility
index.ts	Extension factory — registers tools, renderers, and event handlers
types.ts	Type definitions, constants, and lookup maps
state.ts	Module-level mutable singleton; state reconstruction from session history; UI sync
tools.ts	Tool definitions for write_todos, list_todos, edit_todos with TypeBox schemas
events.ts	Event handlers (session_start, session_tree, before_agent_start, agent_end) and message renderers
formatting.ts	Dual-mode formatting: plain-text for LLM, themed for TUI
validation.ts	Type guards, deep-cloning helpers, and input validation

Key design patterns:

• Event-sourced state — tool results store TodoDetails in message entry details, enabling state reconstruction from any point in the session tree.
• Dual rendering — tool content uses plain-text icons (for LLM consumption), while TUI renderers apply color themes and strikethrough for completed/abandoned items.
• Counter reset semantics — the auto-continue counter resets on write_todos (all modes) and edit_todos (user-directed actions), but not on agent_end (auto iterations). This ensures the 20-iteration limit counts only consecutive auto-continues.

See docs/ARCHITECTURE.md for detailed diagrams and data flow.

Configuration

There are no user-configurable settings. All limits are defined as constants in types.ts:

Constant	Value	Description
MAX_TODO_TEXT_LENGTH	1000	Maximum characters per todo item text
MAX_AUTO_CONTINUE	20	Maximum consecutive auto-continue iterations (circuit breaker)
MAX_TODOS	100	Maximum items in a todo list
MAX_INDICES	50	Maximum indices in a single edit_todos call
INITIAL_STATUS	"not_started"	Status assigned to newly created items

Development

Scripts

npm test              # Run test suite (Vitest)
npm run test:watch    # Run tests in watch mode
npm run lint          # ESLint check
npm run format        # Prettier format (write)
npm run format:check  # Prettier format check (dry run)
npm run typecheck     # TypeScript type check (no emit)

Testing

Tests use Vitest with mock implementations of the pi-coding-agent API. Test files live in src/__tests__/ and cover all modules.

See docs/TESTING.md for the testing strategy and how to add tests.

Contributing

See CONTRIBUTING.md for contribution guidelines.

License

MIT