tmux-team 3.0.0 → 3.1.0

package/README.md

@@ -1,298 +1,106 @@
-# 🤖 tmux-team
+# tmux-team
 
-**The lightweight coordination layer for terminal-based AI agents.**
+Coordinate AI agents (Claude, Codex, Gemini) running in tmux panes. Send messages, wait for responses, broadcast to all.
 
-tmux-team is a protocol-agnostic transport layer that enables multi-agent collaboration directly within your existing tmux workflow. It turns a collection of isolated terminal panes into a coordinated AI team.
-
----
-
-## 🛑 The Problem
-
-As we move from "Chat with an AI" to "Orchestrating a Team," we face major friction points:
-
-1. **Isolation** — Agents in different panes (Claude, Gemini, local LLMs) have no way to talk to each other
-2. **Synchronization** — Humans are stuck in a "manual polling" loop—waiting for an agent to finish before copying its output to the next pane
-3. **Tool Restrictions** — AI agents operate under tool whitelists; using `sleep` or arbitrary shell commands is dangerous or blocked
-4. **Token Waste** — Repeated polling instructions burn context tokens unnecessarily
-
----
-
-## 🚀 Our Niche: The Universal Transport Layer
-
-Unlike heavyweight frameworks that require specific SDKs or cloud infrastructure, tmux-team treats the **terminal pane as the universal interface**.
-
-- **Model Agnostic** — Works with Claude Code, Gemini CLI, Codex, Aider, or any CLI tool
-- **Zero Infrastructure** — No servers, no MCP setup, no complex configuration. If it runs in tmux, tmux-team can talk to it
-- **Whitelist-Friendly** — A single `tmux-team talk:*` prefix covers all operations, keeping AI tool permissions simple and safe
-- **Local-First** — Per-project `tmux-team.json` lives with your repo; global config in `~/.config/tmux-team/`
-
----
-
-## 🧠 Design Philosophy
-
-> *These principles guide our design decisions.*
-
-### 1. Deterministic Transport (`--delay` vs. `sleep`)
-
-**The Problem**: Tool allowlists typically approve one safe command (`tmux-team talk ...`) but not arbitrary shell commands. Using `sleep` is often blocked by security policies.
-
-**The Why**: Internal delay keeps the workflow as a single tool call. No shell dependency, no policy friction.
-
-### 2. Stateless Handshakes (The "Nonce" Strategy)
-
-**The Problem**: Terminal panes are streams, not RPC channels. A simple `[DONE]` string could already be in scrollback.
-
-**The Why**: We use a unique **Nonce** for every request: `{tmux-team-end:8f3a}`.
-- **Collision Avoidance** — Prevents matching markers from previous turns
-- **Completion Safety** — Ensures the agent has truly finished
-- **Zero-API RPC** — Creates request/response semantics over a standard TTY
-
-### 3. Context Injection (Preambles)
-
-**The Problem**: AI agents are prone to "instruction drift." Over a long session, they might forget constraints.
-
-**The Why**: Preambles act as a forced system prompt for CLI environments. By injecting these "hidden instructions" at the transport level, we ensure the agent remains in character.
-
----
-
-## 📦 Installation
+## Install
 
 ```bash
 npm install -g tmux-team
 ```
 
-**Requirements:** Node.js >= 18, tmux, macOS/Linux
-
-### Shell Completion
-
-```bash
-# Zsh (add to ~/.zshrc)
-eval "$(tmux-team completion zsh)"
-
-# Bash (add to ~/.bashrc)
-eval "$(tmux-team completion bash)"
-```
-
-### Claude Code Plugin
-
-```
-/plugin marketplace add wkh237/tmux-team
-/plugin install tmux-team@tmux-team
-```
+**Requirements:** Node.js >= 18, tmux
 
-### Agent Skills (Optional)
+**Alias:** `tmt` (shorthand for `tmux-team`)
 
-Install tmux-team as a native skill for your AI coding agent:
+## Quick Start
 
 ```bash
-# Install for Claude Code (user-wide)
-tmux-team install-skill claude
-
-# Install for OpenAI Codex (user-wide)
-tmux-team install-skill codex
-
-# Install to project directory instead
-tmux-team install-skill claude --local
-tmux-team install-skill codex --local
-```
-
-See [skills/README.md](./skills/README.md) for detailed instructions.
-
----
-
-## ⌨️ Quick Start
-
-```bash
-# Initialize config
-tmux-team init
-
-# Register your agents (name + tmux pane ID)
-tmux-team add claude 10.0 "Frontend specialist"
-tmux-team add codex 10.1 "Backend engineer"
-tmux-team add gemini 10.2 "Code reviewer"
-
-# Send messages
-tmux-team talk codex "Review the auth module and suggest improvements"
-tmux-team talk all "Starting the refactor now"
+# 1. Install for your AI agent
+tmux-team install claude   # or: tmux-team install codex
 
-# Read responses
-tmux-team check codex
-tmux-team check codex 200  # More lines if needed
+# 2. Run the setup wizard (auto-detects panes)
+tmux-team setup
 
-# Manage agents
-tmux-team list
-tmux-team update codex --remark "Now handling tests"
-tmux-team remove gemini
-```
-
-### From Claude Code
-
-Once the plugin is installed, coordinate directly from your Claude Code session:
-
-```
-/tmux-team:team codex "Can you review my changes?"
-/tmux-team:team all "I'm starting the database migration"
+# 3. Talk to agents
+tmux-team talk codex "Review this code" --wait
 ```
 
----
+The `--wait` flag blocks until the agent responds, returning the response directly.
 
-## 📋 Commands
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `talk <agent> "<msg>"` | Send message to agent (or `all` for broadcast) |
-| `talk ... --delay 5` | Wait 5 seconds before sending |
-| `talk ... --wait` | Wait for agent response (nonce-based) |
-| `check <agent> [lines]` | Read agent's terminal output (default: 100 lines) |
-| `list` | Show all configured agents |
-| `add <name> <pane> [remark]` | Register a new agent |
-| `update <name> --pane/--remark` | Update agent configuration |
-| `remove <name>` | Unregister an agent |
-| `init` | Create `tmux-team.json` in current directory |
-| `config [show/set/clear]` | View/modify settings |
-| `preamble [show/set/clear]` | Manage agent preambles |
-| `install-skill <agent>` | Install skill for Claude/Codex (--local/--user) |
-| `completion [zsh\|bash]` | Output shell completion script |
+| `install [claude\|codex]` | Install tmux-team for an AI agent |
+| `setup` | Interactive wizard to configure agents |
+| `talk <agent> "msg" --wait` | Send message and wait for response |
+| `talk all "msg" --wait` | Broadcast to all agents |
+| `check <agent> [lines]` | Read agent's pane output (fallback if --wait times out) |
+| `list` | Show configured agents |
+| `learn` | Show educational guide |
 
----
+**Options for `talk --wait`:**
+- `--timeout <seconds>` - Max wait time (default: 180s)
+- `--lines <number>` - Lines to capture from response (default: 100)
 
-## ⚙️ Configuration
+Run `tmux-team help` for all commands and options.
 
-### Local Config (`./tmux-team.json`)
+## Managing Your Team
 
-Per-project agent registry with optional preambles:
+Configuration lives in `tmux-team.json` in your project root.
 
-```json
-{
-  "claude": {
-    "pane": "10.0",
-    "remark": "Frontend specialist",
-    "preamble": "Focus on UI components. Ask for review before merging."
-  },
-  "codex": {
-    "pane": "10.1",
-    "remark": "Code reviewer",
-    "preamble": "You are the code quality guard. Review changes thoroughly."
-  }
-}
+**Create** - Run the setup wizard to auto-detect agents:
+```bash
+tmux-team setup
 ```
 
-| Field | Description |
-|-------|-------------|
-| `pane` | tmux pane ID (required) |
-| `remark` | Description shown in `list` |
-| `preamble` | Hidden instructions prepended to every message |
-
-### Global Config (`~/.config/tmux-team/config.json`)
-
-Global settings that apply to all projects:
+**Read** - List configured agents:
+```bash
+tmux-team list
+```
 
+**Update** - Edit `tmux-team.json` directly or re-run setup:
 ```json
 {
-  "mode": "polling",
-  "preambleMode": "always",
-  "defaults": {
-    "timeout": 180,
-    "pollInterval": 1,
-    "captureLines": 100,
-    "preambleEvery": 3
-  }
+  "codex": { "pane": "%1", "remark": "Code reviewer" },
+  "gemini": { "pane": "%2", "remark": "Documentation" }
 }
 ```
 
-| Field | Description |
-|-------|-------------|
-| `mode` | Default mode: `polling` (manual check) or `wait` (auto-wait) |
-| `preambleMode` | `always` (inject preambles) or `disabled` |
-| `defaults.timeout` | Default --wait timeout in seconds |
-| `defaults.pollInterval` | Polling interval in seconds |
-| `defaults.captureLines` | Default lines for `check` command |
-| `defaults.preambleEvery` | Inject preamble every N messages (default: 3) |
-
----
+**Delete** - Remove an agent entry from `tmux-team.json` or delete the file entirely.
 
-## ✨ Features
+Find pane IDs: `tmux display-message -p "#{pane_id}"`
 
-### 📡 Enhanced `talk` Command
+## Claude Code Plugin
 
-```bash
-# Delay before sending (safe alternative to sleep)
-tmux-team talk codex "message" --delay 5
-
-# Wait for response with nonce-based completion detection
-tmux-team talk codex "message" --wait --timeout 60
 ```
-
-### 📜 Agent Preambles
-
-Inject hidden instructions into every message via local `tmux-team.json`:
-
-```json
-{
-  "gemini": {
-    "pane": "10.2",
-    "preamble": "Always explain your reasoning. Do not edit files directly."
-  }
-}
+/plugin marketplace add wkh237/tmux-team
+/plugin install tmux-team
 ```
 
-Use the CLI to manage preambles:
+Gives you two slash commands:
 
-```bash
-tmux-team preamble show gemini      # View current preamble
-tmux-team preamble set gemini "Be concise" # Set preamble
-tmux-team preamble clear gemini     # Remove preamble
+**`/learn`** - Teach Claude how to use tmux-team
 ```
+/learn
+```
+Run this once when starting a session. Claude will understand how to coordinate with other agents.
 
----
-
-## 🚫 Non-Goals
-
-tmux-team intentionally stays lightweight:
-
-- **Not an orchestrator** — No automatic agent selection or routing
-- **Not a session manager** — Doesn't create/manage tmux sessions
-- **Not an LLM wrapper** — Doesn't process or route messages through AI
-
-It's the plumbing layer that lets humans and AI agents coordinate via tmux, nothing more.
-
----
-
-## 📖 Command Reference
-
-### talk Options
-
-| Option | Description |
-|--------|-------------|
-| `--delay <seconds>` | Wait before sending (whitelist-friendly alternative to `sleep`) |
-| `--wait` | Block until agent responds (nonce-based completion detection) |
-| `--timeout <seconds>` | Max wait time (default: 180s) |
-| `--no-preamble` | Skip agent preamble for this message |
-
-### config Command
-
-```bash
-tmux-team config show                  # Show current config
-tmux-team config set mode wait         # Enable wait mode
-tmux-team config set preambleMode disabled  # Disable preambles
-tmux-team config set preambleEvery 5   # Inject preamble every 5 messages
-tmux-team config clear <key>           # Clear a config value
+**`/team`** - Talk to other agents
+```
+/team talk codex "Review my authentication changes" --wait
+/team talk all "I'm starting the database migration" --wait
+/team list
 ```
+Use this to delegate tasks, ask for reviews, or broadcast updates.
 
-### preamble Command
+## Learn More
 
 ```bash
-tmux-team preamble show <agent>        # Show agent's preamble
-tmux-team preamble set <agent> "text"  # Set agent's preamble
-tmux-team preamble clear <agent>       # Clear agent's preamble
+tmux-team learn   # Comprehensive guide
+tmux-team help    # All commands and options
 ```
 
----
-
-*Built for developers who live in the terminal and want their AIs to do the same.*
-
----
-
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-team",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "CLI tool for AI agent collaboration in tmux - manage cross-pane communication",
   "type": "module",
   "bin": {
@@ -10,8 +10,9 @@
   "scripts": {
     "dev": "tsx src/cli.ts",
     "tmt": "./bin/tmux-team",
-    "test": "vitest",
-    "test:run": "vitest run",
+    "test": "npm run test:run",
+    "test:watch": "vitest",
+    "test:run": "vitest run --coverage && node scripts/check-coverage.mjs --threshold 95",
     "lint": "oxlint src/",
     "lint:fix": "oxlint src/ --fix",
     "format": "prettier --write src/",
@@ -50,6 +51,7 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^1.6.1",
     "oxlint": "^1.34.0",
     "prettier": "^3.7.4",
     "typescript": "^5.3.0",

package/skills/README.md

@@ -16,22 +16,21 @@ The easiest way to add tmux-team to Claude Code is via the plugin system:
 
 This gives you `/team` and `/learn` slash commands automatically.
 
-## Quick Install (Standalone Skills)
+## Quick Install
 
-If you prefer standalone skills without the full plugin:
+Use the interactive install command:
 
 ```bash
-# Install for Claude Code (user-wide)
-tmux-team install-skill claude
+# Auto-detect environment and install
+tmux-team install
 
-# Install for OpenAI Codex (user-wide)
-tmux-team install-skill codex
-
-# Install to project directory (local scope)
-tmux-team install-skill claude --local
-tmux-team install-skill codex --local
+# Or specify agent directly
+tmux-team install claude
+tmux-team install codex
 ```
 
+After installation, run `tmux-team setup` to configure your agents interactively.
+
 ## Claude Code
 
 Claude Code uses slash commands stored in `~/.claude/commands/` (user) or `.claude/commands/` (local).

package/src/cli.test.ts

@@ -0,0 +1,163 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import type { Context } from './types.js';
+
+function makeStubContext(): Context {
+  return {
+    argv: [],
+    flags: { json: false, verbose: false },
+    ui: {
+      info: vi.fn(),
+      success: vi.fn(),
+      warn: vi.fn(),
+      error: vi.fn(),
+      table: vi.fn(),
+      json: vi.fn(),
+    },
+    config: {
+      mode: 'polling',
+      preambleMode: 'always',
+      defaults: { timeout: 180, pollInterval: 1, captureLines: 100, preambleEvery: 3 },
+      agents: {},
+      paneRegistry: {},
+    },
+    tmux: {
+      send: vi.fn(),
+      capture: vi.fn(),
+      listPanes: vi.fn(() => []),
+      getCurrentPaneId: vi.fn(() => null),
+    },
+    paths: {
+      globalDir: '/g',
+      globalConfig: '/g/c.json',
+      localConfig: '/p/t.json',
+      stateFile: '/g/s.json',
+    },
+    exit: ((code: number) => {
+      const err = new Error(`exit(${code})`);
+      (err as Error & { exitCode: number }).exitCode = code;
+      throw err;
+    }) as any,
+  };
+}
+
+describe('cli', () => {
+  const originalArgv = process.argv;
+
+  beforeEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  afterEach(() => {
+    process.argv = originalArgv;
+    vi.restoreAllMocks();
+  });
+
+  it('prints completion for bash', async () => {
+    vi.resetModules();
+    process.argv = ['node', 'cli', 'completion', 'bash'];
+
+    vi.doMock('./context.js', () => ({
+      createContext: () => makeStubContext(),
+      ExitCodes: { SUCCESS: 0, ERROR: 1 },
+    }));
+    vi.doMock('./commands/completion.js', () => ({
+      cmdCompletion: (shell?: string) => {
+        console.log(`completion:${shell}`);
+      },
+    }));
+
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    await import('./cli.js');
+    expect(logSpy).toHaveBeenCalledWith('completion:bash');
+    expect(exitSpy).toHaveBeenCalledWith(0);
+  });
+
+  it('errors on invalid time format', async () => {
+    vi.resetModules();
+    process.argv = ['node', 'cli', 'talk', 'codex', 'hi', '--delay', 'abc'];
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation(((code?: number) => {
+      throw new Error(`exit(${code})`);
+    }) as any);
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    await expect(import('./cli.js')).rejects.toThrow('exit(1)');
+    expect(errSpy).toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('routes unknown command to ctx.ui.error and exits', async () => {
+    vi.resetModules();
+    process.argv = ['node', 'cli', 'nope'];
+
+    const ctx = makeStubContext();
+    vi.doMock('./context.js', () => ({
+      createContext: () => ctx,
+      ExitCodes: { SUCCESS: 0, ERROR: 1 },
+    }));
+
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
+    await import('./cli.js');
+    expect(ctx.ui.error).toHaveBeenCalled();
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+
+  it('handles --version by printing VERSION', async () => {
+    vi.resetModules();
+    process.argv = ['node', 'cli', '--version'];
+    const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
+
+    await import('./cli.js');
+    // allow the dynamic import to resolve
+    await new Promise((r) => setTimeout(r, 0));
+    expect(logSpy).toHaveBeenCalled();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it('routes learn command and does not exit', async () => {
+    vi.resetModules();
+    process.argv = ['node', 'cli', 'learn'];
+
+    const ctx = makeStubContext();
+    const learnSpy = vi.fn();
+    vi.doMock('./context.js', () => ({
+      createContext: () => ctx,
+      ExitCodes: { SUCCESS: 0, ERROR: 1 },
+    }));
+    vi.doMock('./commands/learn.js', () => ({ cmdLearn: learnSpy }));
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
+
+    await import('./cli.js');
+    expect(learnSpy).toHaveBeenCalled();
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it('prints JSON error when --json and a command throws', async () => {
+    vi.resetModules();
+    process.argv = ['node', 'cli', 'remove', 'some-agent', '--json']; // will throw in our mocked cmdRemove
+
+    const ctx = makeStubContext();
+    ctx.flags.json = true;
+    vi.doMock('./context.js', () => ({
+      createContext: () => ctx,
+      ExitCodes: { SUCCESS: 0, ERROR: 1 },
+    }));
+    vi.doMock('./commands/remove.js', () => ({
+      cmdRemove: () => {
+        throw new Error('boom');
+      },
+    }));
+
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+    const exitSpy = vi.spyOn(process, 'exit').mockImplementation((() => {}) as any);
+
+    await import('./cli.js');
+    // allow the run().catch handler to run
+    await new Promise((r) => setTimeout(r, 0));
+
+    expect(errSpy).toHaveBeenCalledWith(JSON.stringify({ error: 'boom' }));
+    expect(exitSpy).toHaveBeenCalledWith(1);
+  });
+});

package/src/cli.ts

@@ -19,7 +19,9 @@ import { cmdCheck } from './commands/check.js';
 import { cmdCompletion } from './commands/completion.js';
 import { cmdConfig } from './commands/config.js';
 import { cmdPreamble } from './commands/preamble.js';
-import { cmdInstallSkill } from './commands/install-skill.js';
+import { cmdInstall } from './commands/install.js';
+import { cmdSetup } from './commands/setup.js';
+import { cmdLearn } from './commands/learn.js';
 
 // ─────────────────────────────────────────────────────────────
 // Argument parsing
@@ -41,6 +43,8 @@ function parseArgs(argv: string[]): { command: string; args: string[]; flags: Fl
       flags.json = true;
     } else if (arg === '--verbose' || arg === '-v') {
       flags.verbose = true;
+    } else if (arg === '--debug') {
+      flags.debug = true;
     } else if (arg === '--force' || arg === '-f') {
       flags.force = true;
     } else if (arg === '--config') {
@@ -51,6 +55,8 @@ function parseArgs(argv: string[]): { command: string; args: string[]; flags: Fl
       flags.wait = true;
     } else if (arg === '--timeout') {
       flags.timeout = parseTime(argv[++i]);
+    } else if (arg === '--lines') {
+      flags.lines = parseInt(argv[++i], 10) || 100;
     } else if (arg === '--no-preamble') {
       flags.noPreamble = true;
     } else if (arg.startsWith('--pane=')) {
@@ -106,19 +112,23 @@ function main(): void {
 
   // Help - load config to show current mode/timeout
   if (!command || command === 'help' || command === '--help' || command === '-h') {
+    // Show intro highlight when running just `tmux-team` with no args
+    const showIntro = !command || argv.length === 0;
     try {
       const paths = resolvePaths();
       const config = loadConfig(paths);
       const helpConfig: HelpConfig = {
         mode: config.mode,
         timeout: config.defaults.timeout,
+        showIntro,
       };
       cmdHelp(helpConfig);
     } catch {
       // Fallback if config can't be loaded
-      cmdHelp();
+      cmdHelp({ showIntro });
     }
     process.exit(ExitCodes.SUCCESS);
+    return;
   }
 
   if (command === '--version' || command === '-V') {
@@ -130,11 +140,18 @@ function main(): void {
   if (command === 'completion') {
     cmdCompletion(args[0]);
     process.exit(ExitCodes.SUCCESS);
+    return;
   }
 
   // Create context for all other commands
   const ctx = createContext({ argv, flags });
 
+  // Warn if not in tmux for commands that require it
+  const TMUX_REQUIRED_COMMANDS = ['talk', 'send', 'check', 'read', 'setup'];
+  if (!process.env.TMUX && TMUX_REQUIRED_COMMANDS.includes(command)) {
+    ctx.ui.warn('Not running inside tmux. Some features may not work.');
+  }
+
   const run = async (): Promise<void> => {
     switch (command) {
       case 'init':
@@ -211,22 +228,16 @@ function main(): void {
         cmdPreamble(ctx, args);
         break;
 
-      case 'install-skill':
-        {
-          // Parse --local or --user flag
-          let scope = 'user';
-          const filteredArgs: string[] = [];
-          for (const arg of args) {
-            if (arg === '--local') {
-              scope = 'local';
-            } else if (arg === '--user') {
-              scope = 'user';
-            } else {
-              filteredArgs.push(arg);
-            }
-          }
-          cmdInstallSkill(ctx, filteredArgs[0], scope);
-        }
+      case 'install':
+        await cmdInstall(ctx, args[0]);
+        break;
+
+      case 'setup':
+        await cmdSetup(ctx);
+        break;
+
+      case 'learn':
+        cmdLearn();
         break;
 
       default: