# pi-otty

**⚠️NOTE: otty v1.3.1 officially supports pi coding agent. So you don't need this project any more.**


Otty terminal notification integration for the [pi coding agent](https://pi.dev) — shows processing/idle status badges and fires notifications in the [Otty](https://otty.sh/) terminal.

Inspired by [kimi-otty](https://github.com/youngxhui/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)

```bash
pi install npm:pi-otty
```

### Option 2: From GitHub

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

### Option 3: From source

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

```bash
# 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](https://pi.dev)
- [Otty](https://otty.sh/) (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

```bash
# 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](https://github.com/youngxhui/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](./LICENSE)