---
slug: "99percentpeople-pi-background-tasks"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/99percentpeople/pi-extensions@master/README.md"
repo: "https://github.com/99percentpeople/pi-extensions"
source_file: "README.md"
branch: "master"
---
# Pi Extensions

[![CI](https://github.com/99percentpeople/pi-extensions/actions/workflows/ci.yml/badge.svg)](https://github.com/99percentpeople/pi-extensions/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/github/license/99percentpeople/pi-extensions)](LICENSE)
[![background-tasks](https://img.shields.io/npm/v/%4099percentpeople%2Fpi-background-tasks?label=background-tasks)](https://www.npmjs.com/package/@99percentpeople/pi-background-tasks)
[![pwsh-adapter](https://img.shields.io/npm/v/%4099percentpeople%2Fpi-pwsh-adapter?label=pwsh-adapter)](https://www.npmjs.com/package/@99percentpeople/pi-pwsh-adapter)
[![todo](https://img.shields.io/npm/v/%4099percentpeople%2Fpi-todo?label=todo)](https://www.npmjs.com/package/@99percentpeople/pi-todo)

A focused collection of TypeScript extensions for the
[Pi coding agent](https://pi.dev/): 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`](https://www.npmjs.com/package/@99percentpeople/pi-background-tasks) | Background commands, explicit waits, logs, signals, and optional PTY/TUI interaction |
| pwsh-adapter | [`@99percentpeople/pi-pwsh-adapter`](https://www.npmjs.com/package/@99percentpeople/pi-pwsh-adapter) | PowerShell 7 and Windows PowerShell 5.1 adapter for Pi on Windows |
| todo | [`@99percentpeople/pi-todo`](https://www.npmjs.com/package/@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:

```bash
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:

```powershell
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:

```bash
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:

```text
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](https://github.com/99percentpeople/pi-extensions/blob/HEAD/extensions/background-tasks/README.md)
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](https://github.com/99percentpeople/pi-extensions/blob/HEAD/extensions/todo/README.md)
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.

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

Load an extension directly while developing:

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

Repository layout:

```text
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](https://github.com/99percentpeople/pi-extensions/blob/HEAD/.github/workflows/publish.yml) 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:

```bash
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

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

## License

MIT