pi-tmux

A pi coding agent extension that manages a tmux session per project (one per git root).

Install

pi install npm:@romansix/pi-tmux

Or try without installing:

pi -e npm:@romansix/pi-tmux

Features

tmux tool

Provides a tmux tool for the agent with these actions:

• run — Run a command in a new tmux window. When the command finishes, the agent is automatically notified with the exit code and recent output, so it doesn't need to wait around.
• attach — Open a new terminal tab/window attached to the session. Pass window to target a specific window. Supports iTerm2, Terminal.app, kitty, ghostty, WezTerm, and tmux nesting. Falls back to printing the attach command for unsupported terminals.
• peek — Capture recent output from tmux windows. Use window to target a specific window, or omit for all.
• list — List all windows in the session.
• kill — Kill the entire session.
• mute — Suppress silence notifications for a window. Use when a command is expected to have long silence periods, not waiting for input.

Each command's script is echoed before execution (cat "$0") so you can see exactly what's running — including heredocs and complex constructs that set -x would miss.

Silence detection

When running commands that might prompt for input (installers, interactive tools, confirmations), the agent can set silenceTimeout to be notified when the command goes quiet.

Parameter	Description	Default
silenceTimeout	Initial seconds of silence before notifying. 0 or omitted to disable.	—
silenceBackoffFactor	Multiply the interval after each notification.	1.5
silenceBackoffCap	Max silence interval in seconds.	300 (5 min)

The notification includes a peek of the window output so the agent can decide whether to act or mute the window.

Commands

• /tmux — Open a terminal tab attached to the project's tmux session
• /tmux:cat — Select a tmux window and bring its output into the conversation
• /tmux:clear — Kill idle tmux windows (shells with no running child processes)

Library usage

The package exports reusable tmux utility functions from tmux-utils that other extensions can import:

import {
  getGitRoot,
  sessionName,
  ensureSession,
  runInWindow,
  openTerminalTab,
} from "@romansix/pi-tmux/tmux-utils";

// Ensure the project tmux session exists
const gitRoot = getGitRoot(cwd);
const session = sessionName(gitRoot);
ensureSession(session, gitRoot);

// Run a command in a new window and attach
const winIdx = runInWindow(session, gitRoot, "vim foo.ts", "editor");
openTerminalTab(session, winIdx);

Available exports: exec, execSafe, escapeForTmux, getGitRoot, sessionName, sessionExists, ensureSession, getWindows, formatWindowLines, capturePanes, runInWindow, openTerminalTab, attachToSession.

Credits

Inspired by normful/picadillo's run-in-tmux skill.

License

Apache 2.0