@ogulcancelik/pi-tmux 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Can Celik
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# pi-tmux
+
+Tmux pane management for [pi](https://github.com/badlogic/pi-mono). Run dev servers, watchers, and long-running processes in named panes without blocking the agent.
+
+## Install
+
+```bash
+pi install npm:@ogulcancelik/pi-tmux
+```
+
+Or add manually to `~/.pi/agent/settings.json`:
+
+```json
+{
+  "packages": ["npm:@ogulcancelik/pi-tmux"]
+}
+```
+
+## What it does
+
+Gives the agent a `tmux` tool with five actions:
+
+| Action | Description |
+|--------|-------------|
+| **run** | Start a command in a named pane |
+| **read** | Capture output from a named pane |
+| **send** | Send keys (`C-c`, `Enter`, etc.) or literal text to a pane |
+| **stop** | Kill a named pane |
+| **list** | List all managed panes |
+
+The agent uses `tmux run` for long-running processes (dev servers, file watchers, builds) and `bash` for short-lived commands. This keeps the agent unblocked while background processes run.
+
+## Layout
+
+Pi runs on the left. The first worker pane splits to the right. Additional panes stack vertically below existing ones. You can override with `position: "right"` or `position: "bottom"`.
+
+## How it works
+
+- Panes are tagged with `@pi_name` tmux user options for reliable discovery
+- ANSI escape sequences are stripped from captured output
+- Dead panes are automatically replaced on `run`
+- The tool self-disables when pi is not running inside tmux
+
+## Requirements
+
+- [pi](https://github.com/badlogic/pi-mono) v0.40+
+- [tmux](https://github.com/tmux/tmux) — pi must be running inside a tmux session
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,436 @@
+/**
+ * tmux extension — gives the agent named panes for long-running processes.
+ *
+ * Actions:
+ *   run   — create a named pane (split right) and run a command in it
+ *   read  — capture output from a named pane
+ *   send  — send keys to a named pane (C-c, Enter, q, etc.)
+ *   stop  — kill a named pane
+ *   list  — list all managed panes
+ *
+ * Panes are tagged with @pi_name tmux user options for discovery.
+ * The tool is disabled when not running inside tmux.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { truncateTail, DEFAULT_MAX_BYTES, DEFAULT_MAX_LINES, formatSize } from "@mariozechner/pi-coding-agent";
+import { StringEnum } from "@mariozechner/pi-ai";
+import { Text } from "@mariozechner/pi-tui";
+import { Type } from "@sinclair/typebox";
+
+interface PaneInfo {
+	name: string;
+	paneId: string;
+	alive: boolean;
+	command: string;
+	pid: string;
+}
+
+// Strip ANSI escapes, OSC sequences, and tmux/wezterm wrapping
+function stripAnsi(text: string): string {
+	return (
+		text
+			// OSC sequences (e.g. \x1b]...\x07 or \x1b]...\x1b\\)
+			.replace(/\x1b\].*?(?:\x07|\x1b\\)/g, "")
+			// tmux passthrough (\x1bPtmux;...\x1b\\)
+			.replace(/\x1bPtmux;.*?\x1b\\/g, "")
+			// CSI sequences (\x1b[...letter)
+			.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, "")
+			// Remaining bare escapes
+			.replace(/\x1b[^[\]P]/g, "")
+			// Carriage returns (terminal rewrite lines)
+			.replace(/\r/g, "")
+	);
+}
+
+export default function (pi: ExtensionAPI) {
+	const inTmux = !!process.env.TMUX;
+	let myPaneId: string | null = null;
+	let myWindowId: string | null = null;
+
+	// Discover our own pane/window/session on startup
+	pi.on("session_start", async () => {
+		if (!inTmux) {
+			// Disable the tmux tool
+			const active = pi.getActiveTools();
+			pi.setActiveTools(active.filter((t) => t !== "tmux"));
+			return;
+		}
+
+		try {
+			const result = await pi.exec("tmux", [
+				"display-message",
+				"-p",
+				"-t",
+				process.env.TMUX_PANE || "",
+				"#{pane_id}\t#{window_id}\t#{session_id}",
+			]);
+			if (result.code === 0) {
+				const [paneId, windowId] = result.stdout.trim().split("\t");
+				myPaneId = paneId || null;
+				myWindowId = windowId || null;
+			}
+		} catch {}
+	});
+
+	// --- helpers ---
+
+	function requireWindowTarget(): string {
+		if (!myWindowId) throw new Error("Could not determine current tmux window.");
+		return myWindowId;
+	}
+
+	async function findPane(name: string): Promise<PaneInfo | null> {
+		const result = await pi.exec("tmux", [
+			"list-panes",
+			"-t",
+			requireWindowTarget(),
+			"-F",
+			"#{pane_id}\t#{@pi_name}\t#{pane_current_command}\t#{pane_pid}\t#{pane_dead}",
+		]);
+		if (result.code !== 0) return null;
+
+		for (const line of result.stdout.trim().split("\n")) {
+			const [paneId, paneName, command, pid, dead] = line.split("\t");
+			if (paneName === name) {
+				return { name: paneName, paneId, alive: dead !== "1", command, pid };
+			}
+		}
+		return null;
+	}
+
+	async function listAllPanes(): Promise<PaneInfo[]> {
+		const result = await pi.exec("tmux", [
+			"list-panes",
+			"-t",
+			requireWindowTarget(),
+			"-F",
+			"#{pane_id}\t#{@pi_name}\t#{pane_current_command}\t#{pane_pid}\t#{pane_dead}",
+		]);
+		if (result.code !== 0) return [];
+
+		const panes: PaneInfo[] = [];
+		for (const line of result.stdout.trim().split("\n")) {
+			if (!line.trim()) continue;
+			const [paneId, paneName, command, pid, dead] = line.split("\t");
+			// Skip pi's own pane
+			if (paneId === myPaneId) continue;
+			panes.push({
+				name: paneName?.trim() || "",
+				paneId,
+				alive: dead !== "1",
+				command,
+				pid,
+			});
+		}
+		return panes;
+	}
+
+	async function capturePane(paneId: string, lines: number): Promise<string> {
+		const result = await pi.exec("tmux", ["capture-pane", "-t", paneId, "-p", "-S", `-${lines}`]);
+		if (result.code !== 0) throw new Error(`capture-pane failed: ${result.stderr}`);
+
+		let output = stripAnsi(result.stdout);
+		// Trim trailing blank lines (tmux pads to pane height)
+		output = output.replace(/\n+$/, "\n");
+		return output;
+	}
+
+	// --- tool ---
+
+	pi.registerTool({
+		name: "tmux",
+		label: "tmux",
+		description:
+			"Manage tmux panes for long-running processes (dev servers, watchers, etc). " +
+			"Actions: run (start command in named pane), read (capture output), send (send keys like C-c), stop (kill pane), list (show panes).",
+		promptGuidelines: [
+			"Use `tmux` run for long-running processes (dev servers, watchers, builds) instead of `bash`.",
+			"Use `bash` only for short-lived commands that complete quickly.",
+			"Layout: pi runs on the left. Worker panes are created on the right, stacked vertically. First pane splits right from pi, additional panes automatically stack below existing ones.",
+		],
+		parameters: Type.Object({
+			action: StringEnum(["run", "read", "send", "stop", "list"] as const, {
+				description: "Action to perform",
+			}),
+			pane: Type.Optional(Type.String({ description: "Pane name (required for run/read/send/stop)" })),
+			command: Type.Optional(Type.String({ description: "Shell command to run (for run action)" })),
+			keys: Type.Optional(
+				Type.String({
+					description: "Keys to send, space-separated (for send action). Examples: C-c, Enter, q, y",
+				}),
+			),
+			text: Type.Optional(
+				Type.String({
+					description: "Literal text to type into the pane (for send action). Sent as-is, no key lookup.",
+				}),
+			),
+			lines: Type.Optional(
+				Type.Number({ description: "Scrollback lines to capture (for read action, default: 20)" }),
+			),
+			restart: Type.Optional(
+				Type.Boolean({ description: "Kill existing pane before starting (for run action, default: false)" }),
+			),
+			cwd: Type.Optional(Type.String({ description: "Working directory (for run action)" })),
+			position: Type.Optional(
+				StringEnum(["right", "bottom"] as const, {
+					description: "Pane position (for run action, default: right)",
+				}),
+			),
+		}),
+
+		async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+			if (!inTmux) {
+				throw new Error("Not running inside tmux.");
+			}
+
+			const { action } = params;
+
+			switch (action) {
+				case "run": {
+					const { pane, command, restart, cwd, position } = params;
+					if (!pane) throw new Error("'pane' is required for run");
+					if (!command) throw new Error("'command' is required for run");
+
+					const existing = await findPane(pane);
+
+					// Dead pane → always replace. Alive pane → error unless restart.
+					if (existing?.alive && !restart) {
+						throw new Error(
+							`Pane '${pane}' already exists (running ${existing.command}). Use restart: true to replace it.`,
+						);
+					}
+					if (existing) {
+						await pi.exec("tmux", ["kill-pane", "-t", existing.paneId]);
+					}
+
+					// Layout: first pane splits right from pi, additional panes stack
+					// below existing panes (vertical stack on the right side).
+					// Explicit position overrides this behavior.
+					// Uses all panes (not just managed) for correct layout awareness.
+					const allOtherPanes = await listAllPanes();
+					let splitFlag: string;
+					let splitTarget: string | null = null;
+
+					if (position === "right") {
+						splitFlag = "-h";
+					} else if (position === "bottom") {
+						splitFlag = "-v";
+					} else if (allOtherPanes.length > 0) {
+						// Auto: stack below the last existing pane
+						splitFlag = "-v";
+						splitTarget = allOtherPanes[allOtherPanes.length - 1].paneId;
+					} else {
+						// Auto: first pane goes to the right of pi
+						splitFlag = "-h";
+					}
+
+					const splitArgs = ["split-window", "-d", splitFlag, "-P", "-F", "#{pane_id}"];
+					splitArgs.push("-t", splitTarget ?? myPaneId ?? requireWindowTarget());
+					if (cwd) splitArgs.push("-c", cwd);
+
+					const result = await pi.exec("tmux", splitArgs);
+					if (result.code !== 0) throw new Error(`split-window failed: ${result.stderr}`);
+
+					const newPaneId = result.stdout.trim();
+
+					// Tag with name
+					await pi.exec("tmux", ["set-option", "-p", "-t", newPaneId, "@pi_name", pane]);
+
+					// Send command (literal text + Enter)
+					await pi.exec("tmux", ["send-keys", "-l", "-t", newPaneId, command]);
+					await pi.exec("tmux", ["send-keys", "-t", newPaneId, "Enter"]);
+
+					// Wait briefly and capture initial output
+					await new Promise((r) => setTimeout(r, 1500));
+					const initialOutput = await capturePane(newPaneId, 20);
+
+					return {
+						content: [
+							{
+								type: "text",
+								text: `Started '${command}' in pane '${pane}' (${newPaneId})\n\n${initialOutput}`,
+							},
+						],
+						details: { action: "run", pane, paneId: newPaneId, command, position: position ?? "right" },
+					};
+				}
+
+				case "read": {
+					const { pane, lines } = params;
+					if (!pane) throw new Error("'pane' is required for read");
+
+					const existing = await findPane(pane);
+					if (!existing) throw new Error(`Pane '${pane}' not found. Use action 'list' to see managed panes.`);
+
+					const output = await capturePane(existing.paneId, lines ?? 20);
+
+					const truncation = truncateTail(output, {
+						maxLines: DEFAULT_MAX_LINES,
+						maxBytes: DEFAULT_MAX_BYTES,
+					});
+
+					let text = truncation.content;
+					if (truncation.truncated) {
+						text = `[Showing last ${truncation.outputLines} of ${truncation.totalLines} lines]\n${text}`;
+					}
+
+					return {
+						content: [{ type: "text", text }],
+						details: { action: "read", pane, alive: existing.alive, command: existing.command },
+					};
+				}
+
+				case "send": {
+					const { pane, keys, text } = params;
+					if (!pane) throw new Error("'pane' is required for send");
+					if (!keys && !text) throw new Error("'keys' or 'text' is required for send");
+
+					const existing = await findPane(pane);
+					if (!existing) throw new Error(`Pane '${pane}' not found.`);
+
+					// Send literal text first (if provided)
+					if (text) {
+						await pi.exec("tmux", ["send-keys", "-l", "-t", existing.paneId, text]);
+					}
+
+					// Then send special keys (if provided)
+					if (keys) {
+						const keyArgs = keys.split(/\s+/).filter(Boolean);
+						await pi.exec("tmux", ["send-keys", "-t", existing.paneId, ...keyArgs]);
+					}
+
+					const desc = [text && `"${text}"`, keys].filter(Boolean).join(" + ");
+					return {
+						content: [{ type: "text", text: `Sent ${desc} to pane '${pane}'` }],
+						details: { action: "send", pane, keys, text },
+					};
+				}
+
+				case "stop": {
+					const { pane } = params;
+					if (!pane) throw new Error("'pane' is required for stop");
+
+					const existing = await findPane(pane);
+					if (!existing) throw new Error(`Pane '${pane}' not found.`);
+
+					if (existing.paneId === myPaneId) {
+						throw new Error("Refusing to kill the pane pi is running in.");
+					}
+
+					await pi.exec("tmux", ["kill-pane", "-t", existing.paneId]);
+
+					return {
+						content: [{ type: "text", text: `Stopped pane '${pane}'` }],
+						details: { action: "stop", pane },
+					};
+				}
+
+				case "list": {
+					const panes = await listAllPanes();
+
+					if (panes.length === 0) {
+						return {
+							content: [{ type: "text", text: "No panes (besides pi)." }],
+							details: { action: "list", panes: [] },
+						};
+					}
+
+					const text = panes
+						.map((p) => {
+							const label = p.name || `[${p.command}]`;
+							const managed = p.name ? "" : " (unmanaged)";
+							return `${label}: ${p.alive ? "running" : "dead"} (${p.command}) [${p.paneId}]${managed}`;
+						})
+						.join("\n");
+
+					return {
+						content: [{ type: "text", text }],
+						details: { action: "list", panes },
+					};
+				}
+
+				default:
+					throw new Error(`Unknown action: ${action}`);
+			}
+		},
+
+		// --- rendering ---
+
+		renderCall(args, theme) {
+			const action = args.action || "?";
+			let text = theme.fg("toolTitle", theme.bold("tmux "));
+			text += theme.fg("accent", action);
+
+			if (args.pane) text += theme.fg("muted", ` ${args.pane}`);
+			if (args.command) text += theme.fg("dim", ` › ${args.command}`);
+			if (args.text) text += theme.fg("dim", ` › "${args.text}"`);
+			if (args.keys) text += theme.fg("dim", ` › ${args.keys}`);
+
+			return new Text(text, 0, 0);
+		},
+
+		renderResult(result, { expanded }, theme) {
+			const details = result.details as Record<string, any> | undefined;
+			if (!details) {
+				const c = result.content?.[0];
+				return new Text(c?.type === "text" ? c.text : "", 0, 0);
+			}
+
+			switch (details.action) {
+				case "run": {
+					let t = theme.fg("success", `▶ ${details.pane}`);
+					t += theme.fg("dim", ` › ${details.command}`);
+					return new Text(t, 0, 0);
+				}
+
+				case "read": {
+					const dot = details.alive ? theme.fg("success", "●") : theme.fg("error", "●");
+					let t = `${dot} ${theme.fg("accent", details.pane)}`;
+
+					if (expanded) {
+						const c = result.content?.[0];
+						if (c?.type === "text") {
+							const outputLines = c.text.split("\n").slice(0, 40);
+							t += "\n" + outputLines.map((l: string) => theme.fg("dim", l)).join("\n");
+							const total = c.text.split("\n").length;
+							if (total > 40) {
+								t += `\n${theme.fg("muted", `... (${total} total lines)`)}`;
+							}
+						}
+					}
+					return new Text(t, 0, 0);
+				}
+
+				case "send": {
+					const desc = [details.text && `"${details.text}"`, details.keys].filter(Boolean).join(" + ");
+					return new Text(theme.fg("accent", `⏎ ${details.pane} › ${desc}`), 0, 0);
+				}
+
+				case "stop": {
+					return new Text(theme.fg("warning", `■ ${details.pane}`), 0, 0);
+				}
+
+				case "list": {
+					const panes = details.panes as PaneInfo[];
+					if (!panes?.length) return new Text(theme.fg("dim", "no panes"), 0, 0);
+
+					const lines = panes.map((p) => {
+						const dot = p.alive ? theme.fg("success", "●") : theme.fg("error", "●");
+						const label = p.name
+							? theme.fg("accent", p.name)
+							: theme.fg("muted", `[${p.command}]`);
+						const extra = p.name ? "" : theme.fg("dim", " (unmanaged)");
+						return `${dot} ${label} ${theme.fg("dim", p.command)}${extra}`;
+					});
+					return new Text(lines.join("\n"), 0, 0);
+				}
+
+				default: {
+					const c = result.content?.[0];
+					return new Text(c?.type === "text" ? c.text : "", 0, 0);
+				}
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@ogulcancelik/pi-tmux",
+  "version": "0.1.0",
+  "description": "Tmux pane management for pi. Run dev servers, watchers, and long-running processes in named panes without blocking the agent.",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "tmux",
+    "terminal",
+    "pane-management",
+    "dev-server",
+    "long-running",
+    "coding-agent"
+  ],
+  "author": "Can Celik",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ogulcancelik/pi-extensions.git",
+    "directory": "packages/pi-tmux"
+  },
+  "bugs": {
+    "url": "https://github.com/ogulcancelik/pi-extensions/issues"
+  },
+  "homepage": "https://github.com/ogulcancelik/pi-extensions/tree/main/packages/pi-tmux#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "README.md",
+    "LICENSE"
+  ]
+}