pi-otty

Otty terminal notification integration for the pi coding agent — shows processing/idle status badges and fires notifications in the Otty terminal.

Inspired by kimi-otty, which brings the same Otty integration idea to the Kimi Code CLI. This project ports that approach to the pi extension platform.

Features

• Real-time status badges — Displays the pi agent state (processing / idle) in the Otty terminal pane title bar.
• Completion notifications — Fires a system notification when the agent finishes a task.
• Multi-instance support — Matches by session ID and process PID, so multiple pi instances in the same working directory show independent statuses.
• Zero-config — Auto-detects the Otty CLI and silently skips when Otty is not installed, so it never affects the pi session.

How It Works

The extension listens to pi lifecycle events and reports the state to Otty via the otty-cli state:claude IPC command:

pi Event	Otty State	Description
session_start	idle	Session started / resumed
before_agent_start	processing	User submitted a prompt, starting
tool_call	processing	A tool is being called
agent_settled	idle	Agent fully stopped
session_shutdown	idle	Session closed, clear state

Installation

Option 1: pi install (recommended)

pi install npm:pi-otty

Option 2: From GitHub

pi install git:github.com/killpanda/pi-otty

Option 3: From source

git clone https://github.com/killpanda/pi-otty.git
pi install /path/to/pi-otty

Option 4: Manual placement

Copy extensions/index.ts and src/otty-client.ts into pi's extensions directory:

# Global (all projects)
cp -r extensions src ~/.pi/agent/extensions/pi-otty/

# Or project-local
cp -r extensions src .pi/extensions/pi-otty/

Configuration

The extension locates the Otty CLI in the following order:

1. The OTTY_CLI environment variable (if set)
2. The default path /Applications/Otty.app/Contents/MacOS/otty-cli (macOS)

The Otty terminal automatically injects the OTTY_SOCKET environment variable — no manual setup required.

Requirements

• pi coding agent
• Otty (macOS)

Known Limitations

Otty currently only supports the state:claude command for agent lifecycle reporting, so the badge displays "Claude" as the agent name. This is a limitation on the Otty side and does not affect the status badge or notification functionality.

Development

# Clone the repository
git clone https://github.com/killpanda/pi-otty.git
cd pi-otty

# Install dependencies (for type checking)
npm install

# Type check
npx tsc --noEmit

# Quick test
pi -e ./extensions/index.ts

Acknowledgements

• kimi-otty by @youngxhui — This project is directly inspired by kimi-otty, which pioneered Otty terminal integration for the Kimi Code CLI. The event-to-state mapping and the IPC approach via otty-cli state:claude are adapted from kimi-otty's otty-hook.sh. Special thanks to @youngxhui for the clean reference implementation.

License

MIT