# pi-tracker pi-tracker is an extension for Pi. It manages todolists in your session. ## Features - Create and delete todolists. - Add, update, and remove items in a todolist. - Mark an item as complete or incomplete. - Change the task text of an item. - Declare dependencies between items, so work happens in order. - Persist todolists with the session. - Show the active todolist in a widget above the editor. ## How it works pi-tracker stores its state in an Effect service. It writes a snapshot to the session after every change. It restores the state when the session resumes. The snapshot does not enter the LLM context. ## Usage ### The tracker tool Ask Pi to manage your todolists. Pi calls the `tracker` tool. The tool supports these actions: | Action | Purpose | Parameters | | ------------- | ----------------------------------------- | ----------------------------------------------------------- | | `list` | Show all lists and items | — | | `create_list` | Create a list (becomes active by default) | `name`, `initial_items?`, `activate?` | | `delete_list` | Delete a list | `list_id` | | `set_active` | Set or clear the active list | `list_id` (optional) | | `add_item` | Add one or more items | `list_id`, `text` (string, item object, or array) | | `update_item` | Update one or more items | `item_id` + `text?`/`done?`/`deps?`, or `list_id` + `items` | | `remove_item` | Remove an item | `item_id` | `create_list` accepts `initial_items` to create the list with its first items in one call, so the list and its items are created atomically. Each item is either a text string or an object `{text, deps?}`. `add_item` accepts the same shapes, plus an array of them, to add several items in one call. Item ids are `listName:id`, as the `list` action shows them (e.g. `Work:2`). An id is permanent: it is stored on the item, it is unique within its list, and it is never reused. Removing an item leaves a gap in the numbering instead of shifting the items after it, so a reference you already hold stays valid. `update_item` accepts the scalar form (`item_id` with optional `text`/`done`/`deps`) or a per-list batched form: `list_id` plus an `items` array (`[{item_id, text?, done?, deps?}, ...]`), mirroring `add_item`'s `list_id + text[]` shape, so one batch stays within a single list. Creating a list makes it the active list (the widget switches to it); pass `activate: false` to keep the current active list. The tool validates every call and returns an error that names exactly what to fix: each action accepts only its own parameters, required fields are enforced, and the two `update_item` forms never mix. Read the error and retry with corrected parameters — not-found errors also list the available ids. `update_item` also appends a reminder when one call marks two or more items done and leaves no open items behind (the terminal batch): the working rhythm is to mark each item done in the same turn it completes, never batch the marking at the end. Example prompt: > Create a list called "Work" and add "write plan" to it. Call `set_active` without `list_id` to deselect. The widget hides when no list is active. ### Dependencies and readiness An item can wait for other items. Pass `deps` on the item object when you create it, or through `update_item`, as a list of `listName:id` references to items in the same list. `deps` replaces the whole dependency set, so pass `[]` to clear it. The result names the set before and after whenever the two differ, so a dependency the call dropped does not disappear silently. Dependencies must form a DAG. A dependency must exist, it must be in the same list, and it must not close a cycle. A call that would close one is rejected, and the error names the cycle path (e.g. `Work:1 → Work:2 → Work:1`). Two rules gate mutations: - You can only complete an item after every dependency is done. Completing a blocked item fails, and the error names the blockers. Reopening is never blocked, so you can always repair a mistake. - You cannot remove an item that other items depend on. The error names the dependents. Reopening does not cascade. If you reopen a dependency whose dependents are already done, those dependents stay done and the result adds a note that they are now done but blocked. Giving a done item an open dependency produces the same state and the same note, because a dependency edit would otherwise leave the item silently unsatisfied. The `list` action marks such a row with `(waiting on #Work:1)`: the item is finished, so it is not called blocked. Readiness is derived on every read, never stored. The `list` action marks each blocked item, and it ends every list that has dependencies with a `Ready now` line. A list without a `blocked by` marker has nothing blocked, so an edge-free list is not silent about readiness: it simply has nothing to report, and it keeps the output it had before dependencies existed. A dependency reference that does not resolve counts as a blocker, so a hand-edited snapshot cannot silently unblock work. An `update_item` batch applies its patches in order, so it behaves like the same calls in sequence: one call can complete a chain, and a completion that comes before its blocker in the array is refused. Items render in a stable dependency order: a dependency comes before the items that wait for it. A list with no dependencies keeps its stored order. The stored order itself never changes; only the display order does. The `list` action, the widget, and the `/tracker` items pane all use that order. ### Working through a list The intended rhythm: break multi-step work into items up front (one item per deliverable), work through them one at a time, and mark each done as it completes. The list — shown in the widget — always shows current progress; the agent should read it with `list` before starting and after finishing, and update item text with `update_item` when scope changes. Failed calls are recoverable: the tool's errors say what to fix, and not-found errors name the available ids. The agent corrects the call and retries in the same turn instead of repeating the same failing call. ### The /tracker command Open `/tracker` to manage lists interactively. While the cursor moves over the lists, the items pane below previews the focused list. `enter` commits it as the active list and opens the items pane for editing. | Key | Action | | ------- | -------------------------------------- | | `tab` | Switch between the lists and the items | | `↑` `↓` | Move the cursor | | `enter` | Select a list and open its items | | `space` | Toggle the active list | | `n` | Create a list | | `d` | Delete a list | | `a` | Add an item | | `x` | Toggle an item complete or incomplete | | `e` | Edit the item text | | `r` | Remove an item | | `esc` | Close the view | ### The widget The widget shows the active list above the editor. It appears when a list is active. It hides when no list is active. The widget has a rounded border. The border uses the theme's `border` color. When the list holds more items than the widget can show, the widget keeps the first item, the current item (the first ready item), and the last item visible, then fills the remaining rows around the current item. Items outside that window collapse into a `⋮` row. The `⋮` row appears only when items are hidden between the visible rows. The border label still shows the done and total counts. Each item line starts with one marker: | Marker | Meaning | | ------ | ------------------------------------------------------------ | | `✓` | Done. | | `●` | The current item: the first ready item, in the accent color. | | `○` | Another open item that is ready. | | `⊘` | An open item that waits for an unfinished dependency. | The marker field is two columns wide for every marker, so the text stays flush. The widget and the `list` action show the same derived order and the same readiness, so the two surfaces never disagree. The marker is the widget's whole report of an item's state, so a done item whose dependency was reopened keeps the `✓` there; the `(waiting on ...)` annotation appears in the `list` output and the `/tracker` items pane, which have room for it. ## Persistence The state lives in the session file. Pi writes a snapshot after every change. The state restores on resume, fork, and tree navigation. Changes are applied and written in order, and each result reports the state its own call produced instead of a value another surface cached. A snapshot saved before item ids existed loads with each item id equal to its position, so references in that format still resolve. ## Installation Install from npm: ```bash pi install npm:@ftrdotdev/pi-tracker ``` From git or a local checkout: ```bash pi install git:github.com/felixnorden/pi-mono pi install ./path/to/pi-mono/packages/tracker ``` To try the package without installing it, use `-e` (temporary, current run only): ```bash pi -e npm:@ftrdotdev/pi-tracker ``` Registration lives in `package.json` under the `pi` field: ```json "pi": { "extensions": ["./src/index.ts"] } ``` ## Development | Command | Purpose | | ------------------- | -------------------------------------------- | | `bun test` | Run the test suite (vitest + @effect/vitest) | | `bun test:watch` | Run the test suite in watch mode | | `bunx tsc --noEmit` | Type check | | `bun lint` | Lint with oxlint | ## Project structure | File | Purpose | | -------------------- | ---------------------------------------------------------------- | | `src/domain.ts` | Schema domain model (`TodoItem`, `TodoList`, `TrackerState`) | | `src/deps.ts` | Dependency references, cycle detection, readiness, derived order | | `src/store.ts` | `TrackerStore` service with `Effect.Ref` state | | `src/persistence.ts` | `TrackerPersistence` service (save and restore snapshots) | | `src/ui.ts` | Widget pane and interactive `/tracker` component | | `src/index.ts` | Pi bridge: tool, command, session hooks, widget refresh | | `src/*.test.ts` | Test suites |