pi-teams 0.7.2 → 0.7.3

package/README.md

@@ -1,6 +1,6 @@
 # pi-teams 🚀
 
-**pi-teams** turns your single Pi agent into a coordinated software engineering team. It allows you to spawn multiple "Teammate" agents in separate terminal panes that work autonomously, communicate with each other, and manage a shared task board—all mediated through **tmux**.
+**pi-teams** turns your single Pi agent into a coordinated software engineering team. It allows you to spawn multiple "Teammate" agents in separate terminal panes that work autonomously, communicate with each other, and manage a shared task board—all mediated through tmux, iTerm2, or Zellij.
 
 ### 🖥️ pi-teams in Action
 
@@ -16,137 +16,76 @@ Open your Pi terminal and type:
 pi install npm:pi-teams
 ```
 
----
+## 🚀 Quick Start
+
+```bash
+# 1. Start a team (inside tmux, Zellij, or iTerm2)
+"Create a team named 'my-team' using 'gpt-4o'"
+
+# 2. Spawn teammates
+"Spawn 'security-bot' to scan for vulnerabilities"
+"Spawn 'frontend-dev' using 'haiku' for quick iterations"
+
+# 3. Create and assign tasks
+"Create a task for security-bot: 'Audit auth endpoints'"
+
+# 4. Review and approve work
+"List all tasks and approve any pending plans"
+```
 
 ## 🌟 What can it do?
 
+### Core Features
 - **Spawn Specialists**: Create agents like "Security Expert" or "Frontend Pro" to handle sub-tasks in parallel.
 - **Shared Task Board**: Keep everyone on the same page with a persistent list of tasks and their status.
 - **Agent Messaging**: Agents can send direct messages to each other and to you (the Team Lead) to report progress.
-- **Broadcast Messaging**: Send a message to the entire team at once for global coordination.
-- **Plan Approval Mode**: Require teammates to submit their implementation plans for lead approval before they touch any code.
-- **Quality Gate Hooks**: Automated shell scripts can run when tasks are completed (e.g., to run tests or linting).
 - **Autonomous Work**: Teammates automatically "wake up," read their instructions, and poll their inboxes for new work while idle.
 - **Beautiful UI**: Optimized vertical splits in `tmux` with clear labels so you always know who is doing what.
 
----
-
-## 💬 How to use it (Examples)
+### Advanced Features
+- **Plan Approval Mode**: Require teammates to submit their implementation plans for your approval before they touch any code.
+- **Broadcast Messaging**: Send a message to the entire team at once for global coordination and announcements.
+- **Quality Gate Hooks**: Automated shell scripts run when tasks are completed (e.g., to run tests or linting).
+- **Thinking Level Control**: Set per-teammate thinking levels (`off`, `minimal`, `low`, `medium`, `high`) to balance speed vs. reasoning depth.
 
-You don't need to learn complex code commands. Just talk to Pi in plain English!
+## 💬 Key Examples
 
 ### 1. Start a Team
 > **You:** "Create a team named 'my-app-audit' for reviewing the codebase."
 
-**Pro Tip:** You can also set a default model for the whole team!
+**Set a default model for the whole team:**
 > **You:** "Create a team named 'Research' and use 'gpt-4o' for everyone."
 
-### 2. Spawn a Teammate
+### 2. Spawn Teammate with Custom Settings
 > **You:** "Spawn a teammate named 'security-bot' in the current folder. Tell them to scan for hardcoded API keys."
 
-**Pro Tip:** You can specify a different model for a specific teammate!
+**Use a different model:**
 > **You:** "Spawn a teammate named 'speed-bot' using 'haiku' to quickly run some benchmarks."
 
-**New: Plan Approval Mode**
+**Require plan approval:**
 > **You:** "Spawn a teammate named 'refactor-bot' and require plan approval before they make any changes."
 
-**Customize Teammate Model & Thinking**
+**Customize model and thinking level:**
 > **You:** "Spawn a teammate named 'architect-bot' using 'gpt-4o' with 'high' thinking level for deep reasoning."
-> **You:** "Spawn a teammate named 'frontend-dev' using 'haiku' with 'low' thinking level for quick iterations."
-> **You:** "Spawn a teammate named 'code-reviewer' using 'gpt-4o' with 'medium' thinking level."
 
-You can customize **both** the model and thinking level for each teammate independently:
-- **Model**: Override team's default model for a specific teammate (e.g., `gpt-4o`, `haiku`, `glm-4.7`)
-- **Thinking Level**: Balance speed vs. depth per teammate:
-  - `off`: No thinking blocks (fastest)
-  - `minimal`: Minimal reasoning overhead
-  - `low`: Light reasoning for quick decisions
-  - `medium`: Balanced reasoning (default for most work)
-  - `high`: Extended reasoning for complex problems
-
-This lets you build teams with varied capabilities—fast, lightweight teammates for simple tasks, and powerful, thoughtful teammates for complex work.
-
-### 3. Assign a Task
+### 3. Assign Task & Get Approval
 > **You:** "Create a task for security-bot: 'Check the .env.example file for sensitive defaults' and set it to in_progress."
 
-### 4. Submit and Evaluate a Plan
-Teammates in `planning` mode will use `task_submit_plan`. As the lead, you can then:
+Teammates in `planning` mode will use `task_submit_plan`. As the lead, review their work:
 > **You:** "Review refactor-bot's plan for task 5. If it looks good, approve it. If not, reject it with feedback on the test coverage."
 
-### 5. Broadcast a Message
+### 4. Broadcast to Team
 > **You:** "Broadcast to the entire team: 'The API endpoint has changed to /v2. Please update your work accordingly.'"
 
-### 6. Automated Hooks
-Add a script at `.pi/team-hooks/task_completed.sh` to run automated checks when any task is finished.
-```bash
-#!/bin/bash
-# Example: Run tests when a task is completed
-npm test
-```
-
-### 7. Inter-Agent Communication
-> Teammates can also talk to each other! For example, a `frontend-bot` can message a `backend-bot` to coordinate on an API schema without your intervention.
-
-### 6. Check on Progress
-> **You:** "How is the team doing? List all tasks and check my inbox for any messages."
-
-### 7. Shut Down the Team
+### 5. Shut Down Team
 > **You:** "We're done. Shut down the team and close the panes."
 
 ---
 
-## 🛠 Available Tools
-
-Pi automatically uses these tools when you give instructions like the examples above.
-
-### Team Management
-- `team_create`: Start a new team. (Optional: `default_model`)
-- `team_delete`: Delete a team and its data.
-- `read_config`: Get details about the team and its members.
-
-### Teammates
-- `spawn_teammate`: Launch a new agent into a `tmux` pane with a role and instructions. (Optional: `model`, `thinking`, `plan_mode_required`)
-  - **`model`**: Specify which AI model this teammate should use (e.g., `gpt-4o`, `haiku`, `glm-4.7`, `glm-5`). If not specified, uses the team's default model. You can mix different models across teammates for cost/performance optimization.
-  - **`thinking`**: Set the agent's thinking level (`off`, `minimal`, `low`, `medium`, `high`). This controls how much time the agent spends reasoning before responding. If not specified, inherited from team/global settings. Different teammates can have different thinking levels.
-  - **`plan_mode_required`**: If true, teammate must submit plans for lead approval before making code changes
-- `check_teammate`: See if a teammate is still running or has unread messages.
-- `force_kill_teammate`: Stop a teammate and remove them from the team.
-- `process_shutdown_approved`: Orderly shutdown for a finished teammate.
-
-### Task Management
-- `task_create`: Create a new task.
-- `task_list`: List all tasks and their current status.
-- `task_get`: Get full details of a specific task.
-- `task_update`: Update a task's status (pending, planning, in_progress, etc.) or owner.
-
-### Messaging
-- `send_message`: Send a message to a teammate or lead.
-- `broadcast_message`: Send a message to the entire team.
-- `read_inbox`: Read incoming messages for an agent.
-
-### Task Planning & Approval
-- `task_submit_plan`: For teammates to submit their implementation plans.
-- `task_evaluate_plan`: For the lead to approve or reject a plan (with feedback).
-
----
-
-## 🤖 Automated Behavior
+## 📚 Learn More
 
-- **Initial Greeting**: When a teammate is spawned, they will automatically send a message saying they've started and are checking their inbox.
-- **Idle Polling**: Teammates check for new messages every 30 seconds if they are idle.
-- **Automated Hooks**: If `.pi/team-hooks/task_completed.sh` exists, it will automatically execute whenever a task status is changed to `completed`.
-- **Context Injection**: Each teammate is given a custom system prompt that defines their role and instructions for the team environment.
-
----
-
-## 📂 Configuration & Data
-
-All team and task data is stored in your home directory:
-`~/.pi/teams/` and `~/.pi/tasks/`
-
-You can manually inspect these JSON files if you ever need to debug your team's configuration or message history.
-
----
+- **[Full Usage Guide](docs/guide.md)** - Detailed examples, hook system, best practices, and troubleshooting
+- **[Tool Reference](docs/reference.md)** - Complete documentation of all tools and parameters
 
 ## 🪟 Terminal Requirements: tmux, Zellij, or iTerm2
 
@@ -154,32 +93,29 @@ To show multiple agents on one screen, **pi-teams** requires a way to manage ter
 
 ### Option 1: tmux (Recommended)
 
-#### 1. Install tmux
+Install tmux:
 - **macOS**: `brew install tmux`
 - **Linux**: `sudo apt install tmux`
 
-#### 2. How to run it
-Before you start a team, you **must** be inside a tmux session. Simply type:
+How to run:
 ```bash
-tmux
+tmux  # Start tmux session
+pi   # Start pi inside tmux
 ```
-Then start `pi` inside that window.
 
 ### Option 2: Zellij
 
-If you prefer **Zellij**, simply start `pi` inside a Zellij session. **pi-teams** will detect it via the `ZELLIJ` environment variable and use `zellij run` to spawn teammates in new panes.
+Simply start `pi` inside a Zellij session. **pi-teams** will detect it via the `ZELLIJ` environment variable and use `zellij run` to spawn teammates in new panes.
 
 ### Option 3: iTerm2 (macOS)
 
 If you are using **iTerm2** on macOS and are *not* inside tmux or Zellij, **pi-teams** will use AppleScript to automatically split your current window into an optimized layout (1 large Lead pane on the left, Teammates stacked on the right). It will also name the panes with the teammate's agent name for easy identification.
 
----
-
 ## 📜 Credits & Attribution
 
-This project is a port of the excellent [claude-code-teams-mcp](https://github.com/cs50victor/claude-code-teams-mcp) by [cs50victor](https://github.com/cs50victor). 
+This project is a port of the excellent [claude-code-teams-mcp](https://github.com/cs50victor/claude-code-teams-mcp) by [cs50victor](https://github.com/cs50victor).
 
-We have adapted the original MCP coordination protocol to work natively as a **Pi Package**, adding features like auto-starting teammates, balanced vertical UI layouts, and automatic inbox polling to make the experience seamless for Pi users.
+We have adapted the original MCP coordination protocol to work natively as a **Pi Package**, adding features like auto-starting teammates, balanced vertical UI layouts, automatic inbox polling, plan approval mode, broadcast messaging, and quality gate hooks.
 
 ## 📄 License
 MIT

package/extensions/index.ts

@@ -6,7 +6,8 @@ import * as teams from "../src/utils/teams";
 import * as tasks from "../src/utils/tasks";
 import * as messaging from "../src/utils/messaging";
 import { Member } from "../src/utils/models";
-import { execSync, spawnSync } from "node:child_process";
+import { getTerminalAdapter } from "../src/adapters/terminal-registry";
+import { Iterm2Adapter } from "../src/adapters/iterm2-adapter";
 import path from "node:path";
 import fs from "node:fs";
 
@@ -15,6 +16,9 @@ export default function (pi: ExtensionAPI) {
   const agentName = process.env.PI_AGENT_NAME || "team-lead";
   const teamName = process.env.PI_TEAM_NAME;
 
+  // Get the terminal adapter once at startup
+  const terminal = getTerminalAdapter();
+
   pi.on("session_start", async (_event, ctx) => {
     paths.ensureDirs();
     if (isTeammate) {
@@ -26,15 +30,9 @@ export default function (pi: ExtensionAPI) {
       // Use a shorter, more prominent status at the beginning if possible
       ctx.ui.setStatus("00-pi-teams", `[${agentName.toUpperCase()}]`); 
       
-      // Also set the tmux pane title for better visibility
-      try {
-        if (process.env.TMUX) {
-          spawnSync("tmux", ["select-pane", "-T", agentName]);
-        } else if (process.env.TERM_PROGRAM === "iTerm.app") {
-          spawnSync("osascript", ["-e", `tell application "iTerm2" to tell current session of current window to set name to "${agentName}"`]);
-        }
-      } catch (e) {
-        // ignore
+      // Set the terminal pane title for better visibility
+      if (terminal) {
+        terminal.setTitle(agentName);
       }
       
       // Auto-trigger the first turn for teammates
@@ -99,32 +97,8 @@ export default function (pi: ExtensionAPI) {
       }
     }
 
-    if (member.tmuxPaneId) {
-      try {
-        if (member.tmuxPaneId.startsWith("iterm_")) {
-          const itermId = member.tmuxPaneId.replace("iterm_", "");
-          const script = `tell application "iTerm2"
-  repeat with aWindow in windows
-    repeat with aTab in tabs of aWindow
-      repeat with aSession in sessions of aTab
-        if id of aSession is "${itermId}" then
-          close aSession
-          return "Closed"
-        end if
-      end repeat
-    end repeat
-  end repeat
-end tell`;
-          spawnSync("osascript", ["-e", script]);
-        } else if (member.tmuxPaneId.startsWith("zellij_")) {
-          // Zellij is expected to close on process exit (using --close-on-exit)
-        } else {
-          // Use -t with the pane_id
-          spawnSync("tmux", ["kill-pane", "-t", member.tmuxPaneId.trim()]);
-        }
-      } catch (e) {
-        // ignore
-      }
+    if (member.tmuxPaneId && terminal) {
+      terminal.kill(member.tmuxPaneId);
     }
   }
 
@@ -150,7 +124,7 @@ end tell`;
   pi.registerTool({
     name: "spawn_teammate",
     label: "Spawn Teammate",
-    description: "Spawn a new teammate in a tmux pane.",
+    description: "Spawn a new teammate in a terminal pane.",
     parameters: Type.Object({
       team_name: Type.String(),
       name: Type.String(),
@@ -168,8 +142,28 @@ end tell`;
         throw new Error(`Team ${params.team_name} does not exist`);
       }
 
+      if (!terminal) {
+        throw new Error("No terminal adapter detected. Ensure you're running in tmux, iTerm2, or Zellij.");
+      }
+
       const teamConfig = await teams.readConfig(safeTeamName);
-      const chosenModel = params.model || teamConfig.defaultModel;
+      let chosenModel = params.model || teamConfig.defaultModel;
+
+      // If model doesn't include provider prefix (provider/model), use the team's defaultModel or fallback
+      if (chosenModel && !chosenModel.includes('/')) {
+        // Check if team has a defaultModel with a provider prefix
+        if (teamConfig.defaultModel && teamConfig.defaultModel.includes('/')) {
+          const [provider] = teamConfig.defaultModel.split('/');
+          chosenModel = `${provider}/${chosenModel}`;
+        } else {
+          // Infer provider from model name
+          if (chosenModel.startsWith('glm-')) {
+            chosenModel = `zai/${chosenModel}`;
+          } else if (chosenModel.startsWith('claude-')) {
+            chosenModel = `anthropic/${chosenModel}`;
+          }
+        }
+      }
 
       const member: Member = {
         agentId: `${safeName}@${safeTeamName}`,
@@ -194,25 +188,13 @@ end tell`;
 
       // Build model command with thinking level if specified
       if (chosenModel) {
-        // If model doesn't include provider prefix (provider/model), use the team's defaultModel or fallback
-        let modelWithProvider = chosenModel;
-        if (!chosenModel.includes('/')) {
-          // Check if team has a defaultModel with a provider prefix
-          if (teamConfig.defaultModel && teamConfig.defaultModel.includes('/')) {
-            const [provider] = teamConfig.defaultModel.split('/');
-            modelWithProvider = `${provider}/${chosenModel}`;
-          } else {
-            // Use zai as default provider for glm models (matching user's pi settings)
-            if (chosenModel.startsWith('glm-')) {
-              modelWithProvider = `zai/${chosenModel}`;
-            }
-          }
-        }
+        const [provider, ...modelParts] = chosenModel.split('/');
+        const modelName = modelParts.join('/');
 
         if (params.thinking) {
-          piCmd = `${piBinary} --model ${modelWithProvider}:${params.thinking}`;
+          piCmd = `${piBinary} --provider ${provider} --model ${modelName}:${params.thinking}`;
         } else {
-          piCmd = `${piBinary} --model ${modelWithProvider}`;
+          piCmd = `${piBinary} --provider ${provider} --model ${modelName}`;
         }
       } else if (params.thinking) {
         piCmd = `${piBinary} --thinking ${params.thinking}`;
@@ -224,87 +206,28 @@ end tell`;
         PI_AGENT_NAME: safeName,
       };
 
-      let paneId = "";
-      try {
-        if (process.env.ZELLIJ && !process.env.TMUX) {
-          const zellijArgs = [
-            "run", 
-            "--name", safeName, 
-            "--cwd", params.cwd, 
-            "--close-on-exit",
-            "--", 
-            "env", ...Object.entries(env).filter(([k]) => k.startsWith("PI_")).map(([k, v]) => `${k}=${v}`),
-            "sh", "-c", piCmd
-          ];
-          spawnSync("zellij", zellijArgs);
-          paneId = `zellij_${safeName}`;
-        } else if (process.env.TERM_PROGRAM === "iTerm.app" && !process.env.TMUX && !process.env.ZELLIJ) {
-          const envStr = Object.entries(env)
-            .filter(([k]) => k.startsWith("PI_"))
-            .map(([k, v]) => `${k}=${v}`)
-            .join(" ");
-          const itermCmd = `cd '${params.cwd}' && ${envStr} ${piCmd}`;
-          const teammates = teamConfig.members.filter(m => m.agentType === "teammate" && m.tmuxPaneId.startsWith("iterm_"));
-          const lastTeammate = teammates.length > 0 ? teammates[teammates.length - 1] : null;
-          
-          let script = "";
-          if (!lastTeammate) {
-            // First teammate: split current session vertically (side-by-side)
-            script = `tell application "iTerm2"
-  tell current session of current window
-    set newSession to split vertically with default profile
-    tell newSession
-      write text "${itermCmd.replace(/"/g, '\\"')}"
-      return id
-    end tell
-  end tell
-end tell`;
-          } else {
-            // Subsequent teammate: split the last teammate's session horizontally (stacking them)
-            const lastSessionId = lastTeammate.tmuxPaneId.replace("iterm_", "");
-            script = `tell application "iTerm2"
-  repeat with aWindow in windows
-    repeat with aTab in tabs of aWindow
-      repeat with aSession in sessions of aTab
-        if id of aSession is "${lastSessionId}" then
-          tell aSession
-            set newSession to split horizontally with default profile
-            tell newSession
-              write text "${itermCmd.replace(/"/g, '\\"')}"
-              return id
-            end tell
-          end tell
-        end if
-      end repeat
-    end repeat
-  end repeat
-end tell`;
-          }
-          const result = spawnSync("osascript", ["-e", script]);
-          if (result.status !== 0) throw new Error(`osascript failed with status ${result.status}: ${result.stderr.toString()}`);
-          paneId = `iterm_${result.stdout.toString().trim()}`;
+      // For iTerm2, we need to handle the spawn context for proper layout
+      if (terminal instanceof Iterm2Adapter) {
+        const teammates = teamConfig.members.filter(m => m.agentType === "teammate" && m.tmuxPaneId.startsWith("iterm_"));
+        const lastTeammate = teammates.length > 0 ? teammates[teammates.length - 1] : null;
+        if (lastTeammate?.tmuxPaneId) {
+          terminal.setSpawnContext({ lastSessionId: lastTeammate.tmuxPaneId.replace("iterm_", "") });
         } else {
-          const envArgs = Object.entries(env)
-            .filter(([k]) => k.startsWith("PI_"))
-            .map(([k, v]) => `${k}=${v}`);
-          const tmuxArgs = [
-            "split-window", 
-            "-h", "-dP", 
-            "-F", "#{pane_id}", 
-            "-c", params.cwd, 
-            "env", ...envArgs,
-            "sh", "-c", piCmd
-          ];
-          const result = spawnSync("tmux", tmuxArgs);
-          if (result.status !== 0) throw new Error(`tmux failed with status ${result.status}: ${result.stderr.toString()}`);
-          paneId = result.stdout.toString().trim();
-          spawnSync("tmux", ["set-window-option", "main-pane-width", "60%"]);
-          spawnSync("tmux", ["select-layout", "main-vertical"]);
+          terminal.setSpawnContext({});
         }
-      } catch (e) {
-        throw new Error(`Failed to spawn ${process.env.ZELLIJ && !process.env.TMUX ? "zellij" : (process.env.TERM_PROGRAM === "iTerm.app" ? "iTerm2" : "tmux")} pane: ${e}`);
       }
 
+      let paneId = "";
+      try {
+        paneId = terminal.spawn({
+          name: safeName,
+          cwd: params.cwd,
+          command: piCmd,
+          env: env,
+        });
+      } catch (e) {
+        throw new Error(`Failed to spawn ${terminal.name} pane: ${e}`);
+      }
 
       // Update member with paneId
       await teams.updateMember(params.team_name, params.name, { tmuxPaneId: paneId });
@@ -533,7 +456,7 @@ end tell`;
   pi.registerTool({
     name: "force_kill_teammate",
     label: "Force Kill Teammate",
-    description: "Forcibly kill a teammate's tmux target.",
+    description: "Forcibly kill a teammate's terminal pane.",
     parameters: Type.Object({
       team_name: Type.String(),
       agent_name: Type.String(),
@@ -567,33 +490,8 @@ end tell`;
       if (!member) throw new Error(`Teammate ${params.agent_name} not found`);
 
       let alive = false;
-      if (member.tmuxPaneId) {
-        try {
-          if (member.tmuxPaneId.startsWith("zellij_")) {
-            // Assume alive if it's zellij for now
-            alive = true;
-          } else if (member.tmuxPaneId.startsWith("iterm_")) {
-            const itermId = member.tmuxPaneId.replace("iterm_", "");
-            const script = `tell application "iTerm2"
-  repeat with aWindow in windows
-    repeat with aTab in tabs of aWindow
-      repeat with aSession in sessions of aTab
-        if id of aSession is "${itermId}" then
-          return "Alive"
-        end if
-      end repeat
-    end repeat
-  end repeat
-end tell`;
-            const result = spawnSync("osascript", ["-e", script]);
-            alive = result.stdout.toString().includes("Alive");
-          } else {
-            execSync(`tmux has-session -t ${member.tmuxPaneId}`);
-            alive = true;
-          }
-        } catch (e) {
-          alive = false;
-        }
+      if (member.tmuxPaneId && terminal) {
+        alive = terminal.isAlive(member.tmuxPaneId);
       }
 
       const unreadCount = (await messaging.readInbox(params.team_name, params.agent_name, true, false)).length;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-teams",
-  "version": "0.7.2",
+  "version": "0.7.3",
   "description": "Agent teams for pi, ported from claude-code-teams-mcp",
   "repository": "github:burggraf/pi-teams",
   "author": "Mark Burggraf",

package/src/adapters/iterm2-adapter.ts

@@ -0,0 +1,158 @@
+/**
+ * iTerm2 Terminal Adapter
+ * 
+ * Implements the TerminalAdapter interface for iTerm2 terminal emulator.
+ * Uses AppleScript for all operations.
+ */
+
+import { TerminalAdapter, SpawnOptions, execCommand } from "../utils/terminal-adapter";
+
+/**
+ * Context needed for iTerm2 spawning (tracks last pane for layout)
+ */
+export interface Iterm2SpawnContext {
+  /** ID of the last spawned session, used for layout decisions */
+  lastSessionId?: string;
+}
+
+export class Iterm2Adapter implements TerminalAdapter {
+  readonly name = "iTerm2";
+  private spawnContext: Iterm2SpawnContext = {};
+
+  detect(): boolean {
+    // iTerm2 is available if TERM_PROGRAM is iTerm.app and not in tmux/zellij
+    return process.env.TERM_PROGRAM === "iTerm.app" && !process.env.TMUX && !process.env.ZELLIJ;
+  }
+
+  spawn(options: SpawnOptions): string {
+    const envStr = Object.entries(options.env)
+      .filter(([k]) => k.startsWith("PI_"))
+      .map(([k, v]) => `${k}=${v}`)
+      .join(" ");
+    
+    const itermCmd = `cd '${options.cwd}' && ${envStr} ${options.command}`;
+    const escapedCmd = itermCmd.replace(/"/g, '\\"');
+
+    let script: string;
+    
+    if (!this.spawnContext.lastSessionId) {
+      // First teammate: split current session vertically (side-by-side)
+      script = `tell application "iTerm2"
+  tell current session of current window
+    set newSession to split vertically with default profile
+    tell newSession
+      write text "${escapedCmd}"
+      return id
+    end tell
+  end tell
+end tell`;
+    } else {
+      // Subsequent teammate: split the last teammate's session horizontally (stacking)
+      script = `tell application "iTerm2"
+  repeat with aWindow in windows
+    repeat with aTab in tabs of aWindow
+      repeat with aSession in sessions of aTab
+        if id of aSession is "${this.spawnContext.lastSessionId}" then
+          tell aSession
+            set newSession to split horizontally with default profile
+            tell newSession
+              write text "${escapedCmd}"
+              return id
+            end tell
+          end tell
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell`;
+    }
+
+    const result = execCommand("osascript", ["-e", script]);
+    
+    if (result.status !== 0) {
+      throw new Error(`osascript failed with status ${result.status}: ${result.stderr}`);
+    }
+
+    const sessionId = result.stdout.toString().trim();
+    this.spawnContext.lastSessionId = sessionId;
+    
+    return `iterm_${sessionId}`;
+  }
+
+  kill(paneId: string): void {
+    if (!paneId || !paneId.startsWith("iterm_")) {
+      return; // Not an iTerm2 pane
+    }
+
+    const itermId = paneId.replace("iterm_", "");
+    const script = `tell application "iTerm2"
+  repeat with aWindow in windows
+    repeat with aTab in tabs of aWindow
+      repeat with aSession in sessions of aTab
+        if id of aSession is "${itermId}" then
+          close aSession
+          return "Closed"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell`;
+
+    try {
+      execCommand("osascript", ["-e", script]);
+    } catch {
+      // Ignore errors - session may already be closed
+    }
+  }
+
+  isAlive(paneId: string): boolean {
+    if (!paneId || !paneId.startsWith("iterm_")) {
+      return false; // Not an iTerm2 pane
+    }
+
+    const itermId = paneId.replace("iterm_", "");
+    const script = `tell application "iTerm2"
+  repeat with aWindow in windows
+    repeat with aTab in tabs of aWindow
+      repeat with aSession in sessions of aTab
+        if id of aSession is "${itermId}" then
+          return "Alive"
+        end if
+      end repeat
+    end repeat
+  end repeat
+end tell`;
+
+    try {
+      const result = execCommand("osascript", ["-e", script]);
+      return result.stdout.includes("Alive");
+    } catch {
+      return false;
+    }
+  }
+
+  setTitle(title: string): void {
+    try {
+      execCommand("osascript", [
+        "-e",
+        `tell application "iTerm2" to tell current session of current window to set name to "${title}"`
+      ]);
+    } catch {
+      // Ignore errors
+    }
+  }
+
+  /**
+   * Set the spawn context (used to restore state when needed)
+   */
+  setSpawnContext(context: Iterm2SpawnContext): void {
+    this.spawnContext = context;
+  }
+
+  /**
+   * Get current spawn context (useful for persisting state)
+   */
+  getSpawnContext(): Iterm2SpawnContext {
+    return { ...this.spawnContext };
+  }
+}

package/src/adapters/terminal-registry.ts

@@ -0,0 +1,92 @@
+/**
+ * Terminal Registry
+ * 
+ * Manages terminal adapters and provides automatic selection based on
+ * the current environment.
+ */
+
+import { TerminalAdapter } from "../utils/terminal-adapter";
+import { TmuxAdapter } from "./tmux-adapter";
+import { Iterm2Adapter } from "./iterm2-adapter";
+import { ZellijAdapter } from "./zellij-adapter";
+
+/**
+ * Available terminal adapters, ordered by priority
+ */
+const adapters: TerminalAdapter[] = [
+  new TmuxAdapter(),
+  new Iterm2Adapter(),
+  new ZellijAdapter(),
+];
+
+/**
+ * Cached detected adapter
+ */
+let cachedAdapter: TerminalAdapter | null = null;
+
+/**
+ * Detect and return the appropriate terminal adapter for the current environment.
+ * 
+ * Detection order (first match wins):
+ * 1. tmux - if TMUX env is set
+ * 2. iTerm2 - if TERM_PROGRAM=iTerm.app and not in tmux/zellij
+ * 3. Zellij - if ZELLIJ env is set and not in tmux
+ * 
+ * @returns The detected terminal adapter, or null if none detected
+ */
+export function getTerminalAdapter(): TerminalAdapter | null {
+  if (cachedAdapter) {
+    return cachedAdapter;
+  }
+
+  for (const adapter of adapters) {
+    if (adapter.detect()) {
+      cachedAdapter = adapter;
+      return adapter;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Get a specific terminal adapter by name.
+ * 
+ * @param name - The adapter name (e.g., "tmux", "iTerm2", "zellij")
+ * @returns The adapter instance, or undefined if not found
+ */
+export function getAdapterByName(name: string): TerminalAdapter | undefined {
+  return adapters.find(a => a.name === name);
+}
+
+/**
+ * Get all available adapters.
+ * 
+ * @returns Array of all registered adapters
+ */
+export function getAllAdapters(): TerminalAdapter[] {
+  return [...adapters];
+}
+
+/**
+ * Clear the cached adapter (useful for testing or environment changes)
+ */
+export function clearAdapterCache(): void {
+  cachedAdapter = null;
+}
+
+/**
+ * Set a specific adapter (useful for testing or forced selection)
+ */
+export function setAdapter(adapter: TerminalAdapter): void {
+  cachedAdapter = adapter;
+}
+
+/**
+ * Check if any terminal adapter is available.
+ * 
+ * @returns true if a terminal adapter was detected
+ */
+export function hasTerminalAdapter(): boolean {
+  return getTerminalAdapter() !== null;
+}

package/src/adapters/tmux-adapter.ts

@@ -0,0 +1,77 @@
+/**
+ * Tmux Terminal Adapter
+ * 
+ * Implements the TerminalAdapter interface for tmux terminal multiplexer.
+ */
+
+import { execSync } from "node:child_process";
+import { TerminalAdapter, SpawnOptions, execCommand } from "../utils/terminal-adapter";
+
+export class TmuxAdapter implements TerminalAdapter {
+  readonly name = "tmux";
+
+  detect(): boolean {
+    // tmux is available if TMUX environment variable is set
+    return !!process.env.TMUX;
+  }
+
+  spawn(options: SpawnOptions): string {
+    const envArgs = Object.entries(options.env)
+      .filter(([k]) => k.startsWith("PI_"))
+      .map(([k, v]) => `${k}=${v}`);
+
+    const tmuxArgs = [
+      "split-window",
+      "-h", "-dP",
+      "-F", "#{pane_id}",
+      "-c", options.cwd,
+      "env", ...envArgs,
+      "sh", "-c", options.command
+    ];
+
+    const result = execCommand("tmux", tmuxArgs);
+    
+    if (result.status !== 0) {
+      throw new Error(`tmux spawn failed with status ${result.status}: ${result.stderr}`);
+    }
+
+    // Apply layout after spawning
+    execCommand("tmux", ["set-window-option", "main-pane-width", "60%"]);
+    execCommand("tmux", ["select-layout", "main-vertical"]);
+
+    return result.stdout.trim();
+  }
+
+  kill(paneId: string): void {
+    if (!paneId || paneId.startsWith("iterm_") || paneId.startsWith("zellij_")) {
+      return; // Not a tmux pane
+    }
+    
+    try {
+      execCommand("tmux", ["kill-pane", "-t", paneId.trim()]);
+    } catch {
+      // Ignore errors - pane may already be dead
+    }
+  }
+
+  isAlive(paneId: string): boolean {
+    if (!paneId || paneId.startsWith("iterm_") || paneId.startsWith("zellij_")) {
+      return false; // Not a tmux pane
+    }
+
+    try {
+      execSync(`tmux has-session -t ${paneId}`);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  setTitle(title: string): void {
+    try {
+      execCommand("tmux", ["select-pane", "-T", title]);
+    } catch {
+      // Ignore errors
+    }
+  }
+}

package/src/adapters/zellij-adapter.ts

@@ -0,0 +1,62 @@
+/**
+ * Zellij Terminal Adapter
+ * 
+ * Implements the TerminalAdapter interface for Zellij terminal multiplexer.
+ * Note: Zellij uses --close-on-exit, so explicit kill is not needed.
+ */
+
+import { TerminalAdapter, SpawnOptions, execCommand } from "../utils/terminal-adapter";
+
+export class ZellijAdapter implements TerminalAdapter {
+  readonly name = "zellij";
+
+  detect(): boolean {
+    // Zellij is available if ZELLIJ env is set and not in tmux
+    return !!process.env.ZELLIJ && !process.env.TMUX;
+  }
+
+  spawn(options: SpawnOptions): string {
+    const zellijArgs = [
+      "run",
+      "--name", options.name,
+      "--cwd", options.cwd,
+      "--close-on-exit",
+      "--",
+      "env",
+      ...Object.entries(options.env)
+        .filter(([k]) => k.startsWith("PI_"))
+        .map(([k, v]) => `${k}=${v}`),
+      "sh", "-c", options.command
+    ];
+
+    const result = execCommand("zellij", zellijArgs);
+    
+    if (result.status !== 0) {
+      throw new Error(`zellij spawn failed with status ${result.status}: ${result.stderr}`);
+    }
+
+    // Zellij doesn't return a pane ID, so we create a synthetic one
+    return `zellij_${options.name}`;
+  }
+
+  kill(_paneId: string): void {
+    // Zellij uses --close-on-exit, so panes close automatically
+    // when the process exits. No explicit kill needed.
+  }
+
+  isAlive(paneId: string): boolean {
+    // Zellij doesn't have a straightforward way to check if a pane is alive
+    // For now, we assume alive if it's a zellij pane ID
+    if (!paneId || !paneId.startsWith("zellij_")) {
+      return false;
+    }
+    
+    // Could potentially use `zellij list-sessions` or similar in the future
+    return true;
+  }
+
+  setTitle(_title: string): void {
+    // Zellij pane titles are set via --name at spawn time
+    // No runtime title changing supported
+  }
+}

package/src/utils/terminal-adapter.ts

@@ -0,0 +1,85 @@
+/**
+ * Terminal Adapter Interface
+ * 
+ * Abstracts terminal multiplexer operations (tmux, iTerm2, Zellij)
+ * to provide a unified API for spawning, managing, and terminating panes.
+ */
+
+import { spawnSync } from "node:child_process";
+
+/**
+ * Options for spawning a new terminal pane
+ */
+export interface SpawnOptions {
+  /** Name/identifier for the pane */
+  name: string;
+  /** Working directory for the new pane */
+  cwd: string;
+  /** Command to execute in the pane */
+  command: string;
+  /** Environment variables to set (key-value pairs) */
+  env: Record<string, string>;
+}
+
+/**
+ * Terminal Adapter Interface
+ * 
+ * Implementations provide terminal-specific logic for pane management.
+ */
+export interface TerminalAdapter {
+  /** Unique name identifier for this terminal type */
+  readonly name: string;
+
+  /**
+   * Detect if this terminal is currently available/active.
+   * Should check for terminal-specific environment variables or processes.
+   * 
+   * @returns true if this terminal should be used
+   */
+  detect(): boolean;
+
+  /**
+   * Spawn a new terminal pane with the given options.
+   * 
+   * @param options - Spawn configuration
+   * @returns Pane ID that can be used for subsequent operations
+   * @throws Error if spawn fails
+   */
+  spawn(options: SpawnOptions): string;
+
+  /**
+   * Kill/terminate a terminal pane.
+   * Should be idempotent - no error if pane doesn't exist.
+   * 
+   * @param paneId - The pane ID returned from spawn()
+   */
+  kill(paneId: string): void;
+
+  /**
+   * Check if a terminal pane is still alive/active.
+   * 
+   * @param paneId - The pane ID returned from spawn()
+   * @returns true if pane exists and is active
+   */
+  isAlive(paneId: string): boolean;
+
+  /**
+   * Set the title of the current terminal pane/window.
+   * Used for identifying panes in the terminal UI.
+   * 
+   * @param title - The title to set
+   */
+  setTitle(title: string): void;
+}
+
+/**
+ * Base helper for adapters to execute commands synchronously.
+ */
+export function execCommand(command: string, args: string[]): { stdout: string; stderr: string; status: number | null } {
+  const result = spawnSync(command, args, { encoding: "utf-8" });
+  return {
+    stdout: result.stdout?.toString() ?? "",
+    stderr: result.stderr?.toString() ?? "",
+    status: result.status,
+  };
+}