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.
• Give an item a short title, a longer description, and optional declarations.
• Mark an item as complete or incomplete.
• Declare dependencies between items, so work happens in order.
• Declare the references and products an item needs, so the next step survives compaction.
• Persist todolists with the session.
• Show the active todolist in a widget above the editor.
• Start Pi's compaction when a completed item's detail is no longer needed.

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:

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. Every item is an object {title, description?, refs?, produces?, deps?}, and add_items takes the same objects in its items array, so an item is always declared the same way. A title is one short action line, at most 200 characters; put the longer detail in description.

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_items accepts the scalar form (item_id with optional title/description/refs/produces/done/deps) or a per-list batched form: list_id plus an items array ([{item_id, title?, description?, refs?, produces?, done?, deps?}, ...]), mirroring add_items' list_id + items 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_items forms never mix. Read the error and retry with corrected parameters. Not-found errors also list the available ids. update_items 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.

Titles, descriptions, and declarations

Every item has a required title: one short action line, at most 200 characters. An item may also carry a description with the longer detail. The widget shows the title, with the description dimmed on the line below; the /tracker items pane shows the full description.

An item may declare two optional lists:

• refs: what the item must read after the completed work. Each entry is {kind: "path", path, symbol?, span?} or {kind: "decision", topic}.
• produces: every document the item will write. Each entry is {path}.

Declarations tell the tracker what the next step needs. At the settle boundary the tracker resolves a declared path against disk. If the detail is readable there, the rule table can compact the completed work and keep the next step moving without a classifier call. After a session restore there is no tool footprint, so references resolve as unresolved and only products check disk.

Dependencies and readiness

An item can wait for other items. Pass deps on the item object when you create it, or through update_items, 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_items 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 in the widget always shows current progress. The agent reads it with list before starting and after finishing, and updates an item's title or description with update_items 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.

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:

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.

Smart compaction

When you complete an item in the active list, pi-tracker decides whether the ready items need the completed work. A measured rule row runs first. When an accepted row fires, it decides the whole ready frontier on its own. Every other row reports its name and hands the frontier to the classifier, which judges up to maxCandidates entries, dependents first. Each candidate gets one two-label choice question: needs-context or stands-alone. The answer carries a probability and a confidence. When no ready item needs the detail, pi-tracker starts Pi's compaction at the settle boundary and then resumes the session with a pointer to the next ready item.

The feature reads five keys from tui.json, under smartCompaction:

needsContextProbabilityThreshold is the probability knob: raise it to compact more often, lower it to keep context more often. It cuts on the probability the classifier assigns to needs-context, not on its confidence. minAnswerConfidence is a separate guard on the answer's self-reported confidence: when the model is less confident than the floor, pi-tracker keeps the context. This guard only adds keeping, so it can never cause a premature compaction. Both keys still accept their pre-rename names (keepContextThreshold, keepContextMinConfidence) as aliases; the current key wins when both are present. maxCandidates bounds the classifier input; when more items are ready than the cap, the first maxCandidates are judged, dependents first.

A value outside the range in the table falls back to the default. The feature fails open. A disabled feature, no credential-available classifier, a classifier error or timeout, an aborted run, or a list with no ready item keeps the full context. The classifier input is the item list only. The transcript never leaves the session. An unaccepted rule row abstains, so it never compacts on its own.

The rule table lives in src/compaction/rules.ts. Only rows in ACCEPTED_RULES compact on their own. A row enters that set only when the eval gate accepts it on labeled decisions: at least 10 labeled firings, at least 95% agreement, above the pass base rate, in at least two passes. Every decision on an item with declarations records the fired row and the resolved states as a tracker/reliance-decision session entry, which the eval reads back. bun run eval:rules prints the tables and the gate.

The /tui command edits all five on a Compaction tab: Smart compaction (toggle), Compaction classifier (picker), Needs-context probability, Answer confidence floor, and Max candidates (+ and - adjust the numeric rows). The Compaction tab appears only while the tracker extension is loaded.

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. A snapshot written before the title/description split loads with the first line as the title and the rest as the description.

Installation

Install from npm:

pi install npm:@ftrdotdev/pi-tracker

From git or a local checkout:

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):

pi -e npm:@ftrdotdev/pi-tracker

Registration lives in package.json under the pi field:

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

Development

Project structure