tmux-ide 1.0.0 → 1.2.0

package/README.md

@@ -1,5 +1,7 @@
 # tmux-ide
 
+[![CI](https://github.com/wavyrai/tmux-ide/actions/workflows/ci.yml/badge.svg)](https://github.com/wavyrai/tmux-ide/actions/workflows/ci.yml)
+
 Turn any project into a tmux-powered terminal IDE with a simple `ide.yml` config file.
 
 ## Install
@@ -8,6 +10,8 @@ Turn any project into a tmux-powered terminal IDE with a simple `ide.yml` config
 npm install -g tmux-ide
 ```
 
+Global install also registers the bundled Claude Code skill and enables `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` in `~/.claude/settings.json` if Claude Code is installed locally on the machine.
+
 ## Quick Start
 
 ```bash
@@ -16,24 +20,25 @@ 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
+tmux-ide inspect      # Inspect effective config + runtime state
 ```
 
 ## ide.yml Format
 
 ```yaml
-name: project-name          # tmux session name
+name: project-name # tmux session name
 
-before: pnpm install        # optional pre-launch hook
+before: pnpm install # optional pre-launch hook
 
 rows:
-  - size: 70%               # row height percentage
+  - 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)
+      - 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
 
@@ -43,7 +48,7 @@ rows:
       - title: Tests
         command: pnpm test
 
-theme:                       # optional color overrides
+theme: # optional color overrides
   accent: colour75
   border: colour238
   bg: colour235
@@ -52,38 +57,82 @@ theme:                       # optional color overrides
 
 ## 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 |
+| 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 inspect`                                 | Show effective config and runtime state |
+| `tmux-ide doctor`                                  | Check system requirements               |
+| `tmux-ide validate`                                | Validate `ide.yml`                      |
+| `tmux-ide detect`                                  | Detect project stack and explain why    |
+| `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                           |
+| `tmux-ide config enable-team --name <name>`        | Enable agent teams                      |
+| `tmux-ide config disable-team`                     | Disable agent teams                     |
 
 All commands support `--json` for structured output.
 
+`tmux-ide detect` now includes reasoning about the package manager, language, framework, and dev-command signals it used. `tmux-ide inspect` combines config validation, resolved layout details, and live tmux state in one command.
+
 ## 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
+- `default` - General-purpose layout
+- `nextjs` - Next.js development
+- `convex` - Convex + Next.js
+- `vite` - Vite project
+- `python` - Python development
+- `go` - Go development
+- `agent-team` - Agent team with lead + teammates
+- `agent-team-nextjs` - Agent team for Next.js
+- `agent-team-monorepo` - Agent team for monorepos
+
+## Contributor Workflow
+
+The repo now uses a pnpm workspace with a root CLI package and a separate docs app package:
+
+```bash
+pnpm install
+pnpm test
+pnpm docs:build
+pnpm check
+pnpm pack:check
+```
+
+`pnpm check` is the intended local pre-push command and matches the default release checklist. `npm publish` is still guarded by `prepublishOnly`, so publishing runs the same full check path automatically.
+
+## CI
+
+GitHub Actions validates:
+
+- the Node CLI test suite on Node 18, 20, and 22
+- the docs site production build
+- the package can be packed successfully with `npm pack --dry-run`
+
+That keeps the release surface small but catches the main regressions for a CLI-first package.
+
+## Open Source Project Files
+
+- [CONTRIBUTING.md](CONTRIBUTING.md) for local setup and contribution workflow
+- [RELEASE.md](RELEASE.md) for the publish checklist
+- [CHANGELOG.md](CHANGELOG.md) for release notes
+- [SECURITY.md](SECURITY.md) for vulnerability reporting
+
+Release note convention:
+
+- Keep the next version under an `Unreleased` heading in `CHANGELOG.md` until the tag is cut.
+- Move it to a dated release entry when the release is actually published.
 
 ## Requirements
 

package/bin/cli.js

@@ -8,10 +8,13 @@ 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 { inspect } from "../src/inspect.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";
+import { IdeError } from "../src/lib/errors.js";
+import { printCommandError } from "../src/lib/output.js";
 
 const { positionals, values } = parseArgs({
   allowPositionals: true,
@@ -26,11 +29,28 @@ 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" },
   },
 });
 
+const knownCommands = new Set([
+  "start",
+  "init",
+  "stop",
+  "attach",
+  "restart",
+  "ls",
+  "doctor",
+  "status",
+  "inspect",
+  "validate",
+  "detect",
+  "config",
+  "help",
+]);
+
 // --version / -v
 if (values.version) {
   const require = createRequire(import.meta.url);
@@ -39,7 +59,14 @@ if (values.version) {
   process.exit(0);
 }
 
-const command = positionals[0] ?? "start";
+if (values.verbose) {
+  globalThis.__tmuxIdeVerbose = true;
+}
+
+const firstPositional = positionals[0];
+const hasKnownCommand = firstPositional ? knownCommands.has(firstPositional) : false;
+const command = hasKnownCommand ? firstPositional : "start";
+const startTargetDir = hasKnownCommand ? positionals[1] : firstPositional;
 const json = values.json ?? false;
 
 const noColor = "NO_COLOR" in process.env;
@@ -47,6 +74,11 @@ 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`);
 
+if (values.help) {
+  printHelp();
+  process.exit(0);
+}
+
 function printHelp() {
   console.log(`${bold("tmux-ide")} — Terminal IDE powered by tmux
 
@@ -59,6 +91,7 @@ ${bold("Usage:")}
   ${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 inspect")} [--json]   ${dim("Show effective config and runtime state")}
   ${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")}
@@ -75,94 +108,109 @@ ${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")}`);
 }
 
-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 = [];
+try {
+  switch (command) {
+    case "start":
+      await launch(startTargetDir, { json });
+      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], { json });
+      break;
+
+    case "ls":
+      await ls({ json });
+      break;
+
+    case "doctor":
+      await doctor({ json });
+      break;
+
+    case "status":
+      await status(positionals[1], { json });
+      break;
+
+    case "inspect":
+      await inspect(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;
     }
 
-    await config(null, { json, action, args: configArgs });
-    break;
-  }
-
-  case "help":
-    printHelp();
-    break;
+    case "help":
+      printHelp();
+      break;
 
-  default:
-    console.error(`Unknown command: ${command}`);
-    console.error('Run "tmux-ide help" for usage.');
-    process.exit(1);
+    default:
+      throw new IdeError(`Unknown command: ${command}\nRun "tmux-ide help" for usage.`, {
+        code: "USAGE",
+        exitCode: 1,
+      });
+  }
+} catch (error) {
+  if (error instanceof IdeError) {
+    printCommandError(error, { json });
+  } else {
+    throw error;
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-ide",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Turn any project into a tmux-powered terminal IDE with a simple ide.yml",
   "type": "module",
   "bin": {
@@ -8,16 +8,29 @@
   },
   "files": [
     "bin",
-    "src",
+    "src/**/*.js",
+    "!src/**/*.test.js",
     "scripts",
     "skill",
     "templates"
   ],
   "scripts": {
     "dev": "node bin/cli.js",
-    "test": "node --test 'src/**/*.test.js'",
+    "test": "node --test src/*.test.js src/lib/*.test.js",
+    "test:unit": "node --test src/cli.test.js src/config-cli.test.js src/detect.test.js src/launch.test.js src/validate.test.js src/lib/*.test.js",
+    "test:integration": "node --test src/integration.test.js",
+    "lint": "eslint .",
+    "lint:workspace": "turbo run lint",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "build:workspace": "turbo run build",
+    "typecheck:workspace": "turbo run typecheck",
+    "docs:build": "turbo run build --filter=@tmux-ide/docs",
+    "pack:check": "npm pack --dry-run --cache /tmp/tmux-ide-npm-cache > /dev/null",
+    "check": "pnpm run lint:workspace && pnpm run format:check && pnpm run test:unit && pnpm run docs:build && pnpm run pack:check",
+    "prepublishOnly": "pnpm run check",
     "postinstall": "node scripts/postinstall.js",
-    "docs": "cd docs && pnpm dev"
+    "docs": "turbo run dev --filter=@tmux-ide/docs"
   },
   "keywords": [
     "tmux",
@@ -38,7 +51,15 @@
     "url": "https://github.com/wavyrai/tmux-ide/issues"
   },
   "license": "MIT",
+  "packageManager": "pnpm@10.21.0",
   "dependencies": {
-    "js-yaml": "^4.1.0"
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "eslint": "^10.0.3",
+    "globals": "^17.4.0",
+    "prettier": "^3.8.1",
+    "turbo": "^2.3.3"
   }
 }

package/scripts/postinstall.js

@@ -1,13 +1,52 @@
-import { existsSync, mkdirSync, copyFileSync } from "node:fs";
+import { existsSync, mkdirSync, copyFileSync, readFileSync, writeFileSync } 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"));
+if (!shouldInstallClaudeIntegration() || !existsSync(claudeDir)) {
+  process.exit(0);
+}
+
+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"));
+}
+
+const settingsPath = resolve(claudeDir, "settings.json");
+let settings = {};
+
+if (existsSync(settingsPath)) {
+  try {
+    settings = JSON.parse(readFileSync(settingsPath, "utf-8"));
+  } catch (error) {
+    console.warn(
+      `[tmux-ide] Skipping Claude settings update: could not parse ${settingsPath}: ${error.message}`,
+    );
+    process.exit(0);
   }
 }
+
+if (settings == null || typeof settings !== "object" || Array.isArray(settings)) {
+  console.warn(
+    `[tmux-ide] Skipping Claude settings update: ${settingsPath} does not contain a JSON object.`,
+  );
+  process.exit(0);
+}
+
+const nextSettings = {
+  ...settings,
+  env: {
+    ...(settings.env && typeof settings.env === "object" && !Array.isArray(settings.env)
+      ? settings.env
+      : {}),
+    CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS: "1",
+  },
+};
+
+writeFileSync(settingsPath, `${JSON.stringify(nextSettings, null, 2)}\n`);
+
+function shouldInstallClaudeIntegration() {
+  return process.env.npm_config_global === "true";
+}