tmux-ide 1.1.0 → 1.2.1

package/bin/cli.js

@@ -13,7 +13,8 @@ import { validate } from "../src/validate.js";
 import { detect } from "../src/detect.js";
 import { config } from "../src/config.js";
 import { restart } from "../src/restart.js";
-import { CommandError, printCommandError } from "../src/lib/output.js";
+import { IdeError } from "../src/lib/errors.js";
+import { printCommandError } from "../src/lib/output.js";
 
 const { positionals, values } = parseArgs({
   allowPositionals: true,
@@ -28,6 +29,7 @@ const { positionals, values } = parseArgs({
     write: { type: "boolean" },
     template: { type: "string" },
     name: { type: "string" },
+    verbose: { type: "boolean", default: false },
     help: { type: "boolean", short: "h" },
     version: { type: "boolean", short: "v" },
   },
@@ -57,6 +59,10 @@ if (values.version) {
   process.exit(0);
 }
 
+if (values.verbose) {
+  globalThis.__tmuxIdeVerbose = true;
+}
+
 const firstPositional = positionals[0];
 const hasKnownCommand = firstPositional ? knownCommands.has(firstPositional) : false;
 const command = hasKnownCommand ? firstPositional : "start";
@@ -102,6 +108,7 @@ ${bold("Flags:")}
   ${cyan("--json")}                      ${dim("Output as JSON (all commands)")}
   ${cyan("--template <name>")}           ${dim("Use specific template for init")}
   ${cyan("--write")}                     ${dim("Write detected config to ide.yml")}
+  ${cyan("--verbose")}                   ${dim("Log all tmux commands (or set TMUX_IDE_DEBUG=1)")}
   ${cyan("-h, --help")}                  ${dim("Show usage")}
   ${cyan("-v, --version")}               ${dim("Show version number")}`);
 }
@@ -195,14 +202,13 @@ try {
       break;
 
     default:
-      throw new CommandError(`Unknown command: ${command}\nRun "tmux-ide help" for usage.`, {
+      throw new IdeError(`Unknown command: ${command}\nRun "tmux-ide help" for usage.`, {
         code: "USAGE",
         exitCode: 1,
-        json,
       });
   }
 } catch (error) {
-  if (error instanceof CommandError) {
+  if (error instanceof IdeError) {
     printCommandError(error, { json });
   } else {
     throw error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "Turn any project into a tmux-powered terminal IDE with a simple ide.yml",
   "type": "module",
   "bin": {

package/skill/SKILL.md

@@ -164,6 +164,38 @@ tmux-ide config disable-team
 
 Removes the `team` config and all `role`/`task` fields from panes.
 
+## Session features (v1.2.0)
+
+tmux-ide sessions include these built-in features:
+
+### Mouse support
+
+Mouse is enabled by default. Users can click to focus panes, scroll with trackpad, and drag pane borders to resize.
+
+### Two-line status bar
+
+```
+Line 0:  MY-PROJECT IDE            ●            14:30 │ Mar 17
+Line 1:  ⏺ Claude 1 │ ● Claude 2 │ ⏺ Dev Server │ Shell
+```
+
+- Line 0: session name, window indicators, time/date
+- Line 1: clickable pane tabs (click to switch panes)
+- Green `⏺` next to panes with a running dev server (listening TCP port)
+- Pulsing `⏺` next to panes where Claude/Codex is actively working
+- Dim `●` next to panes where Claude/Codex is idle
+
+### Config drift detection
+
+If `ide.yml` is edited while a session is running, `tmux-ide` warns the user and suggests `tmux-ide restart` to apply changes.
+
+### Debugging
+
+```bash
+tmux-ide --verbose          # Log all tmux commands to stderr
+TMUX_IDE_DEBUG=1 tmux-ide   # Same via env var
+```
+
 ## Programmatic CLI
 
 All commands support `--json` for structured output.
@@ -200,6 +232,7 @@ tmux-ide stop         # Kill session
 tmux-ide restart      # Stop and relaunch
 tmux-ide attach       # Reattach
 tmux-ide init         # Scaffold config
+tmux-ide --verbose    # Launch with tmux command tracing
 ```
 
 ## Modification workflow
@@ -207,6 +240,7 @@ tmux-ide init         # Scaffold config
 1. Read: `tmux-ide config --json`
 2. Modify: `tmux-ide config set <path> <value>` or `add-pane`/`remove-pane`
 3. Validate: `tmux-ide validate --json`
+4. Apply: `tmux-ide restart` (needed if session is already running)
 
 ## Best practices
 
@@ -218,6 +252,7 @@ tmux-ide init         # Scaffold config
 - Use `detect --json` first to understand the project stack
 - For agent teams: assign specific tasks to teammate panes so your prompts stay focused
 - The team lead should have `focus: true` for easy access
+- Use `tmux-ide --verbose` or `TMUX_IDE_DEBUG=1` when debugging layout issues
 
 ## ide.yml format
 

package/src/attach.js

@@ -3,15 +3,13 @@ import { getSessionName } from "./lib/yaml-io.js";
 import { outputError } from "./lib/output.js";
 import { attachSession, getSessionState } from "./lib/tmux.js";
 
-export async function attach(targetDir, { json } = {}) {
+export async function attach(targetDir, { json: _json } = {}) {
   const dir = resolve(targetDir ?? ".");
-  const session = getSessionName(dir);
+  const { name: session } = getSessionName(dir);
   const state = getSessionState(session);
 
   if (!state.running) {
-    outputError(`Session "${session}" is not running. Start it with: tmux-ide`, "NOT_RUNNING", {
-      json,
-    });
+    outputError(`Session "${session}" is not running. Start it with: tmux-ide`, "NOT_RUNNING");
     return;
   }
 

package/src/config.js

@@ -31,7 +31,7 @@ function dumpConfig(dir, { json }) {
   try {
     ({ config: cfg } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }
 
@@ -46,7 +46,7 @@ function dumpConfig(dir, { json }) {
 function setConfig(dir, args, { json }) {
   const [dotpath, ...rest] = args;
   if (!dotpath || rest.length === 0) {
-    outputError("Usage: tmux-ide config set <dotpath> <value>", "USAGE", { json });
+    outputError("Usage: tmux-ide config set <dotpath> <value>", "USAGE");
     return;
   }
 
@@ -54,12 +54,12 @@ function setConfig(dir, args, { json }) {
   try {
     ({ config: cfg } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }
 
   if (!isConfigObject(cfg)) {
-    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG");
     return;
   }
 
@@ -85,7 +85,6 @@ function addPane(dir, args, { json }) {
     outputError(
       "Usage: tmux-ide config add-pane --row <N> --title <T> [--command <C>] [--size <S>]",
       "USAGE",
-      { json },
     );
     return;
   }
@@ -94,30 +93,28 @@ function addPane(dir, args, { json }) {
   try {
     ({ config: cfg } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }
 
   if (!Array.isArray(cfg?.rows)) {
-    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG");
     return;
   }
 
   const rowIdx = parseIndex(row);
   if (rowIdx == null) {
-    outputError(`Invalid row index "${row}"`, "USAGE", { json });
+    outputError(`Invalid row index "${row}"`, "USAGE");
     return;
   }
 
   if (!cfg.rows[rowIdx]) {
-    outputError(`Row ${rowIdx} does not exist`, "INVALID_ROW", { json });
+    outputError(`Row ${rowIdx} does not exist`, "INVALID_ROW");
     return;
   }
 
   if (!Array.isArray(cfg.rows[rowIdx].panes)) {
-    outputError(`Invalid ide.yml: row ${rowIdx} panes must be an array`, "INVALID_CONFIG", {
-      json,
-    });
+    outputError(`Invalid ide.yml: row ${rowIdx} panes must be an array`, "INVALID_CONFIG");
     return;
   }
 
@@ -139,7 +136,7 @@ function addPane(dir, args, { json }) {
 function removePane(dir, args, { json }) {
   const { row, pane } = parseNamedArgs(args);
   if (row === undefined || pane === undefined) {
-    outputError("Usage: tmux-ide config remove-pane --row <N> --pane <M>", "USAGE", { json });
+    outputError("Usage: tmux-ide config remove-pane --row <N> --pane <M>", "USAGE");
     return;
   }
 
@@ -147,31 +144,29 @@ function removePane(dir, args, { json }) {
   try {
     ({ config: cfg } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }
 
   if (!Array.isArray(cfg?.rows)) {
-    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG");
     return;
   }
 
   const rowIdx = parseIndex(row);
   const paneIdx = parseIndex(pane);
   if (rowIdx == null || paneIdx == null) {
-    outputError("Usage: tmux-ide config remove-pane --row <N> --pane <M>", "USAGE", { json });
+    outputError("Usage: tmux-ide config remove-pane --row <N> --pane <M>", "USAGE");
     return;
   }
 
   if (!Array.isArray(cfg.rows[rowIdx]?.panes)) {
-    outputError(`Invalid ide.yml: row ${rowIdx} panes must be an array`, "INVALID_CONFIG", {
-      json,
-    });
+    outputError(`Invalid ide.yml: row ${rowIdx} panes must be an array`, "INVALID_CONFIG");
     return;
   }
 
   if (!cfg.rows[rowIdx].panes[paneIdx]) {
-    outputError(`Pane ${paneIdx} in row ${rowIdx} does not exist`, "INVALID_PANE", { json });
+    outputError(`Pane ${paneIdx} in row ${rowIdx} does not exist`, "INVALID_PANE");
     return;
   }
 
@@ -192,17 +187,17 @@ function addRow(dir, args, { json }) {
   try {
     ({ config: cfg } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }
 
   if (!isConfigObject(cfg)) {
-    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG");
     return;
   }
 
   if (cfg.rows !== undefined && !Array.isArray(cfg.rows)) {
-    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG");
     return;
   }
 
@@ -228,17 +223,17 @@ function enableTeam(dir, args, { json }) {
   try {
     ({ config: cfg } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }
 
   if (!isConfigObject(cfg)) {
-    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG");
     return;
   }
 
   if (cfg.rows !== undefined && !Array.isArray(cfg.rows)) {
-    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG");
     return;
   }
 
@@ -261,7 +256,7 @@ function enableTeam(dir, args, { json }) {
   }
   if (!leadAssigned) {
     delete cfg.team;
-    outputError("Cannot enable agent team: no Claude panes found", "INVALID_CONFIG", { json });
+    outputError("Cannot enable agent team: no Claude panes found", "INVALID_CONFIG");
     return;
   }
 
@@ -279,17 +274,17 @@ function disableTeam(dir, { json }) {
   try {
     ({ config: cfg } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }
 
   if (!isConfigObject(cfg)) {
-    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG");
     return;
   }
 
   if (cfg.rows !== undefined && !Array.isArray(cfg.rows)) {
-    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG");
     return;
   }
 

package/src/init.js

@@ -11,20 +11,14 @@ export async function init({ template, json } = {}) {
   const configPath = resolve(dir, "ide.yml");
 
   if (existsSync(configPath)) {
-    outputError("ide.yml already exists in this directory", "EXISTS", { json });
+    outputError("ide.yml already exists in this directory", "EXISTS");
   }
 
   // If a specific template is requested, use it
   if (template) {
     const templatePath = resolve(__dirname, "..", "templates", `${template}.yml`);
     if (!existsSync(templatePath)) {
-      outputError(
-        json
-          ? `Template "${template}" not found`
-          : `Template "${template}" not found. Available: default, nextjs, convex, vite, python, go, agent-team, agent-team-nextjs, agent-team-monorepo`,
-        "NOT_FOUND",
-        { json },
-      );
+      outputError(`Template "${template}" not found`, "NOT_FOUND");
     }
 
     let content = readFileSync(templatePath, "utf-8");

package/src/inspect.js

@@ -67,7 +67,7 @@ export async function inspect(targetDir, { json } = {}) {
   try {
     ({ config, configPath } = readConfig(dir));
   } catch (error) {
-    outputError(`Cannot read ide.yml: ${error.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${error.message}`, "READ_ERROR");
     return;
   }
 

package/src/launch.js

@@ -1,20 +1,26 @@
-import { resolve } from "node:path";
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { execSync } from "node:child_process";
+import { createHash } from "node:crypto";
 import { readConfig, getSessionName } from "./lib/yaml-io.js";
 import { computeSizes, toSplitPercents } from "./lib/sizes.js";
 import { outputError } from "./lib/output.js";
-import { buildThemeOptions, collectPaneStartupPlan } from "./lib/launch-plan.js";
+import { collectPaneStartupPlan } from "./lib/launch-plan.js";
+import { buildSessionOptions } from "./lib/session-options.js";
 import {
   attachSession,
   createDetachedSession,
   getPaneCurrentCommand,
+  getSessionVariable,
   hasSession,
   runSessionCommand,
   selectPane,
   sendLiteral,
   setPaneTitle,
   setSessionEnvironment,
+  setSessionVariable,
   splitPane,
+  startSessionMonitor,
 } from "./lib/tmux.js";
 import { validateConfig } from "./validate.js";
 
@@ -22,6 +28,10 @@ function sleepMs(ms) {
   Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 
+function configHash(config) {
+  return createHash("sha256").update(JSON.stringify(config)).digest("hex").slice(0, 12);
+}
+
 export function waitForPaneCommand(
   targetPane,
   expectedCommands,
@@ -93,7 +103,7 @@ export function buildPaneMap(rows, dir, rootPaneId, splitPane) {
   return { paneMap, firstPanesOfRows };
 }
 
-function loadLaunchConfig(dir, { json } = {}) {
+function loadLaunchConfig(dir) {
   let config;
 
   try {
@@ -103,11 +113,10 @@ function loadLaunchConfig(dir, { json } = {}) {
       outputError(
         `No ide.yml found in ${dir}. Run "tmux-ide init" or "tmux-ide detect --write" to create one.`,
         "CONFIG_NOT_FOUND",
-        { json },
       );
     }
 
-    outputError(`Cannot read ide.yml: ${error.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${error.message}`, "READ_ERROR");
   }
 
   const errors = validateConfig(config);
@@ -115,14 +124,13 @@ function loadLaunchConfig(dir, { json } = {}) {
     outputError(
       `Invalid ide.yml in ${dir}. Run "tmux-ide validate" for details.`,
       "INVALID_CONFIG",
-      { json },
     );
   }
 
   return config;
 }
 
-function runBeforeHook(command, dir, { json } = {}) {
+function runBeforeHook(command, dir) {
   if (!command) return;
 
   console.log(`Running: ${command}`);
@@ -130,27 +138,37 @@ function runBeforeHook(command, dir, { json } = {}) {
   try {
     execSync(command, { cwd: dir, stdio: "inherit" });
   } catch {
-    const message = json
-      ? `The "before" hook failed: ${command}`
-      : `The before hook failed: ${command}`;
-    outputError(message, "BEFORE_HOOK_FAILED", { json });
+    outputError(`The before hook failed: ${command}`, "BEFORE_HOOK_FAILED");
   }
 }
 
-export async function launch(targetDir, { json, attach = true } = {}) {
+export async function launch(targetDir, { json = false, attach = true } = {}) {
   const dir = resolve(targetDir ?? ".");
-  const config = loadLaunchConfig(dir, { json });
+  const config = loadLaunchConfig(dir);
 
-  const session = config.name ?? getSessionName(dir);
+  const { name: fallbackName } = getSessionName(dir);
+  const session = config.name ?? fallbackName;
   const rows = config.rows;
   const theme = config.theme ?? {};
   const team = config.team ?? null;
 
-  runBeforeHook(config.before, dir, { json });
+  runBeforeHook(config.before, dir);
 
-  // If session already exists, just attach to it
+  // If session already exists, check for config drift and attach
   if (hasSession(session)) {
-    console.log(`Session "${session}" is already running. Attaching...`);
+    const currentHash = configHash(config);
+    const storedHash = getSessionVariable(session, "@config_hash");
+    const configChanged = Boolean(storedHash && currentHash !== storedHash);
+
+    if (json) {
+      console.log(JSON.stringify({ session, running: true, configChanged }));
+    } else if (configChanged) {
+      console.log(`Session "${session}" is running but ide.yml has changed.`);
+      console.log(`Run "tmux-ide restart" to apply changes.`);
+    } else {
+      console.log(`Session "${session}" is already running. Attaching...`);
+    }
+
     if (attach) {
       attachSession(session);
     }
@@ -176,13 +194,7 @@ export async function launch(targetDir, { json, attach = true } = {}) {
     ({ targetPane, direction, cwd, percent }) => splitPane(targetPane, direction, cwd, percent),
   );
 
-  const { focusPane, leadPane, paneActions, teammateCommands } = collectPaneStartupPlan(
-    rows,
-    paneMap,
-    firstPanesOfRows,
-    dir,
-    team,
-  );
+  const { focusPane, paneActions } = collectPaneStartupPlan(rows, paneMap, firstPanesOfRows, dir);
 
   for (const action of paneActions) {
     if (action.title) {
@@ -202,20 +214,21 @@ export async function launch(targetDir, { json, attach = true } = {}) {
     }
   }
 
-  // Keep a second pass hook available for future staged startup behavior.
-  if (teammateCommands.length > 0) {
-    if (leadPane) {
-      waitForPaneCommand(leadPane, ["claude"]);
-    }
-    for (const { pane: p, cmd } of teammateCommands) {
-      sendLiteral(p, cmd);
-    }
-  }
-
-  for (const command of buildThemeOptions(session, theme)) {
+  for (const command of buildSessionOptions(session, { theme })) {
     runSessionCommand(command);
   }
 
+  // Store config hash for drift detection on re-launch
+  setSessionVariable(session, "@config_hash", configHash(config));
+
+  // Start background session monitor (port detection + agent status)
+  const monitorScript = resolve(
+    dirname(fileURLToPath(import.meta.url)),
+    "lib",
+    "session-monitor.js",
+  );
+  startSessionMonitor(session, monitorScript);
+
   // Focus the correct pane
   selectPane(focusPane);
 

package/src/lib/errors.js

@@ -0,0 +1,35 @@
+export class IdeError extends Error {
+  constructor(message, { code, exitCode = 1, cause } = {}) {
+    super(message, { cause });
+    this.name = "IdeError";
+    this.code = code;
+    this.exitCode = exitCode;
+  }
+
+  toJSON() {
+    const obj = { error: this.message, code: this.code };
+    if (this.cause) obj.cause = this.cause.message;
+    return obj;
+  }
+}
+
+export class ConfigError extends IdeError {
+  constructor(message, code, { cause } = {}) {
+    super(message, { code, exitCode: 1, cause });
+    this.name = "ConfigError";
+  }
+}
+
+export class TmuxError extends IdeError {
+  constructor(message, code, { cause } = {}) {
+    super(message, { code, exitCode: 1, cause });
+    this.name = "TmuxError";
+  }
+}
+
+export class SessionError extends IdeError {
+  constructor(message, code, { cause } = {}) {
+    super(message, { code, exitCode: 1, cause });
+    this.name = "SessionError";
+  }
+}

package/src/lib/launch-plan.js

@@ -1,13 +1,12 @@
 import { resolve } from "node:path";
 
-export function buildPaneCommand(pane, _team) {
+export function buildPaneCommand(pane) {
   if (!pane.command) return null;
   return pane.command;
 }
 
-export function collectPaneStartupPlan(rows, paneMap, firstPanesOfRows, dir, team) {
+export function collectPaneStartupPlan(rows, paneMap, firstPanesOfRows, dir) {
   let focusPane = paneMap[0][0];
-  const teammateCommands = [];
   const paneActions = [];
 
   for (let rowIdx = 0; rowIdx < rows.length; rowIdx++) {
@@ -33,7 +32,7 @@ export function collectPaneStartupPlan(rows, paneMap, firstPanesOfRows, dir, tea
         action.exports = Object.entries(pane.env).map(([key, value]) => `export ${key}=${value}`);
       }
 
-      const command = buildPaneCommand(pane, team);
+      const command = buildPaneCommand(pane);
       if (command) {
         action.command = command;
       }
@@ -46,38 +45,5 @@ export function collectPaneStartupPlan(rows, paneMap, firstPanesOfRows, dir, tea
     }
   }
 
-  return { focusPane, leadPane: null, paneActions, teammateCommands };
-}
-
-export function buildThemeOptions(session, theme = {}) {
-  const accent = theme.accent ?? "colour75";
-  const border = theme.border ?? "colour238";
-  const bg = theme.bg ?? "colour235";
-  const fg = theme.fg ?? "colour248";
-
-  return [
-    ["set-option", "-t", session, "pane-border-status", "top"],
-    ["set-option", "-t", session, "pane-border-format", " #{?pane_active,#[bold]▸,·} #T "],
-    ["set-option", "-t", session, "pane-border-style", `fg=${border}`],
-    ["set-option", "-t", session, "pane-active-border-style", `fg=${accent}`],
-    ["set-option", "-t", session, "status-style", `bg=${bg},fg=${fg}`],
-    [
-      "set-option",
-      "-t",
-      session,
-      "status-left",
-      `#[fg=colour0,bg=${accent},bold]  ${session.toUpperCase()} IDE #[default] `,
-    ],
-    ["set-option", "-t", session, "status-left-length", "30"],
-    [
-      "set-option",
-      "-t",
-      session,
-      "status-right",
-      `#[fg=colour243]%H:%M #[fg=${accent}]│ #[fg=${fg}]%b %d `,
-    ],
-    ["set-option", "-t", session, "status-justify", "centre"],
-    ["set-option", "-t", session, "window-status-current-format", `#[fg=${accent},bold]●`],
-    ["set-option", "-t", session, "window-status-format", `#[fg=${border}]○`],
-  ];
+  return { focusPane, paneActions };
 }

package/src/lib/output.js

@@ -1,23 +1,4 @@
-export function output(data, { json } = {}) {
-  if (json) {
-    console.log(JSON.stringify(data, null, 2));
-  } else if (typeof data === "string") {
-    console.log(data);
-  } else {
-    console.log(data);
-  }
-}
-
-export class CommandError extends Error {
-  constructor(message, { code, exitCode = 1, details, json = false } = {}) {
-    super(message);
-    this.name = "CommandError";
-    this.code = code;
-    this.exitCode = exitCode;
-    this.details = details;
-    this.json = json;
-  }
-}
+import { IdeError } from "./errors.js";
 
 export function printLayout(config) {
   const INNER = 40;
@@ -37,51 +18,49 @@ export function printLayout(config) {
 
     // Top border or mid divider
     if (r === 0) {
-      let top = "  ┌";
+      let top = "  \u250c";
       for (let i = 0; i < count; i++) {
-        top += "─".repeat(widths[i]);
-        top += i < count - 1 ? "┬" : "┐";
+        top += "\u2500".repeat(widths[i]);
+        top += i < count - 1 ? "\u252c" : "\u2510";
       }
       console.log(top);
     } else {
-      console.log("  ├" + "─".repeat(INNER + count - 1) + "┤");
+      console.log("  \u251c" + "\u2500".repeat(INNER + count - 1) + "\u2524");
     }
 
     // Content line
     const sizeLabel = rows[r].size ?? "";
-    let line = "  │";
+    let line = "  \u2502";
     for (let i = 0; i < count; i++) {
       const title = panes[i]?.title ?? "";
       const w = widths[i];
       const pad = Math.max(0, w - title.length);
       const left = Math.floor(pad / 2);
       const right = pad - left;
-      line += " ".repeat(left) + title + " ".repeat(right) + "│";
+      line += " ".repeat(left) + title + " ".repeat(right) + "\u2502";
     }
     if (sizeLabel) line += "  " + sizeLabel;
     console.log(line);
 
     // Bottom border (last row only)
     if (r === rows.length - 1) {
-      let bot = "  └";
+      let bot = "  \u2514";
       for (let i = 0; i < count; i++) {
-        bot += "─".repeat(widths[i]);
-        bot += i < count - 1 ? "┴" : "┘";
+        bot += "\u2500".repeat(widths[i]);
+        bot += i < count - 1 ? "\u2534" : "\u2518";
       }
       console.log(bot);
     }
   }
 }
 
-export function outputError(message, code, { json, exitCode = 1, details } = {}) {
-  throw new CommandError(message, { code, exitCode, details, json });
+export function outputError(message, code, { exitCode = 1 } = {}) {
+  throw new IdeError(message, { code, exitCode });
 }
 
-export function printCommandError(error, { json = error?.json ?? false } = {}) {
+export function printCommandError(error, { json = false } = {}) {
   if (json) {
-    const payload = { error: error.message, code: error.code };
-    if (error.details !== undefined) payload.details = error.details;
-    console.error(JSON.stringify(payload, null, 2));
+    console.error(JSON.stringify(error.toJSON(), null, 2));
   } else {
     console.error(error.message);
   }

package/src/lib/session-monitor.js

@@ -0,0 +1,179 @@
+import { execFileSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { resolve } from "node:path";
+
+const INTERVAL = 1000;
+const SPINNERS = /^[⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏⠂⠒⠢⠆⠐⠠⠄◐◓◑◒|/\\-] /;
+
+// --- Port detection (pure helpers) ---
+
+function getListeningPids() {
+  // Returns Set of PIDs that have a listening TCP port in range 1024-20000
+  try {
+    const raw = execFileSync("lsof", ["-nP", "-iTCP", "-sTCP:LISTEN", "-FpPn"], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const pids = new Set();
+    let currentPid = null;
+    for (const line of raw.split("\n")) {
+      if (line.startsWith("p")) {
+        currentPid = line.slice(1);
+      } else if (line.startsWith("n") && currentPid) {
+        const match = line.match(/:(\d+)$/);
+        if (match) {
+          const port = parseInt(match[1], 10);
+          if (port >= 1024 && port <= 20000) pids.add(currentPid);
+        }
+      }
+    }
+    return pids;
+  } catch {
+    return new Set();
+  }
+}
+
+function getProcessTree() {
+  // Returns Map<pid, ppid>
+  try {
+    const raw = execFileSync("ps", ["-axo", "pid=,ppid="], {
+      encoding: "utf-8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    const tree = new Map();
+    for (const line of raw.trim().split("\n")) {
+      const parts = line.trim().split(/\s+/);
+      if (parts.length === 2) tree.set(parts[0], parts[1]);
+    }
+    return tree;
+  } catch {
+    return new Map();
+  }
+}
+
+export function computePortPanes(panes, { listeners, tree } = {}) {
+  // Walk up from each listening PID to find which pane owns it
+  if (!listeners) listeners = getListeningPids();
+  if (!tree) tree = getProcessTree();
+  if (listeners.size === 0) return new Set();
+
+  const panePids = new Map(panes.map((p) => [p.pid, p.id]));
+  const result = new Set();
+
+  for (const listenerPid of listeners) {
+    let pid = listenerPid;
+    while (pid && pid !== "0") {
+      if (panePids.has(pid)) {
+        result.add(panePids.get(pid));
+        break;
+      }
+      pid = tree.get(pid);
+    }
+  }
+  return result;
+}
+
+// --- Agent detection ---
+
+export function computeAgentStates(panes) {
+  // Returns Map<paneId, "busy" | "idle" | null>
+  const states = new Map();
+  for (const pane of panes) {
+    const cmd = (pane.cmd ?? "").toLowerCase();
+    if (!cmd.includes("claude") && !cmd.includes("codex")) {
+      states.set(pane.id, null);
+      continue;
+    }
+    states.set(pane.id, SPINNERS.test(pane.title ?? "") ? "busy" : "idle");
+  }
+  return states;
+}
+
+// --- Main loop (only runs when executed directly) ---
+
+const isMainModule = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+
+if (isMainModule) {
+  const session = process.argv[2];
+  if (!session) process.exit(1);
+
+  function tmux(...args) {
+    return execFileSync("tmux", args, { encoding: "utf-8" }).trim();
+  }
+
+  function tmuxSilent(...args) {
+    try {
+      return tmux(...args);
+    } catch {
+      return "";
+    }
+  }
+
+  function sessionExists() {
+    try {
+      tmux("has-session", "-t", session);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  function hasClients() {
+    return tmuxSilent("list-clients").length > 0;
+  }
+
+  function listPanes() {
+    const raw = tmuxSilent(
+      "list-panes",
+      "-t",
+      session,
+      "-F",
+      "#{pane_id}\t#{pane_pid}\t#{pane_current_command}\t#{pane_title}",
+    );
+    if (!raw) return [];
+    return raw.split("\n").map((line) => {
+      const [id, pid, cmd, title] = line.split("\t");
+      return { id, pid, cmd, title };
+    });
+  }
+
+  let lastState = "";
+
+  function tick() {
+    if (!sessionExists()) process.exit(0);
+    if (!hasClients()) return; // skip when nobody is watching
+
+    const panes = listPanes();
+    if (panes.length === 0) return;
+
+    const portPanes = computePortPanes(panes);
+    const agentStates = computeAgentStates(panes);
+
+    // Build state fingerprint for change detection
+    const stateKey = panes
+      .map((p) => {
+        const port = portPanes.has(p.id) ? "1" : "0";
+        const agent = agentStates.get(p.id) ?? "-";
+        return `${p.id}:${port}:${agent}`;
+      })
+      .join("|");
+
+    if (stateKey === lastState) return;
+
+    // Apply changes
+    for (const pane of panes) {
+      const hasPort = portPanes.has(pane.id) ? "1" : "0";
+      const agent = agentStates.get(pane.id);
+
+      tmuxSilent("set-option", "-pqt", pane.id, "@has_port", hasPort);
+      tmuxSilent("set-option", "-pqt", pane.id, "@agent_busy", agent === "busy" ? "1" : "0");
+      tmuxSilent("set-option", "-pqt", pane.id, "@agent_idle", agent === "idle" ? "1" : "0");
+    }
+
+    tmuxSilent("refresh-client", "-S");
+    lastState = stateKey;
+  }
+
+  setInterval(tick, INTERVAL);
+  tick(); // run immediately
+}

package/src/lib/session-options.js

@@ -0,0 +1,95 @@
+/**
+ * Composable builders for tmux session configuration.
+ * Each returns an array of tmux command arrays.
+ */
+
+export function buildSessionOptions(session, { theme = {} } = {}) {
+  return [
+    ...themeOptions(session, theme),
+    ...borderOptions(session, theme),
+    ...behaviorOptions(session),
+    ...statusBarOptions(session, theme),
+    ...keyBindings(),
+  ];
+}
+
+export function themeOptions(session, theme) {
+  const accent = theme.accent ?? "colour75";
+  const border = theme.border ?? "colour238";
+  const bg = theme.bg ?? "colour235";
+  const fg = theme.fg ?? "colour248";
+
+  return [
+    ["set-option", "-t", session, "status-style", `bg=${bg},fg=${fg}`],
+    ["set-option", "-t", session, "pane-border-style", `fg=${border}`],
+    ["set-option", "-t", session, "pane-active-border-style", `fg=${accent}`],
+  ];
+}
+
+export function borderOptions(session, theme) {
+  const accent = theme.accent ?? "colour75";
+  const border = theme.border ?? "colour238";
+  const fg = theme.fg ?? "colour248";
+
+  return [
+    ["set-option", "-t", session, "pane-border-status", "top"],
+    [
+      "set-option",
+      "-t",
+      session,
+      "pane-border-format",
+      ` #{?pane_active,#[fg=${accent}#,bold]▸ #T  #[fg=${fg}]#{pane_current_path},#[fg=${border}]· #T  #{pane_current_path}} `,
+    ],
+  ];
+}
+
+export function behaviorOptions(session) {
+  return [
+    ["set-option", "-t", session, "mouse", "on"],
+    ["set-option", "-t", session, "escape-time", "0"],
+    ["set-option", "-t", session, "status-interval", "1"],
+  ];
+}
+
+export function statusBarOptions(session, theme) {
+  const accent = theme.accent ?? "colour75";
+  const border = theme.border ?? "colour238";
+  const fg = theme.fg ?? "colour248";
+
+  // Pane tab components — each is a self-contained piece
+  const agentIndicator = [
+    `#{?#{==:#{@agent_busy},1},#[fg=${accent}]⏺ ,`,
+    `#{?#{==:#{@agent_idle},1},#[fg=${border}]● ,}}`,
+  ].join("");
+  const portIndicator = `#{?#{==:#{@has_port},1},#[fg=green]⏺ ,}`;
+  const paneStyle = `#{?pane_active,#[fg=${accent}],#[fg=${border}]}`;
+  const paneTab = `${agentIndicator}${portIndicator}${paneStyle}#[range=pane|#{pane_id}] #T #[norange]#[default]`;
+  const separator = `#{?loop_last_flag,,#[fg=${border}]│}`;
+
+  return [
+    [
+      "set-option",
+      "-t",
+      session,
+      "status-left",
+      `#[fg=colour0,bg=${accent},bold]  ${session.toUpperCase()} IDE #[default] `,
+    ],
+    ["set-option", "-t", session, "status-left-length", "30"],
+    [
+      "set-option",
+      "-t",
+      session,
+      "status-right",
+      `#[fg=colour243]%H:%M #[fg=${accent}]│ #[fg=${fg}]%b %d `,
+    ],
+    ["set-option", "-t", session, "status-justify", "centre"],
+    ["set-option", "-t", session, "window-status-current-format", `#[fg=${accent},bold]●`],
+    ["set-option", "-t", session, "window-status-format", `#[fg=${border}]○`],
+    ["set-option", "-t", session, "status", "2"],
+    ["set-option", "-t", session, "status-format[1]", `  #{P:${paneTab}${separator}}`],
+  ];
+}
+
+export function keyBindings() {
+  return [["bind-key", "-n", "MouseDown1StatusDefault", "select-pane", "-t", "="]];
+}

package/src/lib/tmux.js

@@ -1,4 +1,7 @@
-import { execFileSync } from "node:child_process";
+import { execFileSync, spawn } from "node:child_process";
+import { TmuxError } from "./errors.js";
+
+const DEBUG = process.env.TMUX_IDE_DEBUG === "1";
 
 const SESSION_NOT_FOUND_PATTERNS = ["can't find session", "can't find window", "unknown target"];
 
@@ -9,14 +12,7 @@ const TMUX_UNAVAILABLE_PATTERNS = [
   "connection refused",
 ];
 
-export class TmuxError extends Error {
-  constructor(message, code, cause) {
-    super(message);
-    this.name = "TmuxError";
-    this.code = code;
-    this.cause = cause;
-  }
-}
+export { TmuxError };
 
 export function getSessionState(session) {
   try {
@@ -44,7 +40,10 @@ export function hasSession(session) {
     runTmux(["has-session", "-t", session]);
     return true;
   } catch (error) {
-    if (error instanceof TmuxError && error.code === "SESSION_NOT_FOUND") {
+    if (
+      error instanceof TmuxError &&
+      (error.code === "SESSION_NOT_FOUND" || error.code === "TMUX_UNAVAILABLE")
+    ) {
       return false;
     }
     throw error;
@@ -161,7 +160,47 @@ export function runSessionCommand(args) {
   runTmux(args, { stdio: "inherit" });
 }
 
+export function startSessionMonitor(session, monitorScript) {
+  const child = spawn("node", [monitorScript, session], {
+    detached: true,
+    stdio: "ignore",
+  });
+  child.unref();
+  // Store PID as tmux session variable for later cleanup
+  runTmux(["set-option", "-t", session, "@monitor_pid", String(child.pid)]);
+}
+
+export function stopSessionMonitor(session) {
+  try {
+    const pid = runTmux(["show-option", "-gqvt", session, "@monitor_pid"], {
+      encoding: "utf-8",
+    }).trim();
+    if (pid) process.kill(parseInt(pid, 10));
+  } catch {
+    /* session or process already gone */
+  }
+}
+
+export function getSessionVariable(session, name) {
+  try {
+    const raw = runTmux(["show-option", "-gqvt", session, name], {
+      encoding: "utf-8",
+    });
+    return raw.trim() || null;
+  } catch {
+    return null;
+  }
+}
+
+export function setSessionVariable(session, name, value) {
+  runTmux(["set-option", "-t", session, name, value]);
+}
+
 function runTmux(args, options = {}) {
+  if (DEBUG || globalThis.__tmuxIdeVerbose) {
+    console.error(`  [tmux] ${args.join(" ")}`);
+  }
+
   const execOptions = {
     stdio: ["ignore", "pipe", "pipe"],
     ...options,
@@ -178,18 +217,16 @@ function classifyTmuxError(error) {
   const detail = getErrorDetail(error).toLowerCase();
 
   if (SESSION_NOT_FOUND_PATTERNS.some((pattern) => detail.includes(pattern))) {
-    return new TmuxError("tmux session was not found", "SESSION_NOT_FOUND", error);
+    return new TmuxError("tmux session was not found", "SESSION_NOT_FOUND", { cause: error });
   }
 
   if (TMUX_UNAVAILABLE_PATTERNS.some((pattern) => detail.includes(pattern))) {
-    return new TmuxError(
-      "tmux is unavailable or its socket is inaccessible",
-      "TMUX_UNAVAILABLE",
-      error,
-    );
+    return new TmuxError("tmux is unavailable or its socket is inaccessible", "TMUX_UNAVAILABLE", {
+      cause: error,
+    });
   }
 
-  return new TmuxError("tmux command failed", "TMUX_ERROR", error);
+  return new TmuxError("tmux command failed", "TMUX_ERROR", { cause: error });
 }
 
 function getErrorDetail(error) {

package/src/lib/yaml-io.js

@@ -19,8 +19,8 @@ export function writeConfig(dir, config) {
 export function getSessionName(dir) {
   try {
     const { config } = readConfig(dir);
-    return config.name ?? basename(dir);
+    return { name: config.name ?? basename(dir), source: config.name ? "config" : "fallback" };
   } catch {
-    return basename(dir);
+    return { name: basename(dir), source: "fallback" };
   }
 }

package/src/restart.js

@@ -5,7 +5,7 @@ import { killSession } from "./lib/tmux.js";
 
 export async function restart(targetDir, { json, attach } = {}) {
   const dir = resolve(targetDir ?? ".");
-  const session = getSessionName(dir);
+  const { name: session } = getSessionName(dir);
   const result = killSession(session);
 
   if (result.stopped) {

package/src/status.js

@@ -5,7 +5,7 @@ import { getSessionState, listPanes } from "./lib/tmux.js";
 
 export async function status(targetDir, { json } = {}) {
   const dir = resolve(targetDir ?? ".");
-  const session = getSessionName(dir);
+  const { name: session } = getSessionName(dir);
   const configExists = existsSync(resolve(dir, "ide.yml"));
 
   const state = getSessionState(session);

package/src/stop.js

@@ -1,11 +1,15 @@
 import { resolve } from "node:path";
 import { getSessionName } from "./lib/yaml-io.js";
 import { outputError } from "./lib/output.js";
-import { killSession } from "./lib/tmux.js";
+import { killSession, stopSessionMonitor } from "./lib/tmux.js";
 
 export async function stop(targetDir, { json } = {}) {
   const dir = resolve(targetDir ?? ".");
-  const session = getSessionName(dir);
+  const { name: session } = getSessionName(dir);
+
+  // Stop the session monitor before killing the session
+  stopSessionMonitor(session);
+
   const result = killSession(session);
 
   if (result.stopped) {
@@ -17,8 +21,5 @@ export async function stop(targetDir, { json } = {}) {
     return;
   }
 
-  outputError(`No active session "${session}" found`, "NOT_RUNNING", {
-    json,
-    exitCode: 1,
-  });
+  outputError(`No active session "${session}" found`, "NOT_RUNNING");
 }

package/src/validate.js

@@ -130,7 +130,7 @@ export async function validate(targetDir, { json } = {}) {
   try {
     ({ config } = readConfig(dir));
   } catch (e) {
-    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR", { json });
+    outputError(`Cannot read ide.yml: ${e.message}`, "READ_ERROR");
     return;
   }