tmux-ide 1.0.0 → 1.1.0

package/skill/SKILL.md

@@ -17,6 +17,7 @@ tmux-ide turns any project into a tmux-powered terminal IDE using a simple `ide.
 3. **Present 2-3 layout options using ASCII diagrams** before writing config. Example:
 
    **Option A — Dual Claude + Dev (recommended)**
+
    ```
    ┌─────────────────┬─────────────────┐
    │                 │                 │
@@ -28,6 +29,7 @@ tmux-ide turns any project into a tmux-powered terminal IDE using a simple `ide.
    ```
 
    **Option B — Triple Claude**
+
    ```
    ┌───────────┬───────────┬───────────┐
    │           │           │           │
@@ -39,6 +41,7 @@ tmux-ide turns any project into a tmux-powered terminal IDE using a simple `ide.
    ```
 
    **Option C — Single Claude + wide dev**
+
    ```
    ┌─────────────────────────────────────┐
    │             Claude                  │  60%
@@ -55,7 +58,7 @@ tmux-ide turns any project into a tmux-powered terminal IDE using a simple `ide.
 
 ## Agent Teams workflow
 
-Agent teams coordinate multiple Claude Code instances where a lead delegates tasks to teammates. Each gets its own tmux pane.
+Agent teams coordinate multiple Claude Code instances where a lead delegates tasks to teammates. Each gets its own tmux pane, and tmux-ide prepares that layout before Claude starts the actual team workflow.
 
 ### When to suggest agent teams
 
@@ -66,38 +69,50 @@ Agent teams coordinate multiple Claude Code instances where a lead delegates tas
 
 ### Prerequisites
 
-Agent teams require `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. tmux-ide sets this automatically when `team` is configured in `ide.yml`.
+Agent teams require `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. The tmux-ide install hook enables this in Claude Code settings, and tmux-ide also sets it automatically inside tmux sessions when `team` is configured in `ide.yml`.
 
 ### Setup from scratch
 
 1. **Scaffold with agent team template:**
+
    ```bash
    tmux-ide init --template agent-team
    ```
 
 2. **Or enable teams on an existing config:**
+
    ```bash
    tmux-ide config enable-team --name "my-team"
    ```
+
    This finds all `command: claude` panes and assigns the first as `lead`, the rest as `teammate`.
 
-3. **Assign initial tasks to teammates:**
+3. **Assign initial task hints to teammate panes:**
+
    ```bash
    tmux-ide config set rows.0.panes.1.task "Work on frontend components"
    tmux-ide config set rows.0.panes.2.task "Work on API routes"
    ```
 
-4. **Validate and launch:**
+4. **Validate and launch the layout:**
+
    ```bash
    tmux-ide validate --json
    tmux-ide
    ```
 
+5. **Inside the lead pane, ask Claude to form the team:**
+
+   ```text
+   Start an agent team named my-team. Use the Frontend pane for components and the Backend pane for API routes.
+   ```
+
 ### Present team layout options
 
-When suggesting agent team layouts, show the roles:
+When suggesting agent team layouts, show the roles and note that Claude will create the team after launch:
 
 **Option A — Lead + 2 Teammates**
+
 ```
 ┌───────────┬───────────┬───────────┐
 │           │           │           │
@@ -109,6 +124,7 @@ When suggesting agent team layouts, show the roles:
 ```
 
 **Option B — Lead + 3 Specialized Teammates**
+
 ```
 ┌────────┬────────┬────────┬────────┐
 │        │Frontend│Backend │ Review │
@@ -121,7 +137,7 @@ When suggesting agent team layouts, show the roles:
 
 ### Team lead self-configuration
 
-When running as the team lead inside a tmux-ide session, you can reconfigure the team:
+When running as the team lead inside a tmux-ide session, you can reconfigure the layout for the team:
 
 ```bash
 # Read current config
@@ -200,27 +216,27 @@ tmux-ide init         # Scaffold config
 - 2-3 Claude panes in the top row (or lead + 2 teammates for teams)
 - Dev servers + shell in the bottom row
 - Use `detect --json` first to understand the project stack
-- For agent teams: assign specific tasks to teammates for focused parallel work
+- For agent teams: assign specific tasks to teammate panes so your prompts stay focused
 - The team lead should have `focus: true` for easy access
 
 ## ide.yml format
 
 ```yaml
 name: project-name
-before: pnpm install        # optional pre-launch hook
-team:                        # optional agent team config
+before: pnpm install # optional pre-launch hook
+team: # optional agent team config
   name: my-team
 rows:
   - size: 70%
     panes:
       - title: Lead
         command: claude
-        role: lead           # "lead" or "teammate"
+        role: lead # optional layout metadata: "lead" or "teammate"
         focus: true
       - title: Teammate 1
         command: claude
         role: teammate
-        task: "Work on frontend"  # initial task for teammate
+        task: "Work on frontend" # suggested task text for your prompts
       - title: Teammate 2
         command: claude
         role: teammate
@@ -228,7 +244,7 @@ rows:
   - panes:
       - title: Dev Server
         command: pnpm dev
-        dir: apps/web        # per-pane working directory
+        dir: apps/web # per-pane working directory
         env:
           PORT: 3000
       - title: Shell

package/src/attach.js

@@ -1,22 +1,19 @@
 import { resolve } from "node:path";
-import { execSync } from "node:child_process";
 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 } = {}) {
   const dir = resolve(targetDir ?? ".");
   const session = getSessionName(dir);
+  const state = getSessionState(session);
 
-  try {
-    execSync(`tmux has-session -t "${session}"`, { stdio: "ignore" });
-  } catch {
-    outputError(
-      `Session "${session}" is not running. Start it with: tmux-ide`,
-      "NOT_RUNNING",
-      { json }
-    );
+  if (!state.running) {
+    outputError(`Session "${session}" is not running. Start it with: tmux-ide`, "NOT_RUNNING", {
+      json,
+    });
     return;
   }
 
-  execSync(`tmux attach -t "${session}"`, { stdio: "inherit" });
+  attachSession(session);
 }

package/src/config.js

@@ -1,6 +1,6 @@
 import { resolve } from "node:path";
 import { readConfig, writeConfig } from "./lib/yaml-io.js";
-import { getByPath, setByPath } from "./lib/dot-path.js";
+import { setByPath } from "./lib/dot-path.js";
 import { outputError } from "./lib/output.js";
 
 export async function config(targetDir, { json, action, args } = {}) {
@@ -58,6 +58,11 @@ function setConfig(dir, args, { json }) {
     return;
   }
 
+  if (!isConfigObject(cfg)) {
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    return;
+  }
+
   let value = rest.join(" ");
   // Try to parse as number or boolean
   if (value === "true") value = true;
@@ -77,7 +82,11 @@ function setConfig(dir, args, { json }) {
 function addPane(dir, args, { json }) {
   const { row, title, command, size } = parseNamedArgs(args);
   if (row === undefined) {
-    outputError("Usage: tmux-ide config add-pane --row <N> --title <T> [--command <C>] [--size <S>]", "USAGE", { json });
+    outputError(
+      "Usage: tmux-ide config add-pane --row <N> --title <T> [--command <C>] [--size <S>]",
+      "USAGE",
+      { json },
+    );
     return;
   }
 
@@ -89,12 +98,29 @@ function addPane(dir, args, { json }) {
     return;
   }
 
-  const rowIdx = parseInt(row);
-  if (!cfg.rows?.[rowIdx]) {
+  if (!Array.isArray(cfg?.rows)) {
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    return;
+  }
+
+  const rowIdx = parseIndex(row);
+  if (rowIdx == null) {
+    outputError(`Invalid row index "${row}"`, "USAGE", { json });
+    return;
+  }
+
+  if (!cfg.rows[rowIdx]) {
     outputError(`Row ${rowIdx} does not exist`, "INVALID_ROW", { json });
     return;
   }
 
+  if (!Array.isArray(cfg.rows[rowIdx].panes)) {
+    outputError(`Invalid ide.yml: row ${rowIdx} panes must be an array`, "INVALID_CONFIG", {
+      json,
+    });
+    return;
+  }
+
   const pane = {};
   if (title) pane.title = title;
   if (command) pane.command = command;
@@ -125,10 +151,26 @@ function removePane(dir, args, { json }) {
     return;
   }
 
-  const rowIdx = parseInt(row);
-  const paneIdx = parseInt(pane);
+  if (!Array.isArray(cfg?.rows)) {
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    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 });
+    return;
+  }
 
-  if (!cfg.rows?.[rowIdx]?.panes?.[paneIdx]) {
+  if (!Array.isArray(cfg.rows[rowIdx]?.panes)) {
+    outputError(`Invalid ide.yml: row ${rowIdx} panes must be an array`, "INVALID_CONFIG", {
+      json,
+    });
+    return;
+  }
+
+  if (!cfg.rows[rowIdx].panes[paneIdx]) {
     outputError(`Pane ${paneIdx} in row ${rowIdx} does not exist`, "INVALID_PANE", { json });
     return;
   }
@@ -154,6 +196,16 @@ function addRow(dir, args, { json }) {
     return;
   }
 
+  if (!isConfigObject(cfg)) {
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    return;
+  }
+
+  if (cfg.rows !== undefined && !Array.isArray(cfg.rows)) {
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    return;
+  }
+
   const row = { panes: [{ title: "Shell" }] };
   if (size) row.size = size;
 
@@ -180,6 +232,16 @@ function enableTeam(dir, args, { json }) {
     return;
   }
 
+  if (!isConfigObject(cfg)) {
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    return;
+  }
+
+  if (cfg.rows !== undefined && !Array.isArray(cfg.rows)) {
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    return;
+  }
+
   const teamName = name ?? cfg.name ?? "my-team";
   cfg.team = { name: teamName };
 
@@ -197,6 +259,11 @@ function enableTeam(dir, args, { json }) {
       }
     }
   }
+  if (!leadAssigned) {
+    delete cfg.team;
+    outputError("Cannot enable agent team: no Claude panes found", "INVALID_CONFIG", { json });
+    return;
+  }
 
   writeConfig(dir, cfg);
 
@@ -216,8 +283,19 @@ function disableTeam(dir, { json }) {
     return;
   }
 
+  if (!isConfigObject(cfg)) {
+    outputError("Invalid ide.yml: config root must be an object", "INVALID_CONFIG", { json });
+    return;
+  }
+
+  if (cfg.rows !== undefined && !Array.isArray(cfg.rows)) {
+    outputError("Invalid ide.yml: 'rows' must be an array", "INVALID_CONFIG", { json });
+    return;
+  }
+
   delete cfg.team;
   for (const row of cfg.rows ?? []) {
+    if (!Array.isArray(row?.panes)) continue;
     for (const pane of row.panes ?? []) {
       delete pane.role;
       delete pane.task;
@@ -257,3 +335,12 @@ function parseNamedArgs(args) {
   }
   return result;
 }
+
+function isConfigObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function parseIndex(value) {
+  if (!/^\d+$/.test(String(value))) return null;
+  return Number.parseInt(value, 10);
+}

package/src/detect.js

@@ -20,60 +20,98 @@ export function detectStack(dir) {
     frameworks: [],
     devCommand: null,
     language: null,
+    reasons: [],
   };
 
   // Detect package manager from lockfile
-  if (fileExists(dir, "pnpm-lock.yaml")) detected.packageManager = "pnpm";
-  else if (fileExists(dir, "bun.lockb") || fileExists(dir, "bun.lock")) detected.packageManager = "bun";
-  else if (fileExists(dir, "yarn.lock")) detected.packageManager = "yarn";
-  else if (fileExists(dir, "package-lock.json")) detected.packageManager = "npm";
+  if (fileExists(dir, "pnpm-lock.yaml")) {
+    detected.packageManager = "pnpm";
+    detected.reasons.push('Detected pnpm from "pnpm-lock.yaml".');
+  } else if (fileExists(dir, "bun.lockb") || fileExists(dir, "bun.lock")) {
+    detected.packageManager = "bun";
+    detected.reasons.push('Detected bun from "bun.lockb" or "bun.lock".');
+  } else if (fileExists(dir, "yarn.lock")) {
+    detected.packageManager = "yarn";
+    detected.reasons.push('Detected yarn from "yarn.lock".');
+  } else if (fileExists(dir, "package-lock.json")) {
+    detected.packageManager = "npm";
+    detected.reasons.push('Detected npm from "package-lock.json".');
+  }
 
   const pkg = readJson(dir, "package.json");
   if (pkg) {
     detected.language = "javascript";
+    detected.reasons.push('Detected JavaScript from "package.json".');
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
 
-    if (deps["next"]) detected.frameworks.push("next");
-    if (deps["convex"]) detected.frameworks.push("convex");
-    if (deps["vite"]) detected.frameworks.push("vite");
-    if (deps["remix"] || deps["@remix-run/node"]) detected.frameworks.push("remix");
-    if (deps["nuxt"]) detected.frameworks.push("nuxt");
-    if (deps["astro"]) detected.frameworks.push("astro");
-    if (deps["svelte"] || deps["@sveltejs/kit"]) detected.frameworks.push("svelte");
+    if (deps["next"]) pushFramework(detected, "next", 'Found dependency "next".');
+    if (deps["convex"]) pushFramework(detected, "convex", 'Found dependency "convex".');
+    if (deps["vite"]) pushFramework(detected, "vite", 'Found dependency "vite".');
+    if (deps["remix"] || deps["@remix-run/node"])
+      pushFramework(detected, "remix", "Found Remix dependency.");
+    if (deps["nuxt"]) pushFramework(detected, "nuxt", 'Found dependency "nuxt".');
+    if (deps["astro"]) pushFramework(detected, "astro", 'Found dependency "astro".');
+    if (deps["svelte"] || deps["@sveltejs/kit"])
+      pushFramework(detected, "svelte", "Found Svelte dependency.");
 
     // Detect dev command
     const pm = detected.packageManager ?? "npm";
     const run = pm === "npm" ? "npm run" : pm;
-    if (pkg.scripts?.dev) detected.devCommand = `${run} dev`;
-    else if (pkg.scripts?.start) detected.devCommand = `${run} start`;
+    if (pkg.scripts?.dev) {
+      detected.devCommand = `${run} dev`;
+      detected.reasons.push(
+        `Using dev command "${detected.devCommand}" from package.json scripts.`,
+      );
+    } else if (pkg.scripts?.start) {
+      detected.devCommand = `${run} start`;
+      detected.reasons.push(
+        `Using start command "${detected.devCommand}" from package.json scripts.`,
+      );
+    }
   }
 
   // Python
   if (fileExists(dir, "pyproject.toml") || fileExists(dir, "requirements.txt")) {
     detected.language = detected.language ?? "python";
+    detected.reasons.push('Detected Python from "pyproject.toml" or "requirements.txt".');
     try {
       const pyproject = readFileSync(resolve(dir, "pyproject.toml"), "utf-8");
-      if (pyproject.includes("fastapi")) detected.frameworks.push("fastapi");
-      else if (pyproject.includes("django")) detected.frameworks.push("django");
-      else if (pyproject.includes("flask")) detected.frameworks.push("flask");
-    } catch {}
+      if (pyproject.includes("fastapi"))
+        pushFramework(detected, "fastapi", 'Found "fastapi" in pyproject.toml.');
+      else if (pyproject.includes("django"))
+        pushFramework(detected, "django", 'Found "django" in pyproject.toml.');
+      else if (pyproject.includes("flask"))
+        pushFramework(detected, "flask", 'Found "flask" in pyproject.toml.');
+    } catch {
+      // Ignore missing or unreadable pyproject metadata.
+    }
   }
 
   // Rust
   if (fileExists(dir, "Cargo.toml")) {
     detected.language = detected.language ?? "rust";
-    detected.frameworks.push("cargo");
+    detected.reasons.push('Detected Rust from "Cargo.toml".');
+    pushFramework(detected, "cargo", 'Using Cargo workflow from "Cargo.toml".');
   }
 
   // Go
   if (fileExists(dir, "go.mod")) {
     detected.language = detected.language ?? "go";
-    detected.frameworks.push("go");
+    detected.reasons.push('Detected Go from "go.mod".');
+    pushFramework(detected, "go", 'Using Go workflow from "go.mod".');
   }
 
   // Docker
   if (fileExists(dir, "docker-compose.yml") || fileExists(dir, "docker-compose.yaml")) {
-    detected.frameworks.push("docker");
+    pushFramework(
+      detected,
+      "docker",
+      'Detected Docker from "docker-compose.yml" or "docker-compose.yaml".',
+    );
+  }
+
+  if (detected.reasons.length === 0) {
+    detected.reasons.push("No framework-specific signals found; using the generic layout.");
   }
 
   return detected;
@@ -156,10 +194,15 @@ export async function detect(targetDir, { json, write } = {}) {
     if (json) {
       console.log(JSON.stringify({ detected, suggestedConfig: suggested, written: true }, null, 2));
     } else {
-      const desc = detected.frameworks.length > 0
-        ? detected.frameworks.join(" + ")
-        : detected.language ?? "generic project";
+      const desc =
+        detected.frameworks.length > 0
+          ? detected.frameworks.join(" + ")
+          : (detected.language ?? "generic project");
       console.log(`Detected ${desc}. Created ide.yml.`);
+      console.log("\nWhy this layout:");
+      for (const reason of detected.reasons) {
+        console.log(`  - ${reason}`);
+      }
     }
     return;
   }
@@ -174,5 +217,16 @@ export async function detect(targetDir, { json, write } = {}) {
   if (detected.language) console.log(`  Language: ${detected.language}`);
   if (detected.frameworks.length) console.log(`  Frameworks: ${detected.frameworks.join(", ")}`);
   if (detected.devCommand) console.log(`  Dev command: ${detected.devCommand}`);
+  console.log("\nReasoning:");
+  for (const reason of detected.reasons) {
+    console.log(`  - ${reason}`);
+  }
   console.log("\nRun with --write to create ide.yml, or --json to see the suggested config.");
 }
+
+function pushFramework(detected, framework, reason) {
+  if (!detected.frameworks.includes(framework)) {
+    detected.frameworks.push(framework);
+  }
+  detected.reasons.push(reason);
+}

package/src/doctor.js

@@ -18,7 +18,7 @@ export async function doctor({ json } = {}) {
     check("tmux installed", () => {
       execSync("which tmux", { stdio: "ignore" });
       return "found";
-    })
+    }),
   );
 
   checks.push(
@@ -27,7 +27,7 @@ export async function doctor({ json } = {}) {
       const num = parseFloat(version.replace(/[^0-9.]/g, ""));
       if (num < 3.0) throw new Error(`${version} (need ≥ 3.0)`);
       return version;
-    })
+    }),
   );
 
   checks.push(
@@ -35,17 +35,22 @@ export async function doctor({ json } = {}) {
       const major = parseInt(process.versions.node.split(".")[0]);
       if (major < 18) throw new Error(`Node ${process.versions.node} (need ≥ 18)`);
       return `v${process.versions.node}`;
-    })
+    }),
   );
 
   checks.push(
     check("256-color terminal", () => {
       const term = process.env.TERM ?? "";
-      if (!term.includes("256color") && !term.includes("ghostty") && !term.includes("kitty") && term !== "tmux-256color") {
+      if (
+        !term.includes("256color") &&
+        !term.includes("ghostty") &&
+        !term.includes("kitty") &&
+        term !== "tmux-256color"
+      ) {
         throw new Error(`$TERM is "${term}"`);
       }
       return term;
-    })
+    }),
   );
 
   checks.push(
@@ -53,20 +58,25 @@ export async function doctor({ json } = {}) {
       const path = resolve(".", "ide.yml");
       if (!existsSync(path)) throw new Error("not found in current directory");
       return "found";
-    })
+    }),
   );
 
   checks.push(
-    check("Claude Code agent teams", () => {
-      if (process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS !== "1") {
-        throw new Error("not set (enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)");
-      }
-      return "enabled";
-    }, { optional: true })
+    check(
+      "Claude Code agent teams",
+      () => {
+        if (process.env.CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS !== "1") {
+          throw new Error("not set (enable with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1)");
+        }
+        return "enabled";
+      },
+      { optional: true },
+    ),
   );
 
+  const allPass = checks.every((c) => c.pass || c.optional);
+
   if (json) {
-    const allPass = checks.every((c) => c.pass || c.optional);
     console.log(JSON.stringify({ ok: allPass, checks }, null, 2));
     return;
   }
@@ -77,6 +87,5 @@ export async function doctor({ json } = {}) {
     console.log(`${color}${icon}\x1b[0m ${c.label} — ${c.detail}`);
   }
 
-  const allPass = checks.every((c) => c.pass);
   if (!allPass) process.exitCode = 1;
 }

package/src/init.js

@@ -1,32 +1,30 @@
-import { existsSync, readFileSync } from "node:fs";
-import { resolve, basename } from "node:path";
-import { writeFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve, basename, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
 import { detectStack, suggestConfig } from "./detect.js";
-import { printLayout } from "./lib/output.js";
+import { outputError, printLayout } from "./lib/output.js";
 
 export async function init({ template, json } = {}) {
   const dir = process.cwd();
   const configPath = resolve(dir, "ide.yml");
 
   if (existsSync(configPath)) {
-    if (json) {
-      console.error(JSON.stringify({ error: "ide.yml already exists", code: "EXISTS" }));
-    } else {
-      console.error("ide.yml already exists in this directory");
-    }
-    process.exit(1);
+    outputError("ide.yml already exists in this directory", "EXISTS", { json });
   }
 
   // If a specific template is requested, use it
   if (template) {
-    const templatePath = resolve(import.meta.dirname, "..", "templates", `${template}.yml`);
+    const templatePath = resolve(__dirname, "..", "templates", `${template}.yml`);
     if (!existsSync(templatePath)) {
-      if (json) {
-        console.error(JSON.stringify({ error: `Template "${template}" not found`, code: "NOT_FOUND" }));
-      } else {
-        console.error(`Template "${template}" not found. Available: default, nextjs, convex, vite, python, go, agent-team, agent-team-nextjs, agent-team-monorepo`);
-      }
-      process.exit(1);
+      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 },
+      );
     }
 
     let content = readFileSync(templatePath, "utf-8");
@@ -64,7 +62,7 @@ export async function init({ template, json } = {}) {
     }
   } else {
     // Fallback to default template
-    const templatePath = resolve(import.meta.dirname, "..", "templates", "default.yml");
+    const templatePath = resolve(__dirname, "..", "templates", "default.yml");
     let content = readFileSync(templatePath, "utf-8");
     content = content.replace(/^name: .+/m, `name: ${name}`);
     writeFileSync(configPath, content);