tmux-team 3.0.1 → 3.2.0

package/README.md

@@ -1,310 +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
-
-**Alias:** `tmt` is available as a shorthand for `tmux-team`
-
-### Shell Completion
-
-```bash
-# Zsh (add to ~/.zshrc)
-eval "$(tmux-team completion zsh)"
-
-# Bash (add to ~/.bashrc)
-eval "$(tmux-team completion bash)"
-```
-
-### Claude Code Plugin
+**Requirements:** Node.js >= 18, tmux
 
-```
-/plugin marketplace add wkh237/tmux-team
-/plugin install tmux-team@tmux-team
-```
+**Alias:** `tmt` (shorthand for `tmux-team`)
 
-### Agent Skills (Optional)
-
-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
+# 1. Install for your AI agent
+tmux-team install claude   # or: tmux-team install codex
 
-# Install to project directory instead
-tmux-team install-skill claude --local
-tmux-team install-skill codex --local
-```
+# 2. Run the setup wizard (auto-detects panes)
+tmux-team setup
 
-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 and wait for response (recommended for better token utilization)
-tmux-team talk codex "Review the auth module" --wait
-tmux-team talk all "Starting the refactor now" --wait
-
-# Or use the shorthand alias
-tmt talk codex "Quick question" --wait
-
-# Manage agents
-tmux-team list
-tmux-team update codex --remark "Now handling tests"
-tmux-team remove gemini
-
-# Learn more
-tmux-team learn
-```
-
-### From Claude Code
-
-Once the plugin is installed, coordinate directly from your Claude Code session:
-
-```
-/tmux-team:team codex "Can you review my changes?" --wait
-/tmux-team:team all "I'm starting the database migration" --wait
+# 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>" --wait` | Send message and wait for response (recommended) |
-| `talk ... --delay 5` | Wait 5 seconds before sending |
-| `talk ... --timeout 300` | Set max wait time (default: 180s) |
-| `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) |
+| `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 |
-| `completion [zsh\|bash]` | Output shell completion script |
 
----
+**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}"`
 
-### 📡 Async Mode (Recommended)
+## Claude Code Plugin
 
-The `--wait` flag is recommended for better token utilization:
-
-```bash
-# Wait for response with nonce-based completion detection
-tmux-team talk codex "Review this code" --wait
-
-# With custom timeout for complex tasks
-tmux-team talk codex "Implement the feature" --wait --timeout 300
-
-# Delay before sending (safe alternative to sleep)
-tmux-team talk codex "message" --wait --delay 5
 ```
-
-Enable by default: `tmux-team config set mode wait`
-
-### 📜 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,12 +1,25 @@
 {
   "name": "tmux-team",
-  "version": "3.0.1",
+  "version": "3.2.0",
   "description": "CLI tool for AI agent collaboration in tmux - manage cross-pane communication",
   "type": "module",
   "bin": {
     "tmux-team": "./bin/tmux-team",
     "tmt": "./bin/tmux-team"
   },
+  "scripts": {
+    "dev": "tsx src/cli.ts",
+    "tmt": "./bin/tmux-team",
+    "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/",
+    "format:check": "prettier --check src/",
+    "type:check": "tsc --noEmit",
+    "check": "npm run type:check && npm run lint && npm run format:check"
+  },
   "keywords": [
     "tmux",
     "cli",
@@ -38,21 +51,10 @@
   },
   "devDependencies": {
     "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^1.6.1",
     "oxlint": "^1.34.0",
     "prettier": "^3.7.4",
     "typescript": "^5.3.0",
     "vitest": "^1.2.0"
-  },
-  "scripts": {
-    "dev": "tsx src/cli.ts",
-    "tmt": "./bin/tmux-team",
-    "test": "vitest",
-    "test:run": "vitest run",
-    "lint": "oxlint src/",
-    "lint:fix": "oxlint src/ --fix",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
-    "type:check": "tsc --noEmit",
-    "check": "npm run type:check && npm run lint && npm run format:check"
   }
-}
+}

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);
+  });
+});