tmux-team 3.0.0 → 3.0.1

package/README.md

@@ -63,6 +63,8 @@ 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
@@ -111,18 +113,20 @@ 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"
+# 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
 
-# Read responses
-tmux-team check codex
-tmux-team check codex 200  # More lines if needed
+# 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
@@ -130,8 +134,8 @@ tmux-team remove gemini
 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"
+/tmux-team:team codex "Can you review my changes?" --wait
+/tmux-team:team all "I'm starting the database migration" --wait
 ```
 
 ---
@@ -140,9 +144,9 @@ Once the plugin is installed, coordinate directly from your Claude Code session:
 
 | Command | Description |
 |---------|-------------|
-| `talk <agent> "<msg>"` | Send message to agent (or `all` for broadcast) |
+| `talk <agent> "<msg>" --wait` | Send message and wait for response (recommended) |
 | `talk ... --delay 5` | Wait 5 seconds before sending |
-| `talk ... --wait` | Wait for agent response (nonce-based) |
+| `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 |
@@ -152,6 +156,7 @@ Once the plugin is installed, coordinate directly from your Claude Code session:
 | `config [show/set/clear]` | View/modify settings |
 | `preamble [show/set/clear]` | Manage agent preambles |
 | `install-skill <agent>` | Install skill for Claude/Codex (--local/--user) |
+| `learn` | Show educational guide |
 | `completion [zsh\|bash]` | Output shell completion script |
 
 ---
@@ -213,16 +218,23 @@ Global settings that apply to all projects:
 
 ## ✨ Features
 
-### 📡 Enhanced `talk` Command
+### 📡 Async Mode (Recommended)
 
-```bash
-# Delay before sending (safe alternative to sleep)
-tmux-team talk codex "message" --delay 5
+The `--wait` flag is recommended for better token utilization:
 
+```bash
 # Wait for response with nonce-based completion detection
-tmux-team talk codex "message" --wait --timeout 60
+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`:

package/package.json

@@ -1,24 +1,12 @@
 {
   "name": "tmux-team",
-  "version": "3.0.0",
+  "version": "3.0.1",
   "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": "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"
-  },
   "keywords": [
     "tmux",
     "cli",
@@ -54,5 +42,17 @@
     "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/src/cli.ts

@@ -20,6 +20,7 @@ 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 { cmdLearn } from './commands/learn.js';
 
 // ─────────────────────────────────────────────────────────────
 // Argument parsing
@@ -106,17 +107,20 @@ 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);
   }
@@ -229,6 +233,10 @@ function main(): void {
         }
         break;
 
+      case 'learn':
+        cmdLearn();
+        break;
+
       default:
         ctx.ui.error(`Unknown command: ${command}. Run 'tmux-team help' for usage.`);
         ctx.exit(ExitCodes.ERROR);

package/src/commands/help.ts

@@ -8,6 +8,7 @@ import { VERSION } from '../version.js';
 export interface HelpConfig {
   mode?: 'polling' | 'wait';
   timeout?: number;
+  showIntro?: boolean;
 }
 
 export function cmdHelp(config?: HelpConfig): void {
@@ -15,17 +16,28 @@ export function cmdHelp(config?: HelpConfig): void {
   const timeout = config?.timeout ?? 180;
   const isWaitMode = mode === 'wait';
 
+  // Show intro highlight when running just `tmux-team` with no args
+  if (config?.showIntro) {
+    console.log(`
+${colors.cyan('┌─────────────────────────────────────────────────────────────┐')}
+${colors.cyan('│')}  ${colors.yellow('New to tmux-team?')} Run ${colors.green('tmux-team learn')} or ${colors.green('tmt learn')}         ${colors.cyan('│')}
+${colors.cyan('│')}  ${colors.dim('tmt is a shorthand alias for tmux-team')}                      ${colors.cyan('│')}
+${colors.cyan('└─────────────────────────────────────────────────────────────┘')}`);
+  }
+
   // Mode indicator with clear explanation
   const modeInfo = isWaitMode
-    ? `${colors.yellow('CURRENT MODE')}: ${colors.green('wait')} (timeout: ${timeout}s)
+    ? `${colors.yellow('CURRENT MODE')}: ${colors.green('wait')} (timeout: ${timeout}s) ${colors.green('✓ recommended')}
   ${colors.dim('→ talk commands will BLOCK until agent responds or timeout')}
   ${colors.dim('→ Response is returned directly, no need to use check command')}`
     : `${colors.yellow('CURRENT MODE')}: ${colors.cyan('polling')}
   ${colors.dim('→ talk commands send and return immediately')}
-  ${colors.dim('→ Use check command to read agent response')}`;
+  ${colors.dim('→ Use check command to read agent response')}
+  ${colors.dim('→')} ${colors.yellow('TIP')}: ${colors.dim('Use --wait or set mode to wait for better token utilization')}`;
 
   console.log(`
 ${colors.cyan('tmux-team')} v${VERSION} - AI agent collaboration in tmux
+${colors.dim('Alias: tmt')}
 
 ${modeInfo}
 
@@ -44,6 +56,7 @@ ${colors.yellow('COMMANDS')}
   ${colors.green('preamble')} [show|set|clear]   Manage agent preambles
   ${colors.green('install-skill')} <agent>       Install skill for AI agent
   ${colors.green('completion')}                  Output shell completion script
+  ${colors.green('learn')}                       Show educational guide
   ${colors.green('help')}                        Show this help message
 
 ${colors.yellow('OPTIONS')}

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/version.ts

@@ -14,7 +14,7 @@ function getVersion(): string {
     const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     return pkg.version;
   } catch {
-    return '3.0.0';
+    return '3.0.1';
   }
 }