---
slug: "johnnywu-pi-terminal-signals"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/jwu/pi-terminal-signals@main/README.md"
repo: "https://github.com/jwu/pi-terminal-signals"
source_file: "README.md"
branch: "main"
---
# pi-terminal-signals

Let's pi send standard OSC escape sequences to inform the terminal it is running in of its status.

Ghostty will display a progress line at the top while pi is running the agent loop.
Supacode, Supaterm and Conductor use it to display a spinner / finished icon on the worktree / agent tab.

## Demo

https://github.com/user-attachments/assets/911ac2fb-f505-4a66-8593-b12afdcb710a

*Unmute for audio.*

## Install

```bash
pi install npm:@jwu/pi-terminal-signals
```

## What it does

| Pi event | Escape sequence | Terminal effect |
|---|---|---|
| `agent_start` | `OSC 9;4;3` | Tab shows indeterminate progress spinner |
| `agent_end` | `OSC 9;4;0` | Progress indicator clears |
| `agent_end` | `OSC 133;D;0` | "Command finished" — triggers completion notification |

**OSC 9;4** — Progress indicator protocol (originated in ConEmu, adopted by Ghostty, WezTerm, Windows Terminal). State 3 is indeterminate (spinner), state 0 clears.

**OSC 133** — Semantic prompt protocol (originated in FinalTerm, adopted by Ghostty, iTerm2, Kitty, WezTerm, VS Code terminal). Marker `D;0` means "command finished successfully" — Ghostty uses this to fire a tab completion notification.