Pi Extensions

A focused collection of TypeScript extensions for the Pi coding agent: run and revisit background tasks, use PowerShell consistently on Windows, and keep model-authored plans visible in the TUI.

Extension	npm package	Purpose
background-tasks	@99percentpeople/pi-background-tasks	Background commands, explicit waits, logs, signals, and optional PTY/TUI interaction
pwsh-adapter	@99percentpeople/pi-pwsh-adapter	PowerShell 7 and Windows PowerShell 5.1 adapter for Pi on Windows
todo	@99percentpeople/pi-todo	Minimal atomic whole-plan todo writes with dependencies and a read-only list above the input

The packages have separate versions and releases. Installing one extension does not install or enable either of the others.

Highlights

• Install only the capabilities you need; every extension is an independent npm package.
• Integrate with Pi's native tools, widgets, session history, and terminal UI.
• Support interactive PTY applications, persistent task snapshots, and cross-platform shell execution.
• Validate on Linux, macOS, and Windows, with tag-driven npm releases through GitHub Actions Trusted Publishing.

Installation

Install background task support on Linux, macOS, or Windows:

pi install npm:@99percentpeople/pi-background-tasks

On Windows, install the optional adapter when both Pi's bash tool and bg_start should use PowerShell syntax:

pi install npm:@99percentpeople/pi-pwsh-adapter

Without the adapter, bg_start follows Pi's configured Bash resolution and command prefix, including Git Bash on Windows.

Install the snapshot-based todo extension after removing another extension that registers the same todo tool:

pi remove npm:@juicesharp/rpiv-todo
pi install npm:@99percentpeople/pi-todo

background-tasks

Tools:

• bg_start starts a pipe or PTY background task.
• bg_wait waits once for a finite task to finish or time out.
• bg_status reads task metadata or lists known tasks.
• bg_logs is the only tool that reads pipe or parsed PTY output.
• bg_send sends text, terminal keys, or supported process signals.
• bg_kill terminates a task.

Commands:

• /bg-attach <id> attaches to a PTY or streams new pipe output. Press Ctrl+] to detach.
• /bg-kill selects and terminates a running task.

Example:

bg_start name="git-ui" command="lazygit" pty=true
/bg-attach <task-id>

Terminal keys sent through bg_send use angle-bracket tokens such as <C-c>, <A-f>, <Space>, <Up>, and <F10>. Escape a literal < as \<. Same-task calls in one model response execute in source order, so bg_wait → bg_logs waits before reading output while different task chains can run in parallel. The same sequence works for pipe and PTY tasks.

PTY support uses node-pty. If no compatible native binary is available, installation may require a C/C++ toolchain. See the background-tasks package documentation for details.

pwsh-adapter

The adapter is a Windows-only package that:

• prefers PowerShell 7 (pwsh.exe) and falls back to Windows PowerShell 5.1 (powershell.exe);
• replaces Pi's Bash execution backend with the selected runtime;
• configures UTF-8 input and output;
• makes background-tasks use the same PowerShell syntax;
• keeps PTY tasks interactive.

The startup notification and tool prompt identify the selected version so the model can avoid PowerShell 7-only syntax when running Windows PowerShell 5.1.

todo

The todo tool replaces per-task CRUD calls with one atomic tasks[] snapshot. Stable task keys allow dependencies to reference tasks created in the same call. Updates include the complete current key list but may omit unchanged fields, so one compact call can complete the current task and start the next. The list is authoritative: omitted keys are deleted directly, stale revisions can be rejected, and invalid dependency graphs do not partially mutate state. Deleted tasks leave no cancelled status or archived record.

The extension deliberately registers no slash commands or interactive manager. A read-only widget above the input shows the current task when collapsed and the complete list when expanded with Pi's standard Ctrl+O binding. Task keys stay model-only, so user-facing rows contain only a status glyph and task name. The tool call itself remains a compact progress confirmation. Completed tasks stay visible for the current response, then are automatically removed before the next response unless unfinished work still depends on them. Exact state follows Pi session branches, survives reloads, and is checkpointed back into model context after compaction. See the todo package documentation for the schema.

Development

The repository uses a private root package as a Bun 1.3.14 workspace. Each extension directory is an independently publishable npm package.

bun install --frozen-lockfile
bun run check
bun run pack:check

Load an extension directly while developing:

pi -e ./extensions/background-tasks/index.ts
pi -e ./extensions/todo/index.ts

Repository layout:

extensions/
├── background-tasks/
│   ├── index.ts
│   ├── package.json
│   └── README.md
├── pwsh-adapter/
│   ├── index.ts
│   ├── package.json
│   └── README.md
└── todo/
    ├── index.ts
    ├── state.ts
    ├── package.json
    └── README.md
tests/
├── background-tasks.test.ts
├── todo.test.ts
└── packages.test.ts

Automated npm releases

The publish workflow uses npm Trusted Publishing with GitHub Actions OIDC. It does not require an NPM_TOKEN GitHub secret.

Before the first automated release, configure a Trusted Publisher separately for all three npm packages:

• Provider: GitHub Actions
• Organization or user: 99percentpeople
• Repository: pi-extensions
• Workflow filename: publish.yml
• Allowed action: npm publish

Release tags are package-specific because the packages are versioned independently:

Package	Tag format	Example
background-tasks	background-tasks-v<version>	background-tasks-v1.1.3
pwsh-adapter	pwsh-adapter-v<version>	pwsh-adapter-v1.0.1
todo	todo-v<version>	todo-v1.1.2

To publish a release:

1. Update the selected package's version in package.json and update its package README when needed.
2. Run bun run pack:check and commit the release changes.
3. Push the commit, then create and push the matching tag:

git tag background-tasks-v1.1.3
git push origin master background-tasks-v1.1.3

The workflow rejects a tag whose version does not exactly match the selected package's package.json.

Uninstall

pi remove npm:@99percentpeople/pi-background-tasks
pi remove npm:@99percentpeople/pi-pwsh-adapter
pi remove npm:@99percentpeople/pi-todo

License

MIT