opencode-agent-tmux 1.0.0

package/README.md

@@ -0,0 +1,162 @@
+# opencode-agent-tmux
+
+OpenCode plugin that provides tmux integration for viewing agent execution in real-time. Automatically spawns panes, streams output, and manages your terminal workspace.
+
+## 🤖 For Humans (Quick Start)
+
+Want to get started immediately? Just paste this prompt into your OpenCode agent (or any other agentic tool like Claude Code) and let it handle the setup for you:
+
+```text
+Please install the opencode-agent-tmux plugin for me.
+
+1. Clone the repository to ~/Code/opencode-agent-tmux
+2. Run 'bun install' and 'bun run build' inside the directory
+3. Add the plugin path to my ~/.config/opencode/opencode.json file
+4. Verify the installation by running 'opencode --version'
+
+The plugin repo is: https://github.com/AnganSamadder/opencode-agent-tmux.git
+```
+
+## ✨ Features
+
+- **Automatic Tmux Pane Spawning**: When any agent starts, automatically spawns a tmux pane
+- **Live Streaming**: Each pane runs `opencode attach` to show real-time agent output
+- **Auto-Cleanup**: Panes automatically close when agents complete
+- **Configurable Layout**: Support multiple tmux layouts (main-vertical, tiled, etc.)
+- **Multi-Port Support**: Automatically finds available ports when running multiple instances
+- **Agent-Agnostic**: Works with oh-my-opencode, omoc-slim, or vanilla OpenCode
+
+## 📋 Requirements
+
+- **OpenCode**
+- **tmux**
+- **Bun** (for building)
+
+## 📦 Installation (Official)
+
+1.  **Install via NPM:**
+    ```bash
+    npm install -g opencode-agent-tmux
+    ```
+    *Note: The installation automatically configures a shell alias to enable the smart tmux wrapper.*
+
+2.  **Configure OpenCode:**
+    Add the plugin name to your `~/.config/opencode/opencode.json`:
+    ```json
+    {
+      "plugins": [
+        "opencode-agent-tmux"
+      ]
+    }
+    ```
+
+## 🛠 Manual Installation (Development)
+
+If you prefer to install it yourself:
+
+1.  **Clone the repository:**
+    ```bash
+    git clone https://github.com/AnganSamadder/opencode-agent-tmux.git ~/Code/opencode-agent-tmux
+    ```
+
+2.  **Build the plugin:**
+    ```bash
+    cd ~/Code/opencode-agent-tmux
+    bun install
+    bun run build
+    ```
+
+3.  **Configure OpenCode:**
+    Add the plugin to your `~/.config/opencode/opencode.json`:
+    ```json
+    {
+      "plugins": [
+        "~/Code/opencode-agent-tmux"
+      ]
+    }
+    ```
+
+## 🚀 Usage
+
+### Easy Mode (Recommended)
+
+After installation, just type:
+
+```bash
+opencode
+```
+
+The wrapper automatically:
+- Launches tmux if you're not already in it
+- Finds an available port (4096-4106) if default is in use
+- Starts OpenCode with the available port
+- Enables the plugin to spawn panes for agents
+
+### Running Multiple Instances
+
+Want to run multiple OpenCode sessions? No problem:
+
+```bash
+# Terminal 1
+opencode
+# → Starts on port 4096
+
+# Terminal 2
+opencode
+# → Detects 4096 in use, automatically uses port 4097
+```
+
+Each instance works independently with its own tmux panes!
+
+### Manual Mode
+
+Or start OpenCode inside tmux manually:
+
+```bash
+tmux
+opencode --port 4096
+```
+
+## ⚙️ Configuration
+
+You can customize behavior by creating `~/.config/opencode/opencode-agent-tmux.json`:
+
+```json
+{
+  "enabled": true,
+  "port": 4096,
+  "layout": "main-vertical",
+  "main_pane_size": 60,
+  "auto_close": true
+}
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `enabled` | boolean | `true` | Enable/disable the plugin |
+| `port` | number | `4096` | OpenCode server port |
+| `layout` | string | `"main-vertical"` | Tmux layout: `main-horizontal`, `main-vertical`, `tiled`, etc. |
+| `main_pane_size` | number | `60` | Size of main pane (20-80%) |
+| `auto_close` | boolean | `true` | Auto-close panes when sessions complete |
+
+## ❓ Troubleshooting
+
+### Panes Not Spawning
+1. Verify you're inside tmux: `echo $TMUX`
+2. Check tmux is installed: `which tmux`
+3. Check OpenCode server is running with port: `opencode --port 4096`
+4. Check logs: `cat /tmp/opencode-agent-tmux.log`
+
+### Server Not Found
+Make sure OpenCode is started with the `--port` flag matching your config:
+```bash
+opencode --port 4096
+```
+
+## 📄 License
+
+MIT
+
+## 🙏 Acknowledgements
+
+This project extracts and improves upon the tmux session management from [oh-my-opencode-slim](https://github.com/alvinunreal/oh-my-opencode-slim) by alvinunreal.

package/bin/opencode-tmux.js

@@ -0,0 +1,127 @@
+#!/usr/bin/env node
+
+import { spawn, execSync } from 'child_process';
+import { createServer } from 'net';
+import { env, platform, exit, argv } from 'process';
+import { existsSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+const OPENCODE_PORT_START = parseInt(env.OPENCODE_PORT || '4096', 10);
+const OPENCODE_PORT_MAX = OPENCODE_PORT_START + 10;
+
+function findOpencodeBin() {
+  try {
+    const cmd = platform === 'win32' ? 'where opencode' : 'which -a opencode';
+    const output = execSync(cmd, { encoding: 'utf-8' }).trim().split('\n');
+    const currentScript = process.argv[1];
+    
+    for (const bin of output) {
+      const normalizedBin = bin.trim();
+      if (normalizedBin.includes('opencode-tmux') || normalizedBin === currentScript) continue;
+      if (normalizedBin) return normalizedBin;
+    }
+  } catch (e) {
+  }
+
+  const commonPaths = [
+    join(homedir(), '.opencode', 'bin', platform === 'win32' ? 'opencode.exe' : 'opencode'),
+    join(homedir(), 'AppData', 'Local', 'opencode', 'bin', 'opencode.exe'),
+    '/usr/local/bin/opencode',
+    '/usr/bin/opencode'
+  ];
+
+  for (const p of commonPaths) {
+    if (existsSync(p)) return p;
+  }
+
+  return null;
+}
+
+function checkPort(port) {
+  return new Promise((resolve) => {
+    const server = createServer();
+    server.listen(port, '127.0.0.1');
+    server.on('listening', () => {
+      server.close();
+      resolve(true);
+    });
+    server.on('error', () => {
+      resolve(false);
+    });
+  });
+}
+
+async function findAvailablePort() {
+  for (let port = OPENCODE_PORT_START; port <= OPENCODE_PORT_MAX; port++) {
+    if (await checkPort(port)) return port;
+  }
+  return null;
+}
+
+function hasTmux() {
+  try {
+    execSync('tmux -V', { stdio: 'ignore' });
+    return true;
+  } catch (e) {
+    return false;
+  }
+}
+
+async function main() {
+  const opencodeBin = findOpencodeBin();
+  if (!opencodeBin) {
+    console.error("❌ Error: Could not find 'opencode' binary.");
+    console.error("   Please ensure OpenCode is installed and in your PATH.");
+    exit(1);
+  }
+
+  const port = await findAvailablePort();
+  if (!port) {
+    console.error("❌ No ports available in range " + OPENCODE_PORT_START + "-" + OPENCODE_PORT_MAX);
+    exit(1);
+  }
+
+  if (port !== OPENCODE_PORT_START) {
+    console.warn(`⚠️  Port ${OPENCODE_PORT_START} is in use, using port ${port} instead`);
+  }
+
+  env.OPENCODE_PORT = port.toString();
+  const args = argv.slice(2);
+  const childArgs = ['--port', port.toString(), ...args];
+
+  const inTmux = !!env.TMUX;
+  const tmuxAvailable = hasTmux();
+
+  if (inTmux || !tmuxAvailable) {
+    const child = spawn(opencodeBin, childArgs, { stdio: 'inherit' });
+    child.on('close', (code) => exit(code));
+    
+    process.on('SIGINT', () => child.kill('SIGINT'));
+    process.on('SIGTERM', () => child.kill('SIGTERM'));
+
+  } else {
+    console.log("🚀 Launching tmux session...");
+    
+    const safeCommand = [
+      `"${opencodeBin}"`,
+      `--port ${port}`,
+      ...args.map(a => `"${a}"`)
+    ].join(' ');
+
+    const shellCommand = `${safeCommand} || { echo "Exit code: $?"; echo "Press Enter to close..."; read; }`;
+
+    const tmuxArgs = [
+      'new-session',
+      shellCommand
+    ];
+
+    const child = spawn('tmux', tmuxArgs, { stdio: 'inherit' });
+    child.on('close', (code) => exit(code));
+  }
+}
+
+main().catch(err => {
+  console.error(err);
+  exit(1);
+});

package/dist/index.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+
+interface PluginInput {
+    directory: string;
+    serverUrl?: URL | string;
+    client: {
+        session: {
+            status(): Promise<{
+                data?: Record<string, {
+                    type: string;
+                }>;
+            }>;
+            subscribe(callback: (event: {
+                type: string;
+                properties?: unknown;
+            }) => void): () => void;
+        };
+    };
+}
+interface PluginOutput {
+    name: string;
+    event?: (input: {
+        event: {
+            type: string;
+            properties?: unknown;
+        };
+    }) => Promise<void>;
+    tool?: Record<string, unknown>;
+    config?: unknown;
+}
+type Plugin = (ctx: PluginInput) => Promise<PluginOutput>;
+
+declare const TmuxLayoutSchema: z.ZodEnum<["main-horizontal", "main-vertical", "tiled", "even-horizontal", "even-vertical"]>;
+type TmuxLayout = z.infer<typeof TmuxLayoutSchema>;
+declare const TmuxConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    layout: z.ZodDefault<z.ZodEnum<["main-horizontal", "main-vertical", "tiled", "even-horizontal", "even-vertical"]>>;
+    main_pane_size: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    layout: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical";
+    main_pane_size: number;
+}, {
+    enabled?: boolean | undefined;
+    layout?: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical" | undefined;
+    main_pane_size?: number | undefined;
+}>;
+type TmuxConfig = z.infer<typeof TmuxConfigSchema>;
+declare const PluginConfigSchema: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    port: z.ZodDefault<z.ZodNumber>;
+    layout: z.ZodDefault<z.ZodEnum<["main-horizontal", "main-vertical", "tiled", "even-horizontal", "even-vertical"]>>;
+    main_pane_size: z.ZodDefault<z.ZodNumber>;
+    auto_close: z.ZodDefault<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    port: number;
+    layout: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical";
+    main_pane_size: number;
+    auto_close: boolean;
+}, {
+    enabled?: boolean | undefined;
+    port?: number | undefined;
+    layout?: "main-horizontal" | "main-vertical" | "tiled" | "even-horizontal" | "even-vertical" | undefined;
+    main_pane_size?: number | undefined;
+    auto_close?: boolean | undefined;
+}>;
+type PluginConfig = z.infer<typeof PluginConfigSchema>;
+
+declare const OpencodeAgentTmux: Plugin;
+
+export { type PluginConfig, type TmuxConfig, type TmuxLayout, OpencodeAgentTmux as default };

package/dist/index.js

@@ -0,0 +1,508 @@
+// src/index.ts
+import * as fs2 from "fs";
+import * as path2 from "path";
+
+// src/config.ts
+import { z } from "zod";
+var TmuxLayoutSchema = z.enum([
+  "main-horizontal",
+  "main-vertical",
+  "tiled",
+  "even-horizontal",
+  "even-vertical"
+]);
+var TmuxConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  layout: TmuxLayoutSchema.default("main-vertical"),
+  main_pane_size: z.number().min(20).max(80).default(60)
+});
+var PluginConfigSchema = z.object({
+  enabled: z.boolean().default(true),
+  port: z.number().default(4096),
+  layout: TmuxLayoutSchema.default("main-vertical"),
+  main_pane_size: z.number().min(20).max(80).default(60),
+  auto_close: z.boolean().default(true)
+});
+var POLL_INTERVAL_MS = 2e3;
+var SESSION_TIMEOUT_MS = 10 * 60 * 1e3;
+var SESSION_MISSING_GRACE_MS = POLL_INTERVAL_MS * 3;
+
+// src/utils/logger.ts
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+var logFile = path.join(os.tmpdir(), "opencode-agent-tmux.log");
+function log(message, data) {
+  try {
+    const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+    const logEntry = `[${timestamp}] ${message} ${data ? JSON.stringify(data) : ""}
+`;
+    fs.appendFileSync(logFile, logEntry);
+  } catch {
+  }
+}
+
+// src/utils/tmux.ts
+import { spawn } from "child_process";
+var tmuxPath = null;
+var tmuxChecked = false;
+var storedConfig = null;
+var serverAvailable = null;
+var serverCheckUrl = null;
+async function spawnAsync(command, options) {
+  return new Promise((resolve) => {
+    const [cmd, ...args] = command;
+    const proc = spawn(cmd, args, { stdio: "pipe" });
+    let stdout = "";
+    let stderr = "";
+    if (!options?.ignoreOutput) {
+      proc.stdout?.on("data", (data) => {
+        stdout += data.toString();
+      });
+      proc.stderr?.on("data", (data) => {
+        stderr += data.toString();
+      });
+    }
+    proc.on("close", (code) => {
+      resolve({
+        exitCode: code ?? 1,
+        stdout,
+        stderr
+      });
+    });
+    proc.on("error", () => {
+      resolve({
+        exitCode: 1,
+        stdout,
+        stderr
+      });
+    });
+  });
+}
+async function isServerRunning(serverUrl) {
+  if (serverCheckUrl === serverUrl && serverAvailable === true) {
+    return true;
+  }
+  const healthUrl = new URL("/health", serverUrl).toString();
+  const timeoutMs = 3e3;
+  const maxAttempts = 2;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    let response = null;
+    try {
+      response = await fetch(healthUrl, { signal: controller.signal }).catch(
+        () => null
+      );
+    } finally {
+      clearTimeout(timeout);
+    }
+    const available = response?.ok ?? false;
+    if (available) {
+      serverCheckUrl = serverUrl;
+      serverAvailable = true;
+      log("[tmux] isServerRunning: checked", { serverUrl, available, attempt });
+      return true;
+    }
+    if (attempt < maxAttempts) {
+      await new Promise((r) => setTimeout(r, 250));
+    }
+  }
+  log("[tmux] isServerRunning: checked", { serverUrl, available: false });
+  return false;
+}
+async function findTmuxPath() {
+  const isWindows = process.platform === "win32";
+  const cmd = isWindows ? "where" : "which";
+  try {
+    const result = await spawnAsync([cmd, "tmux"]);
+    if (result.exitCode !== 0) {
+      log("[tmux] findTmuxPath: 'which tmux' failed", {
+        exitCode: result.exitCode
+      });
+      return null;
+    }
+    const path3 = result.stdout.trim().split("\n")[0];
+    if (!path3) {
+      log("[tmux] findTmuxPath: no path in output");
+      return null;
+    }
+    const verifyResult = await spawnAsync([path3, "-V"]);
+    if (verifyResult.exitCode !== 0) {
+      log("[tmux] findTmuxPath: tmux -V failed", {
+        path: path3,
+        verifyExit: verifyResult.exitCode
+      });
+      return null;
+    }
+    log("[tmux] findTmuxPath: found tmux", { path: path3 });
+    return path3;
+  } catch (err) {
+    log("[tmux] findTmuxPath: exception", { error: String(err) });
+    return null;
+  }
+}
+async function getTmuxPath() {
+  if (tmuxChecked) {
+    return tmuxPath;
+  }
+  tmuxPath = await findTmuxPath();
+  tmuxChecked = true;
+  log("[tmux] getTmuxPath: initialized", { tmuxPath });
+  return tmuxPath;
+}
+function isInsideTmux() {
+  return !!process.env.TMUX;
+}
+async function applyLayout(tmux, layout, mainPaneSize) {
+  try {
+    await spawnAsync([tmux, "select-layout", layout]);
+    if (layout === "main-horizontal" || layout === "main-vertical") {
+      const sizeOption = layout === "main-horizontal" ? "main-pane-height" : "main-pane-width";
+      await spawnAsync([
+        tmux,
+        "set-window-option",
+        sizeOption,
+        `${mainPaneSize}%`
+      ]);
+      await spawnAsync([tmux, "select-layout", layout]);
+    }
+    log("[tmux] applyLayout: applied", { layout, mainPaneSize });
+  } catch (err) {
+    log("[tmux] applyLayout: exception", { error: String(err) });
+  }
+}
+async function spawnTmuxPane(sessionId, description, config, serverUrl) {
+  log("[tmux] spawnTmuxPane called", {
+    sessionId,
+    description,
+    config,
+    serverUrl
+  });
+  if (!config.enabled) {
+    log("[tmux] spawnTmuxPane: config.enabled is false, skipping");
+    return { success: false };
+  }
+  if (!isInsideTmux()) {
+    log("[tmux] spawnTmuxPane: not inside tmux, skipping");
+    return { success: false };
+  }
+  const serverRunning = await isServerRunning(serverUrl);
+  if (!serverRunning) {
+    const defaultPort = process.env.OPENCODE_PORT ?? "4096";
+    log("[tmux] spawnTmuxPane: OpenCode server not running, skipping", {
+      serverUrl,
+      hint: `Start opencode with --port ${defaultPort}`
+    });
+    return { success: false };
+  }
+  const tmux = await getTmuxPath();
+  if (!tmux) {
+    log("[tmux] spawnTmuxPane: tmux binary not found, skipping");
+    return { success: false };
+  }
+  storedConfig = config;
+  try {
+    const opencodeCmd = `opencode attach ${serverUrl} --session ${sessionId}`;
+    const args = [
+      "split-window",
+      "-h",
+      "-d",
+      "-P",
+      "-F",
+      "#{pane_id}",
+      opencodeCmd
+    ];
+    log("[tmux] spawnTmuxPane: executing", { tmux, args, opencodeCmd });
+    const result = await spawnAsync([tmux, ...args]);
+    const paneId = result.stdout.trim();
+    log("[tmux] spawnTmuxPane: split result", {
+      exitCode: result.exitCode,
+      paneId,
+      stderr: result.stderr.trim()
+    });
+    if (result.exitCode === 0 && paneId) {
+      await spawnAsync(
+        [tmux, "select-pane", "-t", paneId, "-T", description.slice(0, 30)],
+        { ignoreOutput: true }
+      );
+      const layout = config.layout ?? "main-vertical";
+      const mainPaneSize = config.main_pane_size ?? 60;
+      await applyLayout(tmux, layout, mainPaneSize);
+      log("[tmux] spawnTmuxPane: SUCCESS, pane created and layout applied", {
+        paneId,
+        layout
+      });
+      return { success: true, paneId };
+    }
+    return { success: false };
+  } catch (err) {
+    log("[tmux] spawnTmuxPane: exception", { error: String(err) });
+    return { success: false };
+  }
+}
+async function closeTmuxPane(paneId) {
+  log("[tmux] closeTmuxPane called", { paneId });
+  if (!paneId) {
+    log("[tmux] closeTmuxPane: no paneId provided");
+    return false;
+  }
+  const tmux = await getTmuxPath();
+  if (!tmux) {
+    log("[tmux] closeTmuxPane: tmux binary not found");
+    return false;
+  }
+  try {
+    const result = await spawnAsync([tmux, "kill-pane", "-t", paneId]);
+    log("[tmux] closeTmuxPane: result", {
+      exitCode: result.exitCode,
+      stderr: result.stderr.trim()
+    });
+    if (result.exitCode === 0) {
+      log("[tmux] closeTmuxPane: SUCCESS, pane closed", { paneId });
+      if (storedConfig) {
+        const layout = storedConfig.layout ?? "main-vertical";
+        const mainPaneSize = storedConfig.main_pane_size ?? 60;
+        await applyLayout(tmux, layout, mainPaneSize);
+        log("[tmux] closeTmuxPane: layout reapplied", { layout });
+      }
+      return true;
+    }
+    log("[tmux] closeTmuxPane: failed (pane may already be closed)", {
+      paneId
+    });
+    return false;
+  } catch (err) {
+    log("[tmux] closeTmuxPane: exception", { error: String(err) });
+    return false;
+  }
+}
+function startTmuxCheck() {
+  if (!tmuxChecked) {
+    getTmuxPath().catch(() => {
+    });
+  }
+}
+
+// src/tmux-session-manager.ts
+var TmuxSessionManager = class {
+  client;
+  tmuxConfig;
+  serverUrl;
+  sessions = /* @__PURE__ */ new Map();
+  pollInterval;
+  enabled = false;
+  constructor(ctx, tmuxConfig, serverUrl) {
+    this.client = ctx.client;
+    this.tmuxConfig = tmuxConfig;
+    this.serverUrl = serverUrl;
+    this.enabled = tmuxConfig.enabled && isInsideTmux();
+    log("[tmux-session-manager] initialized", {
+      enabled: this.enabled,
+      tmuxConfig: this.tmuxConfig,
+      serverUrl: this.serverUrl
+    });
+  }
+  async onSessionCreated(event) {
+    if (!this.enabled) return;
+    if (event.type !== "session.created") return;
+    const info = event.properties?.info;
+    if (!info?.id || !info?.parentID) {
+      return;
+    }
+    const sessionId = info.id;
+    const parentId = info.parentID;
+    const title = info.title ?? "Subagent";
+    if (this.sessions.has(sessionId)) {
+      log("[tmux-session-manager] session already tracked", { sessionId });
+      return;
+    }
+    log("[tmux-session-manager] child session created, spawning pane", {
+      sessionId,
+      parentId,
+      title
+    });
+    const paneResult = await spawnTmuxPane(
+      sessionId,
+      title,
+      this.tmuxConfig,
+      this.serverUrl
+    ).catch((err) => {
+      log("[tmux-session-manager] failed to spawn pane", {
+        error: String(err)
+      });
+      return { success: false, paneId: void 0 };
+    });
+    if (paneResult.success && paneResult.paneId) {
+      const now = Date.now();
+      this.sessions.set(sessionId, {
+        sessionId,
+        paneId: paneResult.paneId,
+        parentId,
+        title,
+        createdAt: now,
+        lastSeenAt: now
+      });
+      log("[tmux-session-manager] pane spawned", {
+        sessionId,
+        paneId: paneResult.paneId
+      });
+      this.startPolling();
+    }
+  }
+  startPolling() {
+    if (this.pollInterval) return;
+    this.pollInterval = setInterval(
+      () => this.pollSessions(),
+      POLL_INTERVAL_MS
+    );
+    log("[tmux-session-manager] polling started");
+  }
+  stopPolling() {
+    if (this.pollInterval) {
+      clearInterval(this.pollInterval);
+      this.pollInterval = void 0;
+      log("[tmux-session-manager] polling stopped");
+    }
+  }
+  async pollSessions() {
+    if (this.sessions.size === 0) {
+      this.stopPolling();
+      return;
+    }
+    try {
+      const statusResult = await this.client.session.status();
+      const allStatuses = statusResult.data ?? {};
+      const now = Date.now();
+      const sessionsToClose = [];
+      for (const [sessionId, tracked] of this.sessions.entries()) {
+        const status = allStatuses[sessionId];
+        const isIdle = status?.type === "idle";
+        if (status) {
+          tracked.lastSeenAt = now;
+          tracked.missingSince = void 0;
+        } else if (!tracked.missingSince) {
+          tracked.missingSince = now;
+        }
+        const missingTooLong = !!tracked.missingSince && now - tracked.missingSince >= SESSION_MISSING_GRACE_MS;
+        const isTimedOut = now - tracked.createdAt > SESSION_TIMEOUT_MS;
+        if (isIdle || missingTooLong || isTimedOut) {
+          sessionsToClose.push(sessionId);
+        }
+      }
+      for (const sessionId of sessionsToClose) {
+        await this.closeSession(sessionId);
+      }
+    } catch (err) {
+      log("[tmux-session-manager] poll error", { error: String(err) });
+    }
+  }
+  async closeSession(sessionId) {
+    const tracked = this.sessions.get(sessionId);
+    if (!tracked) return;
+    log("[tmux-session-manager] closing session pane", {
+      sessionId,
+      paneId: tracked.paneId
+    });
+    await closeTmuxPane(tracked.paneId);
+    this.sessions.delete(sessionId);
+    if (this.sessions.size === 0) {
+      this.stopPolling();
+    }
+  }
+  createEventHandler() {
+    return async (input) => {
+      await this.onSessionCreated(input.event);
+    };
+  }
+  async cleanup() {
+    this.stopPolling();
+    if (this.sessions.size > 0) {
+      log("[tmux-session-manager] closing all panes", {
+        count: this.sessions.size
+      });
+      const closePromises = Array.from(this.sessions.values()).map(
+        (s) => closeTmuxPane(s.paneId).catch(
+          (err) => log("[tmux-session-manager] cleanup error for pane", {
+            paneId: s.paneId,
+            error: String(err)
+          })
+        )
+      );
+      await Promise.all(closePromises);
+      this.sessions.clear();
+    }
+    log("[tmux-session-manager] cleanup complete");
+  }
+};
+
+// src/index.ts
+function detectServerUrl() {
+  if (process.env.OPENCODE_PORT) {
+    return `http://localhost:${process.env.OPENCODE_PORT}`;
+  }
+  return "http://localhost:4096";
+}
+function loadConfig(directory) {
+  const configPaths = [
+    path2.join(directory, "opencode-agent-tmux.json"),
+    path2.join(
+      process.env.HOME ?? "",
+      ".config",
+      "opencode",
+      "opencode-agent-tmux.json"
+    )
+  ];
+  for (const configPath of configPaths) {
+    try {
+      if (fs2.existsSync(configPath)) {
+        const content = fs2.readFileSync(configPath, "utf-8");
+        const parsed = JSON.parse(content);
+        const result = PluginConfigSchema.safeParse(parsed);
+        if (result.success) {
+          log("[plugin] loaded config", { configPath, config: result.data });
+          return result.data;
+        }
+        log("[plugin] config parse error", {
+          configPath,
+          error: result.error.message
+        });
+      }
+    } catch (err) {
+      log("[plugin] config load error", { configPath, error: String(err) });
+    }
+  }
+  const defaultConfig = PluginConfigSchema.parse({});
+  log("[plugin] using default config", { config: defaultConfig });
+  return defaultConfig;
+}
+var OpencodeAgentTmux = async (ctx) => {
+  const config = loadConfig(ctx.directory);
+  const tmuxConfig = {
+    enabled: config.enabled,
+    layout: config.layout,
+    main_pane_size: config.main_pane_size
+  };
+  const serverUrl = ctx.serverUrl?.toString() || detectServerUrl();
+  log("[plugin] initialized", {
+    tmuxConfig,
+    directory: ctx.directory,
+    serverUrl
+  });
+  if (tmuxConfig.enabled) {
+    startTmuxCheck();
+  }
+  const tmuxSessionManager = new TmuxSessionManager(ctx, tmuxConfig, serverUrl);
+  return {
+    name: "opencode-agent-tmux",
+    event: async (input) => {
+      await tmuxSessionManager.onSessionCreated(
+        input.event
+      );
+    }
+  };
+};
+var index_default = OpencodeAgentTmux;
+export {
+  index_default as default
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "opencode-agent-tmux",
+  "version": "1.0.0",
+  "description": "OpenCode plugin that provides tmux integration for viewing agent execution in real-time",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "opencode-tmux": "./bin/opencode-tmux.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "scripts"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "bun run build",
+    "postinstall": "node scripts/install.js"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "tmux",
+    "agent"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "zod": "^3.24.1"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.2.4",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,142 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = os.homedir();
+
+function detectShell() {
+  const shell = process.env.SHELL || '';
+  const platform = process.platform;
+  
+  if (platform === 'win32') {
+     const documents = path.join(HOME, 'Documents');
+     const psDir = path.join(documents, 'PowerShell');
+     const psProfile = path.join(psDir, 'Microsoft.PowerShell_profile.ps1');
+     return {
+         name: 'powershell',
+         rcFile: psProfile,
+         dir: psDir
+     };
+  }
+
+  if (shell.includes('zsh')) {
+    return { name: 'zsh', rcFile: path.join(HOME, '.zshrc') };
+  } else if (shell.includes('bash')) {
+    const bashProfile = path.join(HOME, '.bash_profile');
+    const bashrc = path.join(HOME, '.bashrc');
+    return {
+      name: 'bash',
+      rcFile: fs.existsSync(bashProfile) ? bashProfile : bashrc
+    };
+  } else if (shell.includes('fish')) {
+    return {
+      name: 'fish',
+      rcFile: path.join(HOME, '.config', 'fish', 'config.fish')
+    };
+  }
+  
+  return { name: 'unknown', rcFile: path.join(HOME, '.profile') };
+}
+
+function getAliasContent(shellName) {
+  if (shellName === 'powershell') {
+    return `
+function opencode {
+    opencode-tmux $args
+}
+`;
+  }
+  
+  return `alias opencode='opencode-tmux'`;
+}
+
+function getExportLine() {
+  return `export OPENCODE_PORT=4096`;
+}
+
+function setupAlias() {
+  const shell = detectShell();
+  
+  console.log('');
+  console.log('🔧 Setting up opencode-agent-tmux auto-launcher...');
+  console.log(`   Detected shell: ${shell.name}`);
+  console.log(`   Config file: ${shell.rcFile}`);
+  
+  if (shell.name === 'powershell') {
+      if (!fs.existsSync(shell.dir)) {
+          fs.mkdirSync(shell.dir, { recursive: true });
+      }
+  }
+
+  if (!fs.existsSync(shell.rcFile)) {
+    console.log(`   Creating ${shell.rcFile}...`);
+    fs.writeFileSync(shell.rcFile, '', 'utf-8');
+  }
+  
+  let rcContent = fs.readFileSync(shell.rcFile, 'utf-8');
+  const aliasContent = getAliasContent(shell.name);
+  
+  const MARKER_START = '# >>> opencode-agent-tmux >>>';
+  const MARKER_END = '# <<< opencode-agent-tmux <<<';
+  
+  const OLD_MARKER_START = '# >>> opencode-subagent-tmux >>>';
+  const OLD_MARKER_END = '# <<< opencode-subagent-tmux <<<';
+  
+  if (rcContent.includes(OLD_MARKER_START)) {
+    console.log('   Removing old opencode-subagent-tmux alias...');
+    const regex = new RegExp(`${OLD_MARKER_START}[\\s\\S]*?${OLD_MARKER_END}\\n?`, 'g');
+    rcContent = rcContent.replace(regex, '');
+    fs.writeFileSync(shell.rcFile, rcContent, 'utf-8');
+    console.log('   ✓ Removed old alias');
+    rcContent = fs.readFileSync(shell.rcFile, 'utf-8');
+  }
+  
+  if (rcContent.includes(MARKER_START)) {
+    console.log('   ✓ Auto-launcher already configured');
+    return;
+  }
+  
+  let configBlock = '';
+  if (shell.name === 'powershell') {
+      configBlock = `
+${MARKER_START}
+$env:OPENCODE_PORT="4096"
+${aliasContent}
+${MARKER_END}
+`;
+  } else {
+      configBlock = `
+${MARKER_START}
+${getExportLine()}
+${aliasContent}
+${MARKER_END}
+`;
+  }
+  
+  fs.appendFileSync(shell.rcFile, configBlock);
+  
+  console.log('   ✓ Auto-launcher configured successfully!');
+  console.log('');
+  console.log('   To activate now:');
+  if (shell.name === 'powershell') {
+      console.log(`   . ${shell.rcFile}`);
+  } else {
+      console.log(`   source ${shell.rcFile}`);
+  }
+  console.log('');
+  console.log('   Or restart your terminal.');
+  console.log('');
+  console.log('   Usage: Just type "opencode" and tmux + port 4096 will be auto-configured!');
+  console.log('');
+}
+
+try {
+  setupAlias();
+} catch (error) {
+  console.error('');
+  console.error('⚠️  Failed to auto-configure shell alias:', error.message);
+  console.error('');
+  process.exit(0);
+}