@claaslange/pi-progress-bar

A small pi package that emits terminal progress updates via OSC 9;4.

Why this package exists

This package was inspired by HazAT/pi-ghostty.

That extension combines terminal titles and progress indicators in one package. For this package, we wanted to split those concerns on purpose:

• progress updates should be usable on their own
• terminal title behavior should stay configurable elsewhere
• users should be able to combine this with their own title workflow or another title-focused extension

So @claaslange/pi-progress-bar only handles OSC 9;4 progress signaling and intentionally leaves terminal titles untouched.

Behavior

• 🔵 Indeterminate pulse while the agent is thinking or running tools
• 🔴 Red error state when a tool finishes with an error
• 🔵 Error state resets back to indeterminate progress after the next non-error tool completion
• 🟢 Green 100% completion flash when the agent finishes cleanly
• Clears the progress indicator on shutdown
• Does not modify the terminal title

Install

From npm:

pi install npm:@claaslange/pi-progress-bar

From GitHub:

pi install git:github.com/claaslange/pi-progress-bar

From a local checkout:

pi install /absolute/path/to/pi-progress-bar

Or run it directly without installing:

pi -e /absolute/path/to/pi-progress-bar

Compatibility and detection

This extension uses an optimistic runtime check before writing OSC 9;4 sequences.

For local testing, you can force it on with:

PI_PROGRESS_BAR_FORCE=1 pi -e /absolute/path/to/pi-progress-bar

If you want to disable it even in a supported terminal, use:

PI_PROGRESS_BAR_DISABLE=1 pi -e /absolute/path/to/pi-progress-bar

At the moment that includes common terminal markers for Ghostty, WezTerm, iTerm, Windows Terminal, ConEmu, and tmux passthrough.

A good reference for terminal compatibility and detection is the tracking work in jdx/mise#7485.

How it works

The extension listens to pi lifecycle events and writes OSC 9;4 sequences directly to /dev/tty:

| Pi event | Action | | --- | --- | | agent_start | start indeterminate progress | | tool_execution_end / tool_result with isError: true | show red error state | | tool_execution_end / tool_result with isError: false after an error | switch back to indeterminate progress | | agent_end | flash green 100% completion, then clear if no error is active; otherwise clear | | session_shutdown | clear progress |

Because it writes directly to the terminal, it stays out of pi's normal TUI rendering.

Development

Run a local manual check that exercises busy → error → reset → success:

npm run check
npm run test:manual

Package contents

This package exposes a single extension entrypoint at ./extensions/index.ts through the pi manifest in package.json.

License

MIT