pi-tmux-thread 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aaron Weisberg
+
+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,60 @@
+# pi-tmux-thread
+
+A small pi package that forks the current conversation into a separate pi process managed by tmux.
+
+The new conversation starts from `pi --fork <current-session>` so it can continue with the same context, but anything you do there stays out of the current thread.
+
+## Install
+
+```bash
+pi install git:github.com/aaronweisberg/pi-tmux-thread
+```
+
+For local development:
+
+```bash
+pi install /path/to/pi-tmux-thread
+```
+
+Then reload pi:
+
+```text
+/reload
+```
+
+## Commands
+
+```text
+/tmux [--select|-s] [split|window] [initial prompt]
+/tmux:split [--select|-s] [initial prompt]
+/tmux:window [--select|-s] [initial prompt]
+/tmux:fork [--select|-s] [split|window] [initial prompt]
+/tmux:select [split|window] [initial prompt]
+```
+
+- `/tmux --select` or `/tmux -s` starts the selectable fork workflow.
+- `split` opens a side-by-side tmux pane in the current tmux window. It requires pi itself to be running inside tmux.
+- `window` opens a new tmux window. If pi is not already inside tmux, it creates/reuses a detached per-project tmux session and tells you how to attach.
+- The optional prompt is passed to the forked pi process as its first message.
+- `--select`, `-s`, or `/tmux:select` opens a message picker showing only user messages and assistant text responses. The new tmux thread includes the selected message and excludes every later message from the current thread.
+
+Examples:
+
+```text
+/tmux:split investigate the failing test without changing this thread
+/tmux:window brainstorm an alternate migration plan
+/tmux:fork window review the current diff independently
+/tmux:select window continue from the message I pick
+/tmux:split --select try the other approach from this point
+/tmux -s window continue from the message I pick
+```
+
+## Agent tool
+
+The package also exposes a `tmux_thread` tool. The agent should only use it when you explicitly ask for a separate tmux-managed pi thread. Set `forkFrom` to `select` to ask you which message should be the last included message.
+
+## Notes
+
+- Requires `tmux` on `PATH`.
+- Requires a persisted pi session; it cannot fork an ephemeral `--no-session` run.
+- Inspired by the tmux management approach in `@romansix/pi-tmux` and the hidden side-thread workflow in `pi-btw`.

package/extensions/tmux-thread.ts

@@ -0,0 +1,339 @@
+import { DynamicBorder, SessionManager, type ExtensionAPI, type ExtensionCommandContext, type ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { StringEnum } from "@earendil-works/pi-ai";
+import { Type, type Static } from "typebox";
+import { Container, SelectList, Text, type SelectItem } from "@earendil-works/pi-tui";
+import { execFileSync, execSync, spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+
+const TOOL_NAME = "tmux_thread";
+const DEFAULT_TITLE = "pi-fork";
+
+type Target = "split" | "window";
+
+const TmuxThreadParams = Type.Object({
+  target: StringEnum(["split", "window"] as const, {
+    description: "Where to open the forked pi conversation. Use split for a tmux pane in the current window, or window for a new tmux window.",
+  }),
+  prompt: Type.Optional(Type.String({ description: "Optional initial prompt to send to the forked conversation." })),
+  title: Type.Optional(Type.String({ description: "Optional tmux pane/window title. Defaults to pi-fork." })),
+  forkFrom: Type.Optional(StringEnum(["current", "select"] as const, {
+    description: "Fork from the current leaf, or interactively select a message to include as the last message in the new thread.",
+    default: "current",
+  })),
+});
+
+type TmuxThreadInput = Static<typeof TmuxThreadParams>;
+
+function hasCommand(name: string): boolean {
+  const result = spawnSync("command", ["-v", name], { shell: true, stdio: "ignore" });
+  return result.status === 0;
+}
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function tmuxArg(value: string): string {
+  // tmux command arguments are shell parsed before tmux sees them, then passed as a single tmux argv.
+  return shellQuote(value);
+}
+
+function safeTitle(value: string | undefined): string {
+  return (value?.trim() || DEFAULT_TITLE).replace(/[\n\r]/g, " ").slice(0, 40);
+}
+
+function execText(command: string, cwd?: string): string {
+  return execSync(command, { cwd, encoding: "utf8", timeout: 10_000 }).trim();
+}
+
+function tmux(args: string[]): string {
+  return execFileSync("tmux", args, { encoding: "utf8", timeout: 10_000 }).trim();
+}
+
+function getGitRoot(cwd: string): string | null {
+  try {
+    return execText("git rev-parse --show-toplevel", cwd);
+  } catch {
+    return null;
+  }
+}
+
+function projectSessionName(cwd: string): string {
+  const root = getGitRoot(cwd) ?? cwd;
+  const base = root.split("/").filter(Boolean).pop() ?? "project";
+  const slug = base.toLowerCase().replace(/[^a-z0-9_-]/g, "-").slice(0, 18) || "project";
+  const hash = createHash("md5").update(root).digest("hex").slice(0, 8);
+  return `${slug}-${hash}`;
+}
+
+function tmuxSessionExists(name: string): boolean {
+  try {
+    execSync(`tmux has-session -t ${tmuxArg(name)}`, { stdio: "ignore", timeout: 5_000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function createSessionAtEntry(ctx: ExtensionCommandContext | ExtensionContext, entryId: string): string {
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  if (!sessionFile) {
+    throw new Error("Current pi session is ephemeral; start pi with session persistence before forking into tmux.");
+  }
+
+  const manager = SessionManager.open(sessionFile);
+  const forkedFile = manager.createBranchedSession(entryId);
+  if (!forkedFile) {
+    throw new Error("Could not create a persisted branched session for the selected message.");
+  }
+  return forkedFile;
+}
+
+function buildPiCommand(ctx: ExtensionCommandContext | ExtensionContext, prompt: string | undefined, thinkingLevel: string | undefined, entryId?: string): string {
+  const sessionFile = ctx.sessionManager.getSessionFile();
+  if (!sessionFile) {
+    throw new Error("Current pi session is ephemeral; start pi with session persistence before forking into tmux.");
+  }
+
+  const args = entryId ? ["pi", "--session", createSessionAtEntry(ctx, entryId)] : ["pi", "--fork", sessionFile];
+
+  if (ctx.model) {
+    args.push("--model", `${ctx.model.provider}/${ctx.model.id}`);
+  }
+
+  if (thinkingLevel) {
+    args.push("--thinking", thinkingLevel);
+  }
+
+  const trimmedPrompt = prompt?.trim();
+  if (trimmedPrompt) {
+    args.push(trimmedPrompt);
+  }
+
+  return args.map(shellQuote).join(" ");
+}
+
+function launchInTmux(ctx: ExtensionCommandContext | ExtensionContext, params: TmuxThreadInput, thinkingLevel?: string, entryId?: string): string {
+  if (!hasCommand("tmux")) {
+    throw new Error("tmux is not installed or not on PATH.");
+  }
+
+  const title = safeTitle(params.title);
+  const piCommand = buildPiCommand(ctx, params.prompt, thinkingLevel, entryId);
+  const command = `exec ${piCommand}`;
+  const cwdArg = tmuxArg(ctx.cwd);
+  const titleArg = tmuxArg(title);
+
+  if (params.target === "split") {
+    if (!process.env.TMUX) {
+      throw new Error("/tmux:split requires the current pi process to be running inside tmux. Use /tmux:window outside tmux.");
+    }
+
+    const paneId = tmux(["split-window", "-h", "-c", ctx.cwd, "-P", "-F", "#{pane_id}", command]);
+    if (paneId) {
+      try {
+        tmux(["select-pane", "-t", paneId, "-T", title]);
+      } catch {
+        // Pane titles are cosmetic; ignore failures.
+      }
+    }
+    return `Opened forked pi conversation in a tmux split: ${title}`;
+  }
+
+  if (process.env.TMUX) {
+    tmux(["new-window", "-c", ctx.cwd, "-n", title, command]);
+    return `Opened forked pi conversation in a new tmux window: ${title}`;
+  }
+
+  // Outside tmux, create/reuse a per-project detached tmux session so the window has somewhere to live.
+  const session = projectSessionName(ctx.cwd);
+  if (!tmuxSessionExists(session)) {
+    tmux(["new-session", "-d", "-s", session, "-c", ctx.cwd, "-n", "shell"]);
+  }
+  tmux(["new-window", "-t", session, "-c", ctx.cwd, "-n", title, command]);
+  return `Opened forked pi conversation in detached tmux session ${session}. Attach with: tmux attach -t ${session}`;
+}
+
+function parseTargetAndPrompt(args: string, fallback: Target): { target: Target; prompt: string; select: boolean } {
+  let trimmed = args.trim();
+  const select = /(?:^|\s)(?:--select|-s)(?=\s|$)/.test(trimmed);
+  trimmed = trimmed.replace(/(?:^|\s)(?:--select|-s)(?=\s|$)/g, " ").trim();
+  if (!trimmed) return { target: fallback, prompt: "", select };
+
+  const match = trimmed.match(/^(split|window)\b\s*/i);
+  if (!match) return { target: fallback, prompt: trimmed, select };
+
+  return {
+    target: match[1].toLowerCase() as Target,
+    prompt: trimmed.slice(match[0].length).trim(),
+    select,
+  };
+}
+
+function messageText(message: any): string {
+  const content = message?.content;
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((part) => (part?.type === "text" ? part.text : ""))
+    .filter(Boolean)
+    .join(" ");
+}
+
+function isSelectableConversationMessage(entry: any): boolean {
+  if (entry?.type !== "message") return false;
+  const role = entry.message?.role;
+  if (role !== "user" && role !== "assistant") return false;
+  return compactLine(messageText(entry.message) || "").length > 0;
+}
+
+function compactLine(value: string, max = 120): string {
+  const line = value.replace(/\s+/g, " ").trim();
+  return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+}
+
+async function selectOptionWithVisibleCursor(ctx: ExtensionCommandContext | ExtensionContext, options: string[]): Promise<number | undefined> {
+  if (!ctx.hasUI) {
+    throw new Error("Selecting a fork point requires interactive pi UI.");
+  }
+
+  const items: SelectItem[] = options.map((label, index) => ({ value: String(index), label }));
+  const selected = await ctx.ui.custom<string | null>((tui, theme, _keybindings, done) => {
+    const container = new Container();
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+    container.addChild(new Text(theme.fg("accent", theme.bold("Fork tmux thread from message")), 1, 0));
+    container.addChild(new Text(theme.fg("dim", "Selected message is included; later messages are excluded."), 1, 0));
+
+    const selectList = new SelectList(items, Math.min(items.length, 18), {
+      selectedPrefix: (t) => theme.bg("selectedBg", theme.fg("text", t)),
+      selectedText: (t) => theme.bg("selectedBg", theme.fg("text", theme.bold(t))),
+      description: (t) => theme.fg("muted", t),
+      scrollInfo: (t) => theme.fg("dim", t),
+      noMatch: (t) => theme.fg("warning", t),
+    });
+    selectList.onSelect = (item) => done(item.value);
+    selectList.onCancel = () => done(null);
+    container.addChild(selectList);
+
+    container.addChild(new Text(theme.fg("dim", "↑↓ navigate • type to filter • enter select • esc cancel"), 1, 0));
+    container.addChild(new DynamicBorder((s: string) => theme.fg("accent", s)));
+
+    return {
+      render: (width: number) => container.render(width),
+      invalidate: () => container.invalidate(),
+      handleInput: (data: string) => {
+        selectList.handleInput(data);
+        tui.requestRender();
+      },
+    };
+  });
+
+  if (selected === null || selected === undefined) return undefined;
+  const index = Number(selected);
+  return Number.isInteger(index) ? index : undefined;
+}
+
+async function selectForkEntry(ctx: ExtensionCommandContext | ExtensionContext): Promise<string | undefined> {
+  const branch = ctx.sessionManager
+    .getBranch()
+    .filter(isSelectableConversationMessage);
+
+  if (branch.length === 0) {
+    throw new Error("No user or assistant response messages are available to select as a fork point.");
+  }
+
+  const options = branch.map((entry: any, index: number) => {
+    const role = entry.message?.role === "assistant" ? "response" : "user";
+    return `${index + 1}. ${role} · ${compactLine(messageText(entry.message))}`;
+  });
+
+  const index = await selectOptionWithVisibleCursor(ctx, options);
+  if (index === undefined) return undefined;
+
+  const entry = branch[index];
+  if (!entry) {
+    throw new Error("Invalid message selection.");
+  }
+  return entry.id;
+}
+
+function notify(ctx: ExtensionCommandContext | ExtensionContext, message: string, level: "info" | "error" = "info"): void {
+  if (ctx.hasUI) {
+    ctx.ui.notify(message, level);
+  }
+}
+
+async function runLaunchCommand(args: string, ctx: ExtensionCommandContext, fallback: Target, thinkingLevel?: string, alwaysSelect = false): Promise<void> {
+  await ctx.waitForIdle();
+  const parsed = parseTargetAndPrompt(args, fallback);
+  try {
+    const entryId = parsed.select || alwaysSelect ? await selectForkEntry(ctx) : undefined;
+    if ((parsed.select || alwaysSelect) && !entryId) return;
+    const message = launchInTmux(ctx, {
+      target: parsed.target,
+      prompt: parsed.prompt || undefined,
+      title: parsed.prompt ? `pi: ${parsed.prompt}` : DEFAULT_TITLE,
+    }, thinkingLevel, entryId);
+    notify(ctx, message, "info");
+  } catch (error) {
+    notify(ctx, error instanceof Error ? error.message : String(error), "error");
+  }
+}
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("tmux", {
+    description: "Fork the current pi conversation into a tmux split/window. Usage: /tmux [--select|-s] [split|window] [initial prompt]",
+    handler: async (args, ctx) => runLaunchCommand(args, ctx, "split", pi.getThinkingLevel()),
+  });
+
+  pi.registerCommand("tmux:fork", {
+    description: "Fork the current pi conversation into a tmux split/window without adding messages to this thread. Usage: /tmux:fork [--select|-s] [split|window] [initial prompt]",
+    handler: async (args, ctx) => runLaunchCommand(args, ctx, "split", pi.getThinkingLevel()),
+  });
+
+  pi.registerCommand("tmux:split", {
+    description: "Fork the current pi conversation into a new tmux split. Usage: /tmux:split [--select|-s] [initial prompt]",
+    handler: async (args, ctx) => runLaunchCommand(args, ctx, "split", pi.getThinkingLevel()),
+  });
+
+  pi.registerCommand("tmux:window", {
+    description: "Fork the current pi conversation into a new tmux window. Usage: /tmux:window [--select|-s] [initial prompt]",
+    handler: async (args, ctx) => runLaunchCommand(args, ctx, "window", pi.getThinkingLevel()),
+  });
+
+  pi.registerCommand("tmux:select", {
+    description: "Pick a message, then fork the current pi conversation into tmux from that point inclusive. Usage: /tmux:select [split|window] [initial prompt]",
+    handler: async (args, ctx) => runLaunchCommand(args, ctx, "split", pi.getThinkingLevel(), true),
+  });
+
+  pi.registerTool({
+
+    name: TOOL_NAME,
+    label: "tmux thread",
+    description: "Fork the current pi conversation into a separate pi process in tmux. The fork continues from the current session file but does not add the side conversation to the current thread.",
+    promptSnippet: "Fork the current pi conversation into a separate tmux split/window when the user wants a clean parallel thread.",
+    promptGuidelines: [
+      "Use tmux_thread only when the user explicitly wants to continue in a separate tmux-managed pi conversation without polluting the current thread.",
+      "Use target=split for a side-by-side pane when pi is already running inside tmux; use target=window for a separate tmux window.",
+    ],
+    parameters: TmuxThreadParams,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      try {
+        const entryId = params.forkFrom === "select" ? await selectForkEntry(ctx) : undefined;
+        if (params.forkFrom === "select" && !entryId) {
+          return { content: [{ type: "text", text: "No message selected; tmux thread was not opened." }] };
+        }
+        const message = launchInTmux(ctx, params, pi.getThinkingLevel(), entryId);
+        return {
+          content: [{ type: "text", text: message }],
+          details: { target: params.target, title: safeTitle(params.title) },
+        };
+      } catch (error) {
+        return {
+          content: [{ type: "text", text: error instanceof Error ? error.message : String(error) }],
+          isError: true,
+        };
+      }
+    },
+  });
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "pi-tmux-thread",
+  "version": "0.1.0",
+  "description": "Pi extension for forking conversations into tmux splits or windows",
+  "type": "module",
+  "license": "MIT",
+  "author": "Aaron Weisberg",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aaronweisberg/pi-tmux-thread.git"
+  },
+  "homepage": "https://github.com/aaronweisberg/pi-tmux-thread#readme",
+  "bugs": {
+    "url": "https://github.com/aaronweisberg/pi-tmux-thread/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "tmux"
+  ],
+  "files": [
+    "extensions",
+    "skills",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/tmux-thread.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "typebox": "*"
+  }
+}