tmux-team 3.0.0 → 3.1.0

package/src/commands/install.ts

@@ -0,0 +1,207 @@
+// ─────────────────────────────────────────────────────────────
+// install command - install tmux-team for AI agents
+// ─────────────────────────────────────────────────────────────
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+import * as readline from 'node:readline';
+import { fileURLToPath } from 'node:url';
+import type { Context } from '../types.js';
+import { ExitCodes } from '../exits.js';
+import { colors } from '../ui.js';
+import { cmdSetup } from './setup.js';
+
+type AgentType = 'claude' | 'codex';
+
+interface SkillConfig {
+  sourceFile: string;
+  userDir: string;
+  targetFile: string;
+  detected: () => boolean;
+}
+
+function getCodexHome(): string {
+  return process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
+}
+
+const SKILL_CONFIGS: Record<AgentType, SkillConfig> = {
+  claude: {
+    sourceFile: 'skills/claude/team.md',
+    userDir: path.join(os.homedir(), '.claude', 'commands'),
+    targetFile: 'team.md',
+    detected: () => fs.existsSync(path.join(os.homedir(), '.claude')),
+  },
+  codex: {
+    sourceFile: 'skills/codex/SKILL.md',
+    userDir: path.join(getCodexHome(), 'skills', 'tmux-team'),
+    targetFile: 'SKILL.md',
+    detected: () => fs.existsSync(getCodexHome()),
+  },
+};
+
+const SUPPORTED_AGENTS = Object.keys(SKILL_CONFIGS) as AgentType[];
+
+function findPackageRoot(): string {
+  const currentFile = fileURLToPath(import.meta.url);
+  let dir = path.dirname(currentFile);
+
+  for (let i = 0; i < 5; i++) {
+    const pkgPath = path.join(dir, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path.resolve(path.dirname(currentFile), '..', '..');
+}
+
+function detectEnvironment(): AgentType[] {
+  const detected: AgentType[] = [];
+  for (const [agent, config] of Object.entries(SKILL_CONFIGS)) {
+    if (config.detected()) {
+      detected.push(agent as AgentType);
+    }
+  }
+  return detected;
+}
+
+async function prompt(rl: readline.Interface, question: string): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function confirm(rl: readline.Interface, question: string): Promise<boolean> {
+  const answer = await prompt(rl, `${question} [Y/n]: `);
+  return answer.toLowerCase() !== 'n';
+}
+
+function installSkill(ctx: Context, agent: AgentType): boolean {
+  const config = SKILL_CONFIGS[agent];
+  const pkgRoot = findPackageRoot();
+  const sourcePath = path.join(pkgRoot, config.sourceFile);
+
+  if (!fs.existsSync(sourcePath)) {
+    ctx.ui.error(`Skill file not found: ${sourcePath}`);
+    ctx.ui.info('Make sure tmux-team is properly installed.');
+    return false;
+  }
+
+  const targetPath = path.join(config.userDir, config.targetFile);
+
+  if (fs.existsSync(targetPath) && !ctx.flags.force) {
+    ctx.ui.warn(`Skill already exists: ${targetPath}`);
+    ctx.ui.info('Use --force to overwrite.');
+    return false;
+  }
+
+  if (!fs.existsSync(config.userDir)) {
+    fs.mkdirSync(config.userDir, { recursive: true });
+  }
+
+  fs.copyFileSync(sourcePath, targetPath);
+  return true;
+}
+
+export async function cmdInstall(ctx: Context, agent?: string): Promise<void> {
+  const { ui, flags, exit } = ctx;
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    let selectedAgent: AgentType;
+
+    if (agent) {
+      // Direct agent specification
+      const agentLower = agent.toLowerCase() as AgentType;
+      if (!SUPPORTED_AGENTS.includes(agentLower)) {
+        ui.error(`Unknown agent: ${agent}`);
+        ui.info(`Supported agents: ${SUPPORTED_AGENTS.join(', ')}`);
+        exit(ExitCodes.ERROR);
+      }
+      selectedAgent = agentLower;
+    } else {
+      // Auto-detect and prompt
+      const detected = detectEnvironment();
+      console.log();
+
+      if (detected.length === 0) {
+        ui.info('No AI agent environments detected.');
+        ui.info(`Supported agents: ${SUPPORTED_AGENTS.join(', ')}`);
+        console.log();
+        const choice = await prompt(rl, 'Which agent are you using? ');
+        const choiceLower = choice.toLowerCase() as AgentType;
+        if (!SUPPORTED_AGENTS.includes(choiceLower)) {
+          ui.error(`Unknown agent: ${choice}`);
+          exit(ExitCodes.ERROR);
+        }
+        selectedAgent = choiceLower;
+      } else if (detected.length === 1) {
+        ui.success(`Detected: ${detected[0]}`);
+        selectedAgent = detected[0];
+      } else {
+        ui.info(`Detected multiple environments: ${detected.join(', ')}`);
+        const choice = await prompt(rl, 'Which agent are you installing for? ');
+        const choiceLower = choice.toLowerCase() as AgentType;
+        if (!SUPPORTED_AGENTS.includes(choiceLower)) {
+          ui.error(`Unknown agent: ${choice}`);
+          exit(ExitCodes.ERROR);
+        }
+        selectedAgent = choiceLower;
+      }
+    }
+
+    // Install the skill
+    console.log();
+    const success = installSkill(ctx, selectedAgent);
+    if (!success) {
+      exit(ExitCodes.ERROR);
+    }
+
+    const config = SKILL_CONFIGS[selectedAgent];
+    const targetPath = path.join(config.userDir, config.targetFile);
+    ui.success(`Installed ${selectedAgent} skill to ${targetPath}`);
+
+    // Agent-specific instructions
+    console.log();
+    if (selectedAgent === 'claude') {
+      console.log(colors.yellow('For full plugin features, run these in Claude Code:'));
+      console.log(`  ${colors.cyan('/plugin marketplace add wkh237/tmux-team')}`);
+      console.log(`  ${colors.cyan('/plugin install tmux-team')}`);
+      console.log();
+    } else if (selectedAgent === 'codex') {
+      console.log(colors.yellow('Enable skills in Codex:'));
+      console.log(`  ${colors.cyan('codex --enable skills')}`);
+      console.log();
+    }
+
+    // Offer to run setup
+    if (process.env.TMUX) {
+      const runSetup = await confirm(rl, 'Run setup wizard now?');
+      if (runSetup) {
+        rl.close();
+        await cmdSetup(ctx);
+        return;
+      }
+    } else {
+      ui.info('Run tmux-team setup inside tmux to configure your agents.');
+    }
+
+    console.log();
+    console.log(colors.yellow('Next steps:'));
+    console.log(`  1. Start tmux and open panes for your AI agents`);
+    console.log(`  2. Run ${colors.cyan('tmux-team setup')} to configure agents`);
+    console.log(`  3. Use ${colors.cyan('tmux-team talk <agent> "message" --wait')}`);
+    console.log();
+  } finally {
+    rl.close();
+  }
+}

package/src/commands/learn.ts

@@ -0,0 +1,80 @@
+// ─────────────────────────────────────────────────────────────
+// learn command - educational guide for tmux-team
+// ─────────────────────────────────────────────────────────────
+
+import { colors } from '../ui.js';
+
+export function cmdLearn(): void {
+  console.log(`
+${colors.cyan('tmux-team')} - Multi-Agent Coordination Guide
+
+${colors.yellow('WHAT IS TMUX-TEAM?')}
+
+  tmux-team enables AI agents (Claude, Codex, Gemini) running in separate
+  terminal panes to communicate with each other. Think of it as a messaging
+  system for terminal-based AI agents.
+
+${colors.yellow('CORE CONCEPT')}
+
+  Each agent runs in its own tmux pane. When you talk to another agent:
+  1. Your message is sent to their pane via tmux send-keys
+  2. They see it as if a human typed it
+  3. You read their response by capturing their pane output
+
+${colors.yellow('ESSENTIAL COMMANDS')}
+
+  ${colors.green('tmux-team list')}                     List available agents
+  ${colors.green('tmux-team talk')} <agent> "<msg>"     Send a message
+  ${colors.green('tmux-team check')} <agent> [lines]    Read agent's response
+  ${colors.green('tmux-team talk')} <agent> --wait      Send and wait for response
+
+${colors.yellow('RECOMMENDED: ASYNC MODE (--wait)')}
+
+  The ${colors.green('--wait')} flag is recommended for better token utilization:
+
+  ${colors.dim('# Without --wait (polling mode):')}
+  tmux-team talk codex "Review this code"
+  ${colors.dim('# ... wait manually ...')}
+  tmux-team check codex                    ${colors.dim('← extra command')}
+
+  ${colors.dim('# With --wait (async mode):')}
+  tmux-team talk codex "Review this code" --wait
+  ${colors.dim('↳ Blocks until response, returns it directly')}
+
+  Enable by default: ${colors.cyan('tmux-team config set mode wait')}
+
+${colors.yellow('PRACTICAL EXAMPLES')}
+
+  ${colors.dim('# Quick question (async)')}
+  tmux-team talk codex "What's the auth status?" --wait
+
+  ${colors.dim('# Delegate a task with timeout')}
+  tmux-team talk gemini "Implement login form" --wait --timeout 300
+
+  ${colors.dim('# Broadcast to all agents')}
+  tmux-team talk all "Sync: PR #123 was merged" --wait
+
+${colors.yellow('CONFIGURATION')}
+
+  Config file: ${colors.cyan('./tmux-team.json')}
+
+  {
+    "$config": { "mode": "wait" },
+    "codex": { "pane": "%1", "remark": "Code reviewer" },
+    "gemini": { "pane": "%2", "remark": "Documentation" }
+  }
+
+  Find your pane ID: ${colors.cyan('tmux display-message -p "#{pane_id}"')}
+
+${colors.yellow('BEST PRACTICES')}
+
+  1. ${colors.green('Use --wait for important tasks')} - ensures complete response
+  2. ${colors.green('Be explicit')} - tell agents exactly what you need
+  3. ${colors.green('Set timeout appropriately')} - complex tasks need more time
+  4. ${colors.green('Broadcast sparingly')} - only for announcements everyone needs
+
+${colors.yellow('NEXT STEP')}
+
+  Run ${colors.cyan('tmux-team list')} to see available agents in your project.
+`);
+}

package/src/commands/setup.test.ts

@@ -0,0 +1,175 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import type { Context, Flags, Paths, ResolvedConfig, Tmux, UI } from '../types.js';
+import { ExitCodes } from '../exits.js';
+
+function createMockUI(): UI {
+  return {
+    info: vi.fn(),
+    success: vi.fn(),
+    warn: vi.fn(),
+    error: vi.fn(),
+    table: vi.fn(),
+    json: vi.fn(),
+  };
+}
+
+function createCtx(testDir: string, tmux: Tmux, flags?: Partial<Flags>): Context {
+  const paths: Paths = {
+    globalDir: testDir,
+    globalConfig: path.join(testDir, 'config.json'),
+    localConfig: path.join(testDir, 'tmux-team.json'),
+    stateFile: path.join(testDir, 'state.json'),
+  };
+  const config: ResolvedConfig = {
+    mode: 'polling',
+    preambleMode: 'always',
+    defaults: { timeout: 180, pollInterval: 1, captureLines: 100, preambleEvery: 3 },
+    agents: {},
+    paneRegistry: {},
+  };
+  return {
+    argv: [],
+    flags: { json: false, verbose: false, ...(flags ?? {}) } as Flags,
+    ui: createMockUI(),
+    config,
+    tmux,
+    paths,
+    exit: ((code: number) => {
+      const err = new Error(`exit(${code})`);
+      (err as Error & { exitCode: number }).exitCode = code;
+      throw err;
+    }) as any,
+  };
+}
+
+describe('cmdSetup', () => {
+  let testDir = '';
+  const originalTmux = process.env.TMUX;
+
+  beforeEach(() => {
+    testDir = fs.mkdtempSync(path.join(os.tmpdir(), 'tmux-team-setup-'));
+  });
+
+  afterEach(() => {
+    process.env.TMUX = originalTmux;
+    fs.rmSync(testDir, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it('errors when not in tmux', async () => {
+    vi.resetModules();
+    delete process.env.TMUX;
+    const { cmdSetup } = await import('./setup.js');
+    const ctx = createCtx(testDir, {
+      send: vi.fn(),
+      capture: vi.fn(),
+      listPanes: vi.fn(() => []),
+      getCurrentPaneId: vi.fn(() => null),
+    });
+    await expect(cmdSetup(ctx)).rejects.toThrow(`exit(${ExitCodes.ERROR})`);
+  });
+
+  it('creates tmux-team.json by configuring panes', async () => {
+    vi.resetModules();
+    process.env.TMUX = '1';
+
+    const answers = [
+      '', // accept default "codex" for pane %1
+      'reviewer', // remark
+      '1bad', // invalid name for pane %2 -> skipped
+      '', // remark (unused)
+    ];
+
+    vi.doMock('readline', () => ({
+      default: {
+        createInterface: () => ({
+          question: (_q: string, cb: (a: string) => void) => cb(answers.shift() ?? ''),
+          close: () => {},
+        }),
+      },
+      createInterface: () => ({
+        question: (_q: string, cb: (a: string) => void) => cb(answers.shift() ?? ''),
+        close: () => {},
+      }),
+    }));
+
+    const { cmdSetup } = await import('./setup.js');
+    const ctx = createCtx(testDir, {
+      send: vi.fn(),
+      capture: vi.fn(),
+      getCurrentPaneId: vi.fn(() => '%0'),
+      listPanes: vi.fn(() => [
+        { id: '%0', command: 'zsh', suggestedName: null },
+        { id: '%1', command: 'codex', suggestedName: 'codex' },
+        { id: '%2', command: 'zsh', suggestedName: null },
+      ]),
+    });
+
+    await cmdSetup(ctx);
+    const saved = JSON.parse(fs.readFileSync(ctx.paths.localConfig, 'utf-8'));
+    expect(saved.codex.pane).toBe('%1');
+    expect(saved.codex.remark).toBe('reviewer');
+  });
+
+  it('errors when no panes found', async () => {
+    vi.resetModules();
+    process.env.TMUX = '1';
+    vi.doMock('readline', () => ({
+      default: {
+        createInterface: () => ({
+          question: (_q: string, cb: (a: string) => void) => cb(''),
+          close: () => {},
+        }),
+      },
+      createInterface: () => ({
+        question: (_q: string, cb: (a: string) => void) => cb(''),
+        close: () => {},
+      }),
+    }));
+    const { cmdSetup } = await import('./setup.js');
+    const ctx = createCtx(testDir, {
+      send: vi.fn(),
+      capture: vi.fn(),
+      getCurrentPaneId: vi.fn(() => '%0'),
+      listPanes: vi.fn(() => []),
+    });
+    await expect(cmdSetup(ctx)).rejects.toThrow(`exit(${ExitCodes.ERROR})`);
+  });
+
+  it('exits success when user skips all panes', async () => {
+    vi.resetModules();
+    process.env.TMUX = '1';
+
+    const answers = [
+      '', // pane %1 has no suggested name -> press Enter to skip
+    ];
+    vi.doMock('readline', () => ({
+      default: {
+        createInterface: () => ({
+          question: (_q: string, cb: (a: string) => void) => cb(answers.shift() ?? ''),
+          close: () => {},
+        }),
+      },
+      createInterface: () => ({
+        question: (_q: string, cb: (a: string) => void) => cb(answers.shift() ?? ''),
+        close: () => {},
+      }),
+    }));
+
+    const { cmdSetup } = await import('./setup.js');
+    const ctx = createCtx(testDir, {
+      send: vi.fn(),
+      capture: vi.fn(),
+      getCurrentPaneId: vi.fn(() => '%0'),
+      listPanes: vi.fn(() => [
+        { id: '%0', command: 'zsh', suggestedName: null },
+        { id: '%1', command: 'zsh', suggestedName: null },
+      ]),
+    });
+
+    await expect(cmdSetup(ctx)).rejects.toThrow(`exit(${ExitCodes.SUCCESS})`);
+  });
+});

package/src/commands/setup.ts

@@ -0,0 +1,163 @@
+// ─────────────────────────────────────────────────────────────
+// setup command - interactive wizard for configuring agents
+// ─────────────────────────────────────────────────────────────
+
+import fs from 'fs';
+import readline from 'readline';
+import type { Context, PaneEntry, PaneInfo, LocalConfigFile } from '../types.js';
+import { ExitCodes } from '../exits.js';
+import { loadLocalConfigFile, saveLocalConfigFile } from '../config.js';
+import { colors } from '../ui.js';
+
+async function prompt(rl: readline.Interface, question: string): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+async function promptWithDefault(
+  rl: readline.Interface,
+  question: string,
+  defaultValue: string
+): Promise<string> {
+  const answer = await prompt(rl, `${question} [${defaultValue}]: `);
+  return answer || defaultValue;
+}
+
+async function confirm(rl: readline.Interface, question: string): Promise<boolean> {
+  const answer = await prompt(rl, `${question} [Y/n]: `);
+  return answer.toLowerCase() !== 'n';
+}
+
+export async function cmdSetup(ctx: Context): Promise<void> {
+  const { ui, tmux, paths, exit } = ctx;
+
+  // Check if in tmux
+  if (!process.env.TMUX) {
+    ui.error('Not running inside tmux. Please run this command from within a tmux session.');
+    exit(ExitCodes.ERROR);
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  try {
+    console.log();
+    ui.info('Detecting tmux panes...');
+    console.log();
+
+    const panes = tmux.listPanes();
+    const currentPaneId = tmux.getCurrentPaneId();
+
+    if (panes.length === 0) {
+      ui.error('No tmux panes found.');
+      exit(ExitCodes.ERROR);
+    }
+
+    // Filter out current pane
+    const otherPanes = panes.filter((p) => p.id !== currentPaneId);
+
+    if (otherPanes.length === 0) {
+      ui.warn('No other panes found. Create more tmux panes with other agents first.');
+      ui.info('Hint: Use Ctrl+B % or Ctrl+B " to split panes, then start your AI agents.');
+      exit(ExitCodes.ERROR);
+    }
+
+    // Show detected panes
+    console.log(colors.yellow('Found panes:'));
+    console.log(`  ${colors.dim(currentPaneId || '?')} ${colors.dim('(current pane - skipped)')}`);
+    for (const pane of otherPanes) {
+      const detected = pane.suggestedName
+        ? colors.green(pane.suggestedName)
+        : colors.dim('(unknown)');
+      console.log(`  ${pane.id} running "${pane.command}" → detected: ${detected}`);
+    }
+    console.log();
+
+    // Load existing config
+    let localConfig: LocalConfigFile = {};
+    if (fs.existsSync(paths.localConfig)) {
+      localConfig = loadLocalConfigFile(paths);
+    }
+
+    const agents: Record<string, PaneEntry> = {};
+    let configuredCount = 0;
+
+    // Configure each pane
+    for (const pane of otherPanes) {
+      const detected = pane.suggestedName || '';
+
+      console.log(colors.cyan(`Configure pane ${pane.id}?`));
+      if (pane.suggestedName) {
+        console.log(`  Detected: ${colors.green(pane.suggestedName)}`);
+      }
+
+      // Ask for name
+      let name: string;
+      if (detected) {
+        name = await promptWithDefault(rl, '  Name', detected);
+      } else {
+        name = await prompt(rl, '  Name (or press Enter to skip): ');
+        if (!name) {
+          console.log(colors.dim('  Skipped'));
+          console.log();
+          continue;
+        }
+      }
+
+      // Validate name
+      if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(name)) {
+        ui.warn(
+          '  Invalid name. Use letters, numbers, underscores, hyphens. Starting with a letter.'
+        );
+        console.log(colors.dim('  Skipped'));
+        console.log();
+        continue;
+      }
+
+      // Ask for optional remark
+      const remark = await prompt(rl, '  Remark (optional): ');
+
+      const entry: PaneEntry = { pane: pane.id };
+      if (remark) {
+        entry.remark = remark;
+      }
+
+      agents[name] = entry;
+      configuredCount++;
+      console.log();
+    }
+
+    if (configuredCount === 0) {
+      ui.warn('No agents configured.');
+      exit(ExitCodes.SUCCESS);
+    }
+
+    // Merge with existing config (preserve $config and existing agents)
+    const newConfig: LocalConfigFile = { ...localConfig };
+    for (const [name, entry] of Object.entries(agents)) {
+      newConfig[name] = entry;
+    }
+
+    // Save config
+    if (!fs.existsSync(paths.localConfig)) {
+      fs.writeFileSync(paths.localConfig, '{}\n');
+    }
+    saveLocalConfigFile(paths, newConfig);
+
+    ui.success(`Created ${paths.localConfig} with ${configuredCount} agent(s)`);
+    console.log();
+
+    // Show next steps
+    const firstAgent = Object.keys(agents)[0];
+    console.log(colors.yellow('Try it:'));
+    console.log(`  ${colors.cyan(`tmux-team talk ${firstAgent} "hello" --wait`)}`);
+    console.log();
+  } finally {
+    rl.close();
+  }
+}