---
slug: "pi-window-title"
source_type: "readme"
source_url: "https://cdn.jsdelivr.net/gh/hdkiller/pi-window-title@main/README.md"
repo: "https://github.com/hdkiller/pi-window-title"
source_file: "README.md"
branch: "main"
---
# pi-window-title

Auto-manage pi session titles and tmux window titles for [pi](https://github.com/badlogic/pi-mono) coding sessions.

This project auto-manages pi session titles and tmux window titles with a maintained npm package and git install target.

## Installation

From npm (after publish):

```bash
pi install npm:pi-window-title
```

From git:

```bash
pi install git:github.com/hdkiller/pi-window-title
```

Or run without installing:

```bash
pi -e npm:pi-window-title
# or
pi -e git:github.com/hdkiller/pi-window-title
```

## What it does

- Watches session lifecycle and the first user prompt.
- Generates two names from the prompt:
  - **tmux window title**: concise 3–4 words.
  - **pi session name**: longer 8–12 word summary for `/resume` scanning.
- Persists the session name with `pi.setSessionName(...)`.
- Persists the short tmux title in a custom session entry for reliable restore.
- Renames the current tmux window (when running inside tmux).
- Ships as a maintained extension package for window-title/session-title automation.
- Default title rendering is `π <title-or-status> (<cwd-basename>)`.
- While the agent is actively working, the tmux window title switches to the active form (by default `π ... (<cwd-basename>)`) and restores the idle title when finished.
- Adds `/rename` to recompute names from the current branch conversation so far, or accepts an explicit window name argument.
- Adds `/title-config` to configure the title template, icon, and title-generation behavior from inside pi.
- If generation fails or output is invalid, leaves session/tmux names unchanged.

## Extension behavior

- Names are generated once per session, then reused when switching/resuming sessions when title generation is enabled.
- `/rename` without arguments rebuilds the name from user and assistant message text in the current branch.
- `/rename <window name>` uses the provided argument as the tmux window title and keeps the generated session-name flow for the session metadata.
- `/rename` ignores reasoning blocks, tool calls/results, and images.
- `/title-config show` displays the active template settings.
- `/title-config generation off` disables automatic/generated titles and falls back to `Ready` until you set an explicit `/rename <title>`.
- `/title-config template <value>` supports `{icon}`, `{body}`, `{title}`, `{ready}`, `{active}`, and `{cwd}` placeholders.
- `/title-config icon <value>` changes the prefix symbol/text.
- `/title-config reset` restores the default `π {body} ({cwd})` behavior.
- On `session_start`, tmux restore prefers the stored short title and falls back to a compacted session name.
- Name normalization strips punctuation and keeps alphanumeric words.
- Set `PI_TMUX_WINDOW_NAME_DISABLED=1` to disable the extension completely, including tmux renames and the `/rename` command. This is useful for sub-agents.

## Development

```bash
npm run pack:check
```

## License

Apache-2.0