@minty1st/pi-todo-timeline
Pi extension. A todo list with timed progress reports, shown in panels above the editor and on an HTML page.
Package details
Install @minty1st/pi-todo-timeline from npm and Pi will load the resources declared by the package manifest.
$ pi install npm:@minty1st/pi-todo-timeline- Package
@minty1st/pi-todo-timeline- Version
0.2.0- Published
- Nov 15, 2026
- Downloads
- 483/mo · 483/wk
- Author
- minty1st
- License
- MIT
- Types
- extension
- Size
- 134 KB
- Dependencies
- 0 dependencies · 0 peers
Pi manifest JSON
{
"extensions": [
"./src/index.ts"
]
}Security note
Pi packages can execute code and influence agent behavior. Review the source before installing third-party packages.
README
pi-todo-timeline
A Pi extension that keeps a task list and timed progress reports in view during long agent sessions.
- Tasks: the model plans and tracks work with a
todotool. Completed tasks stay visible, each with a one-line result. - Reports: while work continues, a separate model call summarizes every 15 minutes what changed, what is undecided, and what you can do in parallel. Hourly reports combine them.
- Views: two panels above the editor, one HTML page per session, and the
/timelinecommand.
It is built for Pi Web, where each panel opens from a button and the page opens in a popup. It also runs in Pi's terminal UI, with shorter panels.
The page for one session, as the timeline and reports buttons open it in Pi Web. The panels show the same content as colored text; in Pi's terminal UI they sit above the editor:
Requirements
- Node.js 24.21 or later and Pi 1.5 or later.
- Linux or Windows. Tested on WSL2 and on Windows 11 with Pi 1.5.2; macOS is untested.
- A model for reports is optional. Without one, tasks, panels, and the page still work.
- Pi Web is the intended interface, though not required. It shows each panel behind a button and previews the page beside the chat, or in a popup. Pi's terminal UI shows both panels above the editor at once and cuts each to 10 lines.
- The interface text is Japanese. Reports are written in Japanese by default;
languagechanges that.
Install
pi install npm:@minty1st/pi-todo-timeline
Or install the latest source with pi install git:github.com/MINTY1st/pi-todo-timeline. Restart Pi or run /reload afterwards.
Pi fails to start when two extensions register a tool with the same name. Remove any other extension that registers a tool named todo, or set todoTool to false.
Usage
Tasks need no setup. Ask for work with several steps and the model creates tasks, marks one in progress, and records a one-line result when it completes each one. The timeline panel updates after every change.
To get reports, name a model in ~/.config/pi-todo-timeline/config.json:
{
"provider": "<a provider configured in Pi>",
"model": "<model id>"
}
The first report appears after 15 minutes of work, at the end of a turn. Reports are stored in the session and never enter the model's context.
/timeline Show tasks and reports as text, and the path of the page
/timeline now Create a report for the work so far, then show them
The page is written to <working directory>/.pi/timeline/ after each turn. Open it in Pi Web's file preview to keep it beside the chat; it refreshes when the file changes. With the popup below, the timeline and reports buttons open it directly.
Configuration
The file is $PI_TODO_TIMELINE_CONFIG, else $XDG_CONFIG_HOME/pi-todo-timeline/config.json, else ~/.config/pi-todo-timeline/config.json (C:\Users\<name>\.config\... on Windows). Run /reload after editing it. Invalid values fall back to the default and are listed by /timeline.
| Setting | Default | Description |
|---|---|---|
provider, model |
Unset | Model that writes reports. No reports are created while unset. |
reasoning |
Unset | Thinking level for report calls. Required for models that cannot turn thinking off. |
enabled |
true |
false stops report creation. |
intervalMinutes |
15 |
Interval of base reports. |
rollupFactor |
4 |
Base reports are combined after this many intervals. |
maxInputChars |
40000 |
Session text sent per report. The rest is carried to the next report. |
language |
日本語 |
Language of reports and task results, as named in the instructions. |
notify |
true |
Notify when a report is created. |
todoTool |
true |
Register the todo tool. |
panel |
true |
Show the panels. panelMaxTasks (10) limits the listed tasks. |
page |
true |
Write the page. pageDirectory (.pi/timeline) sets where. |
webPopup |
true |
Add the popup to Pi Web, as described below. |
panelMaxHeightPercent |
50 |
Panel height limit, in percent of the window height, in Pi Web. |
Also available: maxItemChars, maxLineChars, maxOutputTokens, timeoutSeconds, and focus; see src/core/config.ts.
Popup and panel height in Pi Web
Pi Web draws extension panels as colored text and limits them to 144px. When the extension runs inside Pi Web, it changes both at the start of each session by appending marked blocks to Pi Web's own files:
- a script that opens the page in a popup when you click the
timelineorreportsbutton, in the colors of Pi Web's current theme; - a CSS rule that raises the panel height limit.
Nothing needs to be run. When the blocks are added, a notice asks you to reload the browser without cache (Ctrl+Shift+R) once; this is needed again after installing the extension and after updating Pi Web, which removes the blocks. In Pi's terminal UI, Pi Web's files are not touched.
Click the same button again, or ×, to close the popup; Shift-click opens the text panel instead. The popup does not use Esc, which stops the running turn in Pi Web. webPopup: false removes the script at the next session start.
To remove both blocks after uninstalling, update Pi Web, or run the bundled command from a git install or a source checkout (Node does not execute TypeScript files under node_modules):
node ~/.pi/agent/git/github.com/MINTY1st/pi-todo-timeline/src/pi-web/cli.ts remove
Limitations
- Reports send session text (messages, tool calls, and clipped tool results) to the configured model. Choose a provider you may send that work to.
- A reply that is cut off or is not valid JSON is discarded, and the report is retried at a later turn. A reply that only breaks the size rules is repaired once.
- Work shorter than the interval produces no report until you resume or run
/timeline now. - A completed task cannot be reopened; it can only be deleted. Dependency cycles are not checked.
- Pi Web's files must be writable by the user running it; otherwise a notice explains why the popup is missing. The popup relies on Pi Web's page structure and file API, checked with Pi Web 0.15.0; if they change, the buttons open the text panels as before.
- The popup looks for the page in
.pi/timelineunder the session's working directory, so it does not find a custompageDirectory. - Pages are written per session and never deleted. In a git working tree the directory is added to
.git/info/exclude, except in worktrees and subdirectories of a repository. - On Windows, model calls and the Pi Web views have not been run; unit tests, loading, panels, the page, and the Pi Web command have.
Development
npm ci
npm test
npm run check
npm pack --dry-run
Tests use a fake Pi host and a fake model; they need no Pi installation. The CI workflow runs npm ci --ignore-scripts, npm test, and npm run check on Node 24.22.2, on Linux and Windows, for every pull request and every push to main.
Publishing
An owner-pushed vX.Y.Z tag triggers the publishing workflow.
The tagged commit must be in main, and the tag, manifest, and lockfile versions must match.
Tests and type checks run without publishing credentials; a separate job publishes the verified tarball.
After the package is published, a third job creates the GitHub Release for the tag with generated notes.
One-time npm setup: npm cannot publish the first version of a package through Trusted Publishing, so publish it once manually.
Then, in the package's Settings → Trusted Publisher, select GitHub Actions, set the owner and repository to this repository,
and enter publish.yml as the workflow filename. Leave the environment name empty. No npm token or GitHub secret is needed afterwards.
Only stable versions are supported. Existing npm versions cannot be overwritten.
License
Licensed under MIT. See third-party notices for the notices of the works this package draws on.