tmux-ide 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 wavyrai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,95 @@
+# tmux-ide
+
+Turn any project into a tmux-powered terminal IDE with a simple `ide.yml` config file.
+
+## Install
+
+```bash
+npm install -g tmux-ide
+```
+
+## Quick Start
+
+```bash
+tmux-ide init         # Scaffold ide.yml (auto-detects your stack)
+tmux-ide              # Launch the IDE
+tmux-ide stop         # Kill the session
+tmux-ide restart      # Stop and relaunch
+tmux-ide attach       # Reattach to a running session
+```
+
+## ide.yml Format
+
+```yaml
+name: project-name          # tmux session name
+
+before: pnpm install        # optional pre-launch hook
+
+rows:
+  - size: 70%               # row height percentage
+    panes:
+      - title: Editor        # pane border label
+        command: vim          # command to run (optional)
+        size: 60%            # pane width percentage (optional)
+        dir: apps/web        # per-pane working directory (optional)
+        focus: true          # initial focus (optional)
+        env:                 # environment variables (optional)
+          PORT: 3000
+      - title: Shell
+
+  - panes:
+      - title: Dev Server
+        command: pnpm dev
+      - title: Tests
+        command: pnpm test
+
+theme:                       # optional color overrides
+  accent: colour75
+  border: colour238
+  bg: colour235
+  fg: colour248
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `tmux-ide` | Launch IDE from `ide.yml` |
+| `tmux-ide <path>` | Launch from a specific directory |
+| `tmux-ide init [--template <name>]` | Scaffold a new `ide.yml` |
+| `tmux-ide stop` | Kill the current IDE session |
+| `tmux-ide restart` | Stop and relaunch the IDE session |
+| `tmux-ide attach` | Reattach to a running session |
+| `tmux-ide ls` | List all tmux sessions |
+| `tmux-ide status` | Show session status |
+| `tmux-ide doctor` | Check system requirements |
+| `tmux-ide validate` | Validate `ide.yml` |
+| `tmux-ide detect` | Detect project stack |
+| `tmux-ide detect --write` | Detect and write `ide.yml` |
+| `tmux-ide config` | Dump config as JSON |
+| `tmux-ide config set <path> <value>` | Set a config value |
+| `tmux-ide config add-pane --row <N>` | Add a pane to a row |
+| `tmux-ide config remove-pane --row <N> --pane <M>` | Remove a pane |
+| `tmux-ide config add-row [--size <percent>]` | Add a new row |
+
+All commands support `--json` for structured output.
+
+## Templates
+
+Use `tmux-ide init --template <name>` with one of:
+
+- `default` — General-purpose layout
+- `nextjs` — Next.js development
+- `convex` — Convex + Next.js
+- `vite` — Vite project
+- `python` — Python development
+- `go` — Go development
+
+## Requirements
+
+- **tmux** >= 3.0
+- **Node.js** >= 18
+
+## License
+
+[MIT](LICENSE)

package/bin/cli.js

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { createRequire } from "node:module";
+import { launch } from "../src/launch.js";
+import { init } from "../src/init.js";
+import { stop } from "../src/stop.js";
+import { attach } from "../src/attach.js";
+import { ls } from "../src/ls.js";
+import { doctor } from "../src/doctor.js";
+import { status } from "../src/status.js";
+import { validate } from "../src/validate.js";
+import { detect } from "../src/detect.js";
+import { config } from "../src/config.js";
+import { restart } from "../src/restart.js";
+
+const { positionals, values } = parseArgs({
+  allowPositionals: true,
+  strict: false,
+  options: {
+    json: { type: "boolean" },
+    row: { type: "string" },
+    pane: { type: "string" },
+    title: { type: "string" },
+    command: { type: "string" },
+    size: { type: "string" },
+    write: { type: "boolean" },
+    template: { type: "string" },
+    name: { type: "string" },
+    help: { type: "boolean", short: "h" },
+    version: { type: "boolean", short: "v" },
+  },
+});
+
+// --version / -v
+if (values.version) {
+  const require = createRequire(import.meta.url);
+  const pkg = require("../package.json");
+  console.log(`tmux-ide v${pkg.version}`);
+  process.exit(0);
+}
+
+const command = positionals[0] ?? "start";
+const json = values.json ?? false;
+
+const noColor = "NO_COLOR" in process.env;
+const bold = (s) => (noColor ? s : `\x1b[1m${s}\x1b[22m`);
+const cyan = (s) => (noColor ? s : `\x1b[36m${s}\x1b[39m`);
+const dim = (s) => (noColor ? s : `\x1b[2m${s}\x1b[22m`);
+
+function printHelp() {
+  console.log(`${bold("tmux-ide")} — Terminal IDE powered by tmux
+
+${bold("Usage:")}
+  ${cyan("tmux-ide")}                    ${dim("Launch IDE from ide.yml")}
+  ${cyan("tmux-ide <path>")}             ${dim("Launch from a specific directory")}
+  ${cyan("tmux-ide init")} [--template]  ${dim("Scaffold a new ide.yml (auto-detects stack)")}
+  ${cyan("tmux-ide stop")}               ${dim("Kill the current IDE session")}
+  ${cyan("tmux-ide restart")}            ${dim("Stop and relaunch the IDE session")}
+  ${cyan("tmux-ide attach")}             ${dim("Reattach to a running session")}
+  ${cyan("tmux-ide ls")}                 ${dim("List all tmux sessions")}
+  ${cyan("tmux-ide status")} [--json]    ${dim("Show session status")}
+  ${cyan("tmux-ide doctor")}             ${dim("Check system requirements")}
+  ${cyan("tmux-ide validate")} [--json]  ${dim("Validate ide.yml")}
+  ${cyan("tmux-ide detect")} [--json]    ${dim("Detect project stack")}
+  ${cyan("tmux-ide detect --write")}     ${dim("Detect and write ide.yml")}
+  ${cyan("tmux-ide config")} [--json]    ${dim("Dump config as JSON")}
+  ${cyan("tmux-ide config set")} <path> <value>
+  ${cyan("tmux-ide config add-pane")} --row <N> --title <T> [--command <C>]
+  ${cyan("tmux-ide config remove-pane")} --row <N> --pane <M>
+  ${cyan("tmux-ide config add-row")} [--size <percent>]
+  ${cyan("tmux-ide config enable-team")} [--name <N>]   ${dim("Enable agent teams")}
+  ${cyan("tmux-ide config disable-team")}               ${dim("Disable agent teams")}
+
+${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("-v, --version")}               ${dim("Show version number")}`);
+}
+
+switch (command) {
+  case "start":
+    await launch(positionals[1]);
+    break;
+
+  case "init":
+    await init({ template: values.template, json });
+    break;
+
+  case "stop":
+    await stop(positionals[1], { json });
+    break;
+
+  case "attach":
+    await attach(positionals[1], { json });
+    break;
+
+  case "restart":
+    await restart(positionals[1]);
+    break;
+
+  case "ls":
+    await ls({ json });
+    break;
+
+  case "doctor":
+    await doctor({ json });
+    break;
+
+  case "status":
+    await status(positionals[1], { json });
+    break;
+
+  case "validate":
+    await validate(positionals[1], { json });
+    break;
+
+  case "detect":
+    await detect(positionals[1], { json, write: values.write });
+    break;
+
+  case "config": {
+    const sub = positionals[1]; // set, add-pane, remove-pane, add-row, or undefined (dump)
+    let action = "dump";
+    let configArgs = [];
+
+    if (sub === "set") {
+      action = "set";
+      configArgs = positionals.slice(2);
+    } else if (sub === "add-pane") {
+      action = "add-pane";
+      // Pass named flags as args array
+      configArgs = [];
+      if (values.row !== undefined) configArgs.push("--row", values.row);
+      if (values.title !== undefined) configArgs.push("--title", values.title);
+      if (values.command !== undefined) configArgs.push("--command", values.command);
+      if (values.size !== undefined) configArgs.push("--size", values.size);
+    } else if (sub === "remove-pane") {
+      action = "remove-pane";
+      configArgs = [];
+      if (values.row !== undefined) configArgs.push("--row", values.row);
+      if (values.pane !== undefined) configArgs.push("--pane", values.pane);
+    } else if (sub === "add-row") {
+      action = "add-row";
+      configArgs = [];
+      if (values.size !== undefined) configArgs.push("--size", values.size);
+    } else if (sub === "enable-team") {
+      action = "enable-team";
+      configArgs = [];
+      if (values.name !== undefined) configArgs.push("--name", values.name);
+    } else if (sub === "disable-team") {
+      action = "disable-team";
+      configArgs = [];
+    }
+
+    await config(null, { json, action, args: configArgs });
+    break;
+  }
+
+  case "help":
+    printHelp();
+    break;
+
+  default:
+    console.error(`Unknown command: ${command}`);
+    console.error('Run "tmux-ide help" for usage.');
+    process.exit(1);
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "tmux-ide",
+  "version": "1.0.0",
+  "description": "Turn any project into a tmux-powered terminal IDE with a simple ide.yml",
+  "type": "module",
+  "bin": {
+    "tmux-ide": "bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    "skill",
+    "templates"
+  ],
+  "scripts": {
+    "dev": "node bin/cli.js",
+    "test": "node --test 'src/**/*.test.js'",
+    "postinstall": "node scripts/postinstall.js",
+    "docs": "cd docs && pnpm dev"
+  },
+  "keywords": [
+    "tmux",
+    "ide",
+    "terminal",
+    "workspace",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wavyrai/tmux-ide.git"
+  },
+  "homepage": "https://github.com/wavyrai/tmux-ide#readme",
+  "bugs": {
+    "url": "https://github.com/wavyrai/tmux-ide/issues"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  }
+}

package/scripts/postinstall.js

@@ -0,0 +1,13 @@
+import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+
+const claudeDir = resolve(homedir(), ".claude");
+if (existsSync(claudeDir)) {
+  const skillDir = resolve(claudeDir, "skills", "tmux-ide");
+  mkdirSync(skillDir, { recursive: true });
+  const src = resolve(dirname(import.meta.dirname), "skill", "SKILL.md");
+  if (existsSync(src)) {
+    copyFileSync(src, resolve(skillDir, "SKILL.md"));
+  }
+}

package/skill/SKILL.md

@@ -0,0 +1,238 @@
+# tmux-ide — Claude Code Skill
+
+tmux-ide turns any project into a tmux-powered terminal IDE using a simple `ide.yml` config file.
+
+## When to use
+
+- User mentions multi-pane, tmux, terminal IDE, or dev environment
+- User wants to set up a development workspace
+- User asks about running multiple terminals/tools side-by-side
+- User wants to coordinate multiple Claude Code instances as a team
+- User mentions agent teams, team lead, or multi-agent workflows
+
+## Setup workflow
+
+1. Check if `ide.yml` exists: `tmux-ide status --json`
+2. Auto-detect the project: `tmux-ide detect --json`
+3. **Present 2-3 layout options using ASCII diagrams** before writing config. Example:
+
+   **Option A — Dual Claude + Dev (recommended)**
+   ```
+   ┌─────────────────┬─────────────────┐
+   │                 │                 │
+   │    Claude 1     │    Claude 2     │  70%
+   │                 │                 │
+   ├────────┬────────┴────────┬────────┤
+   │Dev Srv │  Tests  │ Shell │        │  30%
+   └────────┴─────────┴───────┘────────┘
+   ```
+
+   **Option B — Triple Claude**
+   ```
+   ┌───────────┬───────────┬───────────┐
+   │           │           │           │
+   │ Claude 1  │ Claude 2  │ Claude 3  │  70%
+   │           │           │           │
+   ├───────────┴─────┬─────┴───────────┤
+   │    Dev Server    │     Shell       │  30%
+   └─────────────────┴─────────────────┘
+   ```
+
+   **Option C — Single Claude + wide dev**
+   ```
+   ┌─────────────────────────────────────┐
+   │             Claude                  │  60%
+   ├──────────┬──────────┬──────────────┤
+   │ Dev Srv  │  Tests   │    Shell     │  40%
+   └──────────┴──────────┴──────────────┘
+   ```
+
+   Adapt pane names/commands to the detected stack.
+
+4. Once the user picks, write the config:
+   - Quick: `tmux-ide detect --write` then modify
+   - Or build custom with `tmux-ide config` subcommands
+
+## Agent Teams workflow
+
+Agent teams coordinate multiple Claude Code instances where a lead delegates tasks to teammates. Each gets its own tmux pane.
+
+### When to suggest agent teams
+
+- User wants coordinated multi-agent development
+- User mentions team lead, teammates, or task delegation
+- User wants parallel work with inter-agent communication
+- User's task benefits from specialized roles (e.g., frontend + backend + review)
+
+### Prerequisites
+
+Agent teams require `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`. tmux-ide sets this automatically 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:**
+   ```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:**
+   ```bash
+   tmux-ide validate --json
+   tmux-ide
+   ```
+
+### Present team layout options
+
+When suggesting agent team layouts, show the roles:
+
+**Option A — Lead + 2 Teammates**
+```
+┌───────────┬───────────┬───────────┐
+│           │           │           │
+│   Lead    │Teammate 1 │Teammate 2 │  70%
+│ (claude)  │ (claude)  │ (claude)  │
+├───────────┴─────┬─────┴───────────┤
+│   Dev Server    │     Shell       │  30%
+└─────────────────┴─────────────────┘
+```
+
+**Option B — Lead + 3 Specialized Teammates**
+```
+┌────────┬────────┬────────┬────────┐
+│        │Frontend│Backend │ Review │
+│  Lead  │ Agent  │ Agent  │ Agent  │  70%
+│        │        │        │        │
+├────────┴────────┴──┬─────┴────────┤
+│    Dev Server      │    Shell     │  30%
+└────────────────────┴──────────────┘
+```
+
+### Team lead self-configuration
+
+When running as the team lead inside a tmux-ide session, you can reconfigure the team:
+
+```bash
+# Read current config
+tmux-ide config --json
+
+# Add a new teammate pane
+tmux-ide config add-pane --row 0 --title "Reviewer" --command "claude"
+tmux-ide config set rows.0.panes.3.role teammate
+tmux-ide config set rows.0.panes.3.task "Review all PRs and check for issues"
+
+# Or remove a teammate
+tmux-ide config remove-pane --row 0 --pane 2
+
+# Validate and restart to apply
+tmux-ide validate --json
+tmux-ide restart
+```
+
+### Disable teams
+
+```bash
+tmux-ide config disable-team
+```
+
+Removes the `team` config and all `role`/`task` fields from panes.
+
+## Programmatic CLI
+
+All commands support `--json` for structured output.
+
+### Read commands
+
+```bash
+tmux-ide status --json      # Session status
+tmux-ide validate --json    # Validate config
+tmux-ide detect --json      # Detect project stack
+tmux-ide config --json      # Dump config as JSON
+tmux-ide ls --json          # List sessions
+tmux-ide doctor --json      # System health check
+```
+
+### Write commands
+
+```bash
+tmux-ide detect --write                                    # Detect and write config
+tmux-ide config set name "my-app"                          # Set config value by dot path
+tmux-ide config set rows.0.size "70%"
+tmux-ide config add-pane --row 0 --title "Claude" --command "claude"
+tmux-ide config remove-pane --row 1 --pane 2
+tmux-ide config add-row --size "30%"
+tmux-ide config enable-team --name "my-team"               # Enable agent teams
+tmux-ide config disable-team                               # Disable agent teams
+```
+
+### Session commands
+
+```bash
+tmux-ide              # Launch (or re-launch) IDE
+tmux-ide stop         # Kill session
+tmux-ide restart      # Stop and relaunch
+tmux-ide attach       # Reattach
+tmux-ide init         # Scaffold config
+```
+
+## Modification workflow
+
+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`
+
+## Best practices
+
+- Always use `--json` for programmatic access
+- Always run `validate --json` after config mutations
+- Top row ~70% height for Claude panes
+- 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
+- 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
+  name: my-team
+rows:
+  - size: 70%
+    panes:
+      - title: Lead
+        command: claude
+        role: lead           # "lead" or "teammate"
+        focus: true
+      - title: Teammate 1
+        command: claude
+        role: teammate
+        task: "Work on frontend"  # initial task for teammate
+      - title: Teammate 2
+        command: claude
+        role: teammate
+        task: "Work on backend"
+  - panes:
+      - title: Dev Server
+        command: pnpm dev
+        dir: apps/web        # per-pane working directory
+        env:
+          PORT: 3000
+      - title: Shell
+theme:
+  accent: colour75
+  border: colour238
+```

package/src/attach.js

@@ -0,0 +1,22 @@
+import { resolve } from "node:path";
+import { execSync } from "node:child_process";
+import { getSessionName } from "./lib/yaml-io.js";
+import { outputError } from "./lib/output.js";
+
+export async function attach(targetDir, { json } = {}) {
+  const dir = resolve(targetDir ?? ".");
+  const session = getSessionName(dir);
+
+  try {
+    execSync(`tmux has-session -t "${session}"`, { stdio: "ignore" });
+  } catch {
+    outputError(
+      `Session "${session}" is not running. Start it with: tmux-ide`,
+      "NOT_RUNNING",
+      { json }
+    );
+    return;
+  }
+
+  execSync(`tmux attach -t "${session}"`, { stdio: "inherit" });
+}