Skip to content

espennilsen/pi / extensions/pi-cmux

Orchestrate cmux terminal panes — split terminals, run parallel processes, read output from other panes, and use the built-in browser. Use when working inside cmux and you need to run a dev server, watch tests, spawn sub-agents, or preview web pages.

FileKindSize
AGENTS.mdmarkdown2.2 KB
CHANGELOG.mdmarkdown520 B
README.mdmarkdown1.5 KB
SKILL.mdskill md2.8 KB
client.tsscript24.3 KB
index.tsscript10.0 KB
logger.tsscript582 B
package-lock.jsonmanifest135.9 KB
package.jsonmanifest876 B
tools.tsscript32.7 KB
tsconfig.jsonconfig274 B
/**
 * pi-cmux — cmux terminal app integration for pi.
 *
 * Provides three layers of integration:
 *
 *   Layer 1 — Passive: Auto-detects cmux and pushes status/notifications
 *             via Pi lifecycle hooks (agent_start, agent_end, tool events).
 *
 *   Layer 2 — Tools: Registers cmux_list, cmux_split, cmux_read, cmux_send,
 *             cmux_close, cmux_notify, cmux_browser so the LLM can drive cmux.
 *
 *   Layer 3 — Skill: A SKILL.md teaches the agent orchestration patterns.
 *
 * Detection: Checks for CMUX_WORKSPACE_ID / CMUX_SURFACE_ID env vars and
 * the cmux socket at /tmp/cmux.sock. No-ops gracefully outside cmux.
 */

import { basename } from "node:path";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
import { createLogger } from "./logger.ts";
import { CmuxClient } from "./client.ts";
import { registerTools } from "./tools.ts";

export default function (pi: ExtensionAPI) {
	const log = createLogger(pi);

	// ── Detection ─────────────────────────────────────────────
	//
	// cmux injects CMUX_WORKSPACE_ID and CMUX_SURFACE_ID into every
	// terminal it spawns. We also check the socket exists.

	const workspaceId = process.env.CMUX_WORKSPACE_ID;
	const surfaceId = process.env.CMUX_SURFACE_ID;
	const client = new CmuxClient({ log });

	if (!workspaceId || !surfaceId || !client.isAvailable()) {
		log("not_in_cmux", {
			hasWorkspaceId: !!workspaceId,
			hasSurfaceId: !!surfaceId,
			socketAvailable: client.isAvailable(),
			socketPath: client.socketPath,
		}, "DEBUG");
		// Not running inside cmux — skip all setup
		return;
	}

	log("detected", { workspaceId, surfaceId, socketPath: client.socketPath });

	// ── Layer 2: Agent tools ──────────────────────────────────

	const { resetBrowserState } = registerTools(pi, client, log);

	// ── Layer 1: Passive lifecycle hooks ──────────────────────

	/** Safely call cmux — never throw from lifecycle hooks. */
	function safe(fn: () => Promise<void>): void {
		fn().catch((err) => {
			const msg = err instanceof Error ? err.message : String(err);
			log("hook_error", { error: msg }, "WARN");
		});
	}

	// Track turn progress for multi-turn agents
	let turnCount = 0;

	/** Status pill key used for all Pi status updates. */
	const STATUS_KEY = "pi";

	/**
	 * Debounce timer for "Ready for input" notification.
	 * Prevents spurious notifications when agent loops restart quickly
	 * (back-to-back prompts, A2A injections, rapid loop splits).
	 */
	let notifyTimer: ReturnType<typeof setTimeout> | null = null;
	const NOTIFY_DEBOUNCE_MS = 2000;

	function cancelPendingNotify(): void {
		if (notifyTimer) {
			clearTimeout(notifyTimer);
			notifyTimer = null;
		}
	}

	/**
	 * Update the cmux workspace title.
	 *
	 * Priority: session name > workon project name > cwd basename.
	 * Called from the session_start handler and workon:switch events.
	 *
	 * Note: `workonProjectName` is module-level but safe — Pi runs one
	 * session at a time per process (session_start is sequential, not concurrent).
	 */
	let workonProjectName: string | undefined;

	function updateWorkspaceName(): void {
		const name = pi.getSessionName() ?? workonProjectName ?? basename(process.cwd());
		const source = pi.getSessionName() ? "session"
			: workonProjectName ? "workon"
			: "cwd";
		// Use the same "π - " prefix that Pi core's updateTerminalTitle() uses,
		// so the cmux workspace name stays consistent with the terminal title.
		safe(() => client.renameWorkspace(`π - ${name}`));
		log("workspace_renamed", { name, source }, "DEBUG");
	}

	pi.on("session_start", async (event, _ctx) => {
		// Clear stale browser surface tracking from previous sessions
		resetBrowserState();
		cancelPendingNotify();

		// Reset workon state on startup, reload, switch (new/resume).
		// On fork, preserve the inherited project context.
		if (event.reason !== "fork") {
			workonProjectName = undefined;
		}

		// Set workspace name from session
		updateWorkspaceName();

		// Show initial idle status
		safe(() => client.setStatus(STATUS_KEY, "idle"));

		// NOTE: We do NOT call ctx.ui.setTitle() here. Pi core's
		// updateTerminalTitle() sets the terminal title after extensions
		// init. We only use renameWorkspace() (with the π prefix) to keep
		// the cmux workspace name in sync across lifecycle events that
		// Pi core doesn't know about (session_start with reason: "fork", workon:switch).

		log("session_started", { workspaceId, surfaceId, reason: event.reason });
	});

	// Listen for workon:switch events from pi-workon extension.
	// Event shape: { name: string, path: string }
	pi.events.on("workon:switch", (data: unknown) => {
		const event = data as Record<string, unknown> | null | undefined;
		const name = typeof event?.name === "string" ? event.name : undefined;
		if (name) {
			workonProjectName = name;
			updateWorkspaceName();
		} else {
			log("workon_event_missing_name", { data }, "WARN");
		}
	});

	pi.on("agent_start", () => {
		// Cancel any pending "Ready for input" notification — agent is working again
		cancelPendingNotify();
		turnCount = 0;
		safe(() => client.setStatus(STATUS_KEY, "thinking..."));
	});

	pi.on("agent_end", () => {
		safe(() => client.clearProgress());
		safe(() => client.setStatus(STATUS_KEY, "idle"));

		// Debounce notification — only notify if agent stays idle.
		// If agent_start fires again within the window (e.g. back-to-back
		// prompts, A2A messages, sendMessage injections), the notification
		// is cancelled and the user isn't interrupted.
		cancelPendingNotify();
		notifyTimer = setTimeout(() => {
			notifyTimer = null;
			safe(() => client.notify("Pi", "Ready for input"));
		}, NOTIFY_DEBOUNCE_MS);
	});

	pi.on("tool_execution_start", (event) => {
		safe(() => client.setStatus(STATUS_KEY, `running ${event.toolName}...`));
	});

	pi.on("tool_execution_end", () => {
		safe(() => client.setStatus(STATUS_KEY, "thinking..."));
	});

	pi.on("turn_start", () => {
		turnCount++;
		if (turnCount > 1) {
			safe(() => client.setStatus(STATUS_KEY, `turn ${turnCount}...`));
		}
	});

	pi.on("turn_end", () => {
		// Reset at end — agent_end will set final status
	});

	pi.on("session_shutdown", async () => {
		cancelPendingNotify();
		await Promise.allSettled([
			client.clearStatus(STATUS_KEY),
			client.clearProgress(),
		]);
		log("session_shutdown");
	});

	// ── Commands ──────────────────────────────────────────────

	pi.registerCommand("cmux-status", {
		description: "Show cmux connection status and environment info",
		handler: async (_args: string | undefined, ctx: any) => {
			const lines: string[] = [
				"## cmux Integration Status",
				"",
				`- **Socket**: ${client.socketPath} (${client.isAvailable() ? "✅ connected" : "❌ unavailable"})`,
				`- **Workspace ID**: ${workspaceId}`,
				`- **Surface ID**: ${surfaceId}`,
			];

			try {
				const surfaces = await client.listSurfaces();
				const workspaces = await client.listWorkspaces();
				lines.push(`- **Surfaces**: ${Array.isArray(surfaces) ? surfaces.length : "?"}`);
				lines.push(`- **Workspaces**: ${Array.isArray(workspaces) ? workspaces.length : "?"}`);
			} catch {
				lines.push("- **API**: ⚠️ Could not query cmux");
			}

			lines.push("", "### Registered Tools");
			lines.push("cmux_list, cmux_split, cmux_read, cmux_send, cmux_close, cmux_notify, cmux_browser");

			ctx.ui.notify(lines.join("\n"), "info");
		},
	});

	// ── Keyboard shortcuts ────────────────────────────────────

	pi.registerShortcut("ctrl+shift+w", {
		description: "List cmux panes",
		handler: async (ctx: any) => {
			try {
				const surfaces = await client.listSurfaces();
				if (!Array.isArray(surfaces) || surfaces.length === 0) {
					ctx.ui.notify("No cmux surfaces found", "info");
					return;
				}

				const surfaceMap = new Map<string, string>();
				const options = surfaces.map((s) => {
					const sf = s as Record<string, unknown>;
					const id = String(sf.id ?? "?");
					const label = `${id}: ${String(sf.title ?? sf.cwd ?? "untitled")}`;
					surfaceMap.set(label, id);
					return label;
				});

				const choice = await ctx.ui.select("cmux Panes", options);
				if (choice) {
					const selectedId = surfaceMap.get(choice) ?? choice;
					await client.focusSurface(selectedId);
				}
			} catch (err) {
				const msg = err instanceof Error ? err.message : String(err);
				ctx.ui.notify(`cmux error: ${msg}`, "error");
			}
		},
	});

	log("initialized", {
		workspaceId,
		surfaceId,
		socketPath: client.socketPath,
		tools: ["cmux_list", "cmux_split", "cmux_read", "cmux_send", "cmux_close", "cmux_notify", "cmux_browser"],
	});

	// Event bus listener for web/mobile slash command support
	pi.events.on("command:cmux-status", async (data: unknown) => {
		const { source } = data as { args: string; source?: string };
		const notify = (msg: string, type: "info" | "warning" | "error" = "info") => {
			pi.sendMessage({ customType: "command_result", content: msg, display: true, details: { type } });
			pi.events.emit("command_result", { command: "cmux-status", message: msg, type, source: source ?? "" });
		};
		const lines: string[] = [
			"## cmux Integration Status", "",
			`- **Socket**: ${client.socketPath} (${client.isAvailable() ? "✅ connected" : "❌ unavailable"})`,
			`- **Workspace ID**: ${workspaceId}`,
			`- **Surface ID**: ${surfaceId}`,
		];
		try {
			const surfaces = await client.listSurfaces();
			const workspaces = await client.listWorkspaces();
			lines.push(`- **Surfaces**: ${Array.isArray(surfaces) ? surfaces.length : "?"}`);
			lines.push(`- **Workspaces**: ${Array.isArray(workspaces) ? workspaces.length : "?"}`);
		} catch {
			lines.push("- **API**: ⚠️ Could not query cmux");
		}
		lines.push("", "### Registered Tools");
		lines.push("cmux_list, cmux_split, cmux_read, cmux_send, cmux_close, cmux_notify, cmux_browser");
		notify(lines.join("\n"));
	});
}
finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the workStars: 322kUpdated Claude CodeCodexVerifiedInstall
systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesStars: 322kUpdated Claude CodeCodexVerifiedInstall
test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation codeStars: 322kUpdated Claude CodeCodexVerifiedInstall
skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.Stars: 198kUpdated Claude CodeCodexVerifiedInstall