pi-window-title

Auto-manage pi session titles and tmux window titles for pi 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):

pi install npm:pi-window-title

From git:

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

Or run without installing:

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

npm run pack:check

License

Apache-2.0