# pi-activity

[![pi-activity — extension for PI Agent](https://raw.githubusercontent.com/prjct-app/pi-clipboard/main/docs/covers/pi-activity.png)](https://pi.dev)

Keep PI Agent tool output readable with compact, expandable activity rows and summaries of actions, errors, and changed files.

`@prjct.app/pi-activity` · Tool renderers and activity summaries; one extension.

## Demo

[![Watch the pi-activity promotional demo](https://raw.githubusercontent.com/prjct-app/pi-activity/main/media/pi-activity-demo/poster.png)](https://github.com/prjct-app/pi-activity/raw/refs/heads/main/media/pi-activity-demo/pi-activity-demo.mp4)

[Watch or download the 40-second demo](https://github.com/prjct-app/pi-activity/raw/refs/heads/main/media/pi-activity-demo/pi-activity-demo.mp4). It shows compact live tool rows, expanded diagnostic detail, and the activity inspector for changed files, verification commands, and issues. The film follows the package's monochrome cover identity and uses an original instrumental soundtrack with no voice-over or external samples.

## Install

Requires Pi installed separately and Node.js **22.19 or later**. Compatibility is tested with **Pi 0.85.1**; newer versions are not yet verified. This is an independent community package.

Install with Pi's package manager:

```sh
pi install npm:@prjct.app/pi-activity
```

For project-only installation, add `-l`: `pi install -l npm:@prjct.app/pi-activity`. Restart Pi after installation. Do not install the same extension from both GitHub and npm: Pi treats those as different package identities.

## Usage

Start Pi and ask it to inspect a file or run a command. Tool calls become responsive, semantic activity rows:

```text
◆ RUN     npm test                              1.8s
✓ READ    src/auth.ts                    184 lines
✓ SEARCH  "renderResult"                  8 matches
✓ EDIT    src/auth.ts                    +18 −6
✕ RUN     npm run lint                  exit 1
```

While tools run, a temporary widget shows parallel work above the editor. The footer status distinguishes thinking, active tools, prompts waiting for input, successful runs, and runs with issues. Rows adapt to narrow terminals and use the active Pi theme rather than a fixed palette.

Use Pi's configured tool-output expansion shortcut (`Ctrl+O` by default) for detailed output. Expanded reads and writes include syntax highlighting and line numbers, edits include colored diffs, and truncation evidence and full-output paths remain visible.

After the agent settles, an expandable activity report groups:

- files observed through `edit` and `write`, including available line statistics;
- verification commands such as tests, type checks, builds, and linters;
- errors, cancellations, durations, and truncated results.

Run `/activity` to open the interactive activity inspector. Use its All, Changed, Commands, and Issues filters, then press Enter to inspect metadata and the in-memory result preview. Run `/activity-settings` for the picker, or `/activity-settings forensic` to select a mode directly. Three row densities persist in the session:

- `minimal` — action and target, with failure outcomes;
- `balanced` — outcomes and durations (default);
- `forensic` — balanced metadata plus category and truncation evidence.

The extension retains the native execution functions for the seven built-in tools it overrides. It changes presentation and records activity evidence; it does not audit filesystem changes made indirectly by shell commands. Therefore the report deliberately labels modified files as *observed through edit/write*, not as an exhaustive repository diff. It does not remove thinking transcript rows. Avoid enabling another extension that overrides the same built-in tool renderers.


## Manage the package

For an npm installation:

```sh
pi list
pi update npm:@prjct.app/pi-activity
pi remove npm:@prjct.app/pi-activity
```

Use `pi config` to enable or disable individual resources. Use `pi config -l` for project settings and add `-l` to removal when you installed locally.

To pin version 0.1.3, use `pi install npm:@prjct.app/pi-activity@0.1.3`. Pi skips pinned npm versions during package updates. For a Git installation, update or remove using the same `git:github.com/prjct-app/pi-activity` source instead of the npm source.

When switching from GitHub to npm, remove the Git installation first, then install the npm package and restart Pi.

## Troubleshooting

If the activity rows are missing, inspect enabled resources with `pi config` and check for another extension registering the same tool names. Widgets, custom inspectors, and styled tool output require TUI mode. `/activity` keeps the latest 200 recorded actions available in the current session; persisted summaries restore metadata after resume, while full result previews remain in the original tool entries.

## Package and API documentation

Uses documented `registerTool()` overrides, working-message and working-indicator APIs, lifecycle events, and persisted summary entries.

See [Package structure and compatibility](docs/package.md) for the manifest, dependency policy, shipped resources, and official references. This package follows the [official Pi package guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/packages.md) and [extension API guide](https://github.com/earendil-works/pi/blob/v0.85.1/packages/coding-agent/docs/extensions.md) for the tested version.

## Development

From a repository checkout:

```sh
npm ci --ignore-scripts
npm run check
npm test
npm run check:package
```

Pi loads the TypeScript entry point directly; no build step is required. To try this checkout for one run, use `pi -e .`. Tests use isolated temporary state and do not call model APIs. See [CONTRIBUTING.md](CONTRIBUTING.md) for contribution rules and [CHANGELOG.md](CHANGELOG.md) for release notes.

## License

[MIT](LICENSE).