tmux-team 4.0.0-beta.0 → 4.0.0-beta.1

package/README.md

@@ -97,28 +97,125 @@ tmt ls
 tmt rm codex
 ```
 
-## Claude Code Plugin
+---
+
+## Shared Teams
+
+> *Work on different folders but talk to the same team of agents.*
+
+By default, `tmux-team.json` is local to each folder. The `--team` flag lets agents across different folders share a team:
+
+```bash
+# Initialize a shared team
+tmt init --team myproject
+
+# Register agents from ANY folder
+cd ~/code/frontend && tmt this claude --team myproject
+cd ~/code/backend && tmt this codex --team myproject
+cd ~/code/infra && tmt this gemini --team myproject
+
+# Now talk to them from anywhere
+tmt talk codex "What's the user API schema?" --team myproject
+tmt talk all "Starting deploy - heads up" --team myproject
+```
+
+> **Tip:** Most AI coding agents (Claude Code, Codex, Gemini CLI) support `!` to run shell commands. Agents can register themselves without leaving the session:
+> ```
+> !tmt this claude --team myproject
+> ```
+
+### When to use shared teams
+
+**Single project** (default) — agents work in the same folder:
+```bash
+tmt init
+tmt this claude
+tmt add codex 1.1
+```
+
+**Shared team** — agents work across folders but collaborate:
+```bash
+tmt init --team acme-app
+tmt this frontend-claude --team acme-app   # from ~/acme/frontend
+tmt this backend-codex --team acme-app     # from ~/acme/backend
+```
+
+### Multi-team coordination
+
+For large systems, create team hierarchies where leaders coordinate sub-teams:
+
+```mermaid
+flowchart
+
+A["you (claude)"]
+A2["codex"]
+A3["gemini"]
+B["backend-lead"]
+B2["codex"]
+C["infra-lead"]
+C2["codex"]
+
+subgraph your-team
+  A <--> A2
+  A <--> A3
+end
+
+A e1@<--> B
+A e2@<--> C
+
+e1@{ animate: true }
+e2@{ animate: true }
+
+subgraph backend-team
+  B <--> B2
+end
+
+subgraph infra-team
+  C <--> C2
+end
+```
+
+---
+
+## Using /team in Claude Code
+
+The `/team` command lets Claude talk to other AI agents directly. Install the plugin:
 
 ```
 /plugin marketplace add wkh237/tmux-team
 /plugin install tmux-team
 ```
 
-Gives you two slash commands:
+### /team Commands
+
+| Command | What it does |
+|---------|--------------|
+| `/team list` | Show all registered agents |
+| `/team talk <agent> "msg"` | Send a message and wait for response |
+| `/team talk all "msg"` | Broadcast to all agents |
 
-**`/learn`** - Teach Claude how to use tmux-team
+### Real-World Examples
+
+**Code review delegation:**
 ```
-/learn
+/team talk codex "Review my changes in src/auth/ for security issues"
 ```
-Run this once when starting a session. Claude will understand how to coordinate with other agents.
 
-**`/team`** - Talk to other agents
+**Cross-agent coordination:**
 ```
-/team talk codex "Review my authentication changes"
-/team talk all "I'm starting the database migration"
-/team list
+/team talk all "Starting database migration - hold off on API changes"
 ```
-Use this to delegate tasks, ask for reviews, or broadcast updates.
+
+**Ask a specialist:**
+```
+/team talk gemini "What's the best practice for rate limiting in GCP?"
+```
+
+### Tips
+
+- `/team talk` waits for the agent to respond before continuing
+- Use `/team list` to see who's available
+- Run `/learn` once per session to teach Claude the full tmux-team workflow
 
 ## Learn More
 

package/package.json

@@ -1,12 +1,25 @@
 {
   "name": "tmux-team",
-  "version": "4.0.0-beta.0",
+  "version": "4.0.0-beta.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": "pnpm test:run",
+    "test:watch": "vitest",
+    "test:run": "vitest run --coverage && node scripts/check-coverage.mjs --threshold 90 --branches 85",
+    "lint": "oxlint src/",
+    "lint:fix": "oxlint src/ --fix",
+    "format": "prettier --write src/",
+    "format:check": "prettier --check src/",
+    "type:check": "tsc --noEmit",
+    "check": "pnpm type:check && pnpm lint && pnpm format:check"
+  },
   "keywords": [
     "tmux",
     "cli",
@@ -24,6 +37,7 @@
   "engines": {
     "node": ">=18"
   },
+  "packageManager": "pnpm@9.15.4",
   "os": [
     "darwin",
     "linux"
@@ -43,18 +57,5 @@
     "prettier": "^3.7.4",
     "typescript": "^5.3.0",
     "vitest": "^1.2.0"
-  },
-  "scripts": {
-    "dev": "tsx src/cli.ts",
-    "tmt": "./bin/tmux-team",
-    "test": "pnpm test:run",
-    "test:watch": "vitest",
-    "test:run": "vitest run --coverage && node scripts/check-coverage.mjs --threshold 90 --branches 85",
-    "lint": "oxlint src/",
-    "lint:fix": "oxlint src/ --fix",
-    "format": "prettier --write src/",
-    "format:check": "prettier --check src/",
-    "type:check": "tsc --noEmit",
-    "check": "pnpm type:check && pnpm lint && pnpm format:check"
   }
-}
+}

package/src/cli.ts

@@ -59,6 +59,10 @@ function parseArgs(argv: string[]): { command: string; args: string[]; flags: Fl
       flags.lines = parseInt(argv[++i], 10) || 100;
     } else if (arg === '--no-preamble') {
       flags.noPreamble = true;
+    } else if (arg === '--team') {
+      flags.team = argv[++i];
+    } else if (arg.startsWith('--team=')) {
+      flags.team = arg.slice(7);
     } else if (arg.startsWith('--pane=')) {
       // Handled in update command
       positional.push(arg);

package/src/commands/add.ts

@@ -5,16 +5,25 @@
 import fs from 'fs';
 import type { Context, PaneEntry } from '../types.js';
 import { ExitCodes } from '../exits.js';
-import { loadLocalConfigFile, saveLocalConfigFile } from '../config.js';
+import { loadLocalConfigFile, saveLocalConfigFile, ensureTeamsDir } from '../config.js';
 
 export function cmdAdd(ctx: Context, name: string, pane: string, remark?: string): void {
   const { ui, config, paths, flags, exit } = ctx;
 
+  // Ensure teams directory exists if using --team
+  if (flags.team) {
+    ensureTeamsDir(paths.globalDir);
+  }
+
   // Create config file if it doesn't exist
   if (!fs.existsSync(paths.localConfig)) {
     fs.writeFileSync(paths.localConfig, '{}\n');
     if (!flags.json) {
-      ui.info(`Created ${paths.localConfig}`);
+      if (flags.team) {
+        ui.info(`Created shared team "${flags.team}"`);
+      } else {
+        ui.info(`Created ${paths.localConfig}`);
+      }
     }
   }
 
@@ -35,8 +44,12 @@ export function cmdAdd(ctx: Context, name: string, pane: string, remark?: string
   saveLocalConfigFile(paths, localConfig);
 
   if (flags.json) {
-    ui.json({ added: name, pane, remark });
+    ui.json({ added: name, pane, remark, team: flags.team });
   } else {
-    ui.success(`Added agent '${name}' at pane ${pane}`);
+    if (flags.team) {
+      ui.success(`Added agent '${name}' to team "${flags.team}" at pane ${pane}`);
+    } else {
+      ui.success(`Added agent '${name}' at pane ${pane}`);
+    }
   }
 }

package/src/commands/help.ts

@@ -64,6 +64,7 @@ ${colors.yellow('OPTIONS')}
   ${colors.green('--json')}                      Output in JSON format
   ${colors.green('--verbose')}                   Show detailed output
   ${colors.green('--force')}                     Skip warnings
+  ${colors.green('--team')} <name>               Use shared team (cross-folder)
 
 ${colors.yellow('TALK OPTIONS')}
   ${colors.green('--delay')} <seconds>           Wait before sending
@@ -90,6 +91,7 @@ ${colors.yellow('EXAMPLES')}${
 ${colors.yellow('CONFIG')}
   Local:  ./tmux-team.json (pane registry + $config override)
   Global: ~/.config/tmux-team/config.json (settings)
+  Teams:  ~/.config/tmux-team/teams/<name>.json (shared teams)
 
 ${colors.yellow('CHANGE MODE')}
   tmux-team config set mode wait            ${colors.dim('Enable wait mode (local)')}

package/src/commands/init.ts

@@ -1,14 +1,20 @@
 // ─────────────────────────────────────────────────────────────
-// init command - create tmux-team.json
+// init command - create tmux-team.json or shared team config
 // ─────────────────────────────────────────────────────────────
 
 import fs from 'fs';
 import type { Context } from '../types.js';
 import { ExitCodes } from '../exits.js';
+import { ensureTeamsDir } from '../config.js';
 
 export function cmdInit(ctx: Context): void {
   const { ui, paths, flags, exit } = ctx;
 
+  // Ensure teams directory exists if using --team
+  if (flags.team) {
+    ensureTeamsDir(paths.globalDir);
+  }
+
   if (fs.existsSync(paths.localConfig)) {
     ui.error(`${paths.localConfig} already exists. Remove it first if you want to reinitialize.`);
     exit(ExitCodes.ERROR);
@@ -17,8 +23,12 @@ export function cmdInit(ctx: Context): void {
   fs.writeFileSync(paths.localConfig, '{}\n');
 
   if (flags.json) {
-    ui.json({ created: paths.localConfig });
+    ui.json({ created: paths.localConfig, team: flags.team });
   } else {
-    ui.success(`Created ${paths.localConfig}`);
+    if (flags.team) {
+      ui.success(`Created shared team "${flags.team}" at ${paths.localConfig}`);
+    } else {
+      ui.success(`Created ${paths.localConfig}`);
+    }
   }
 }

package/src/commands/list.ts

@@ -9,16 +9,24 @@ export function cmdList(ctx: Context): void {
   const agents = Object.entries(config.paneRegistry);
 
   if (flags.json) {
-    ui.json(config.paneRegistry);
+    ui.json({ team: flags.team, agents: config.paneRegistry });
     return;
   }
 
   if (agents.length === 0) {
-    ui.info("No agents configured. Use 'tmux-team add <name> <pane>' to add one.");
+    if (flags.team) {
+      ui.info(`No agents in team "${flags.team}". Use 'tmt this <name> --team ${flags.team}' to add one.`);
+    } else {
+      ui.info("No agents configured. Use 'tmux-team add <name> <pane>' to add one.");
+    }
     return;
   }
 
   console.log();
+  if (flags.team) {
+    console.log(`Team: ${flags.team}`);
+    console.log();
+  }
   ui.table(
     ['NAME', 'PANE', 'REMARK'],
     agents.map(([name, data]) => [name, data.pane, data.remark || '-'])

package/src/commands/this.ts

@@ -12,7 +12,7 @@ export function cmdThis(ctx: Context, name: string, remark?: string): void {
   const currentPaneId = tmux.getCurrentPaneId();
   if (!currentPaneId) {
     ui.error('Not running inside tmux.');
-    exit(ExitCodes.ERROR);
+    return exit(ExitCodes.ERROR);
   }
 
   // Reuse existing add logic

package/src/config.ts

@@ -17,6 +17,7 @@ import type {
 const CONFIG_FILENAME = 'config.json';
 const LOCAL_CONFIG_FILENAME = 'tmux-team.json';
 const STATE_FILENAME = 'state.json';
+const TEAMS_DIR = 'teams';
 
 // Default configuration values
 const DEFAULT_CONFIG: GlobalConfig = {
@@ -102,9 +103,37 @@ function findUpward(filename: string, startDir: string): string | null {
   }
 }
 
-export function resolvePaths(cwd: string = process.cwd()): Paths {
+/**
+ * Get the path to a shared team config file.
+ */
+export function getTeamConfigPath(globalDir: string, teamName: string): string {
+  return path.join(globalDir, TEAMS_DIR, `${teamName}.json`);
+}
+
+/**
+ * Ensure the teams directory exists.
+ */
+export function ensureTeamsDir(globalDir: string): void {
+  const teamsDir = path.join(globalDir, TEAMS_DIR);
+  if (!fs.existsSync(teamsDir)) {
+    fs.mkdirSync(teamsDir, { recursive: true });
+  }
+}
+
+export function resolvePaths(cwd: string = process.cwd(), teamName?: string): Paths {
   const globalDir = resolveGlobalDir();
 
+  // If team name is specified, use the shared team config
+  if (teamName) {
+    const teamConfig = getTeamConfigPath(globalDir, teamName);
+    return {
+      globalDir,
+      globalConfig: path.join(globalDir, CONFIG_FILENAME),
+      localConfig: teamConfig,
+      stateFile: path.join(globalDir, STATE_FILENAME),
+    };
+  }
+
   // Search up for local config (like .git discovery)
   const localConfigPath =
     findUpward(LOCAL_CONFIG_FILENAME, cwd) ?? path.join(cwd, LOCAL_CONFIG_FILENAME);

package/src/context.ts

@@ -17,7 +17,7 @@ export interface CreateContextOptions {
 export function createContext(options: CreateContextOptions): Context {
   const { argv, flags, cwd = process.cwd() } = options;
 
-  const paths = resolvePaths(cwd);
+  const paths = resolvePaths(cwd, flags.team);
   const config = loadConfig(paths);
   const ui = createUI(flags.json);
   const tmux = createTmux();

package/src/tmux.ts

@@ -39,6 +39,11 @@ export function createTmux(): Tmux {
     return message.endsWith('\n') ? message : `${message}\n`;
   }
 
+  function escapeExclamation(message: string): string {
+    // Escape "!" to avoid shell history expansion issues
+    return message.replace(/!/g, '\\!');
+  }
+
   function makeBufferName(): string {
     const nonce = crypto.randomBytes(4).toString('hex');
     return `tmt-${process.pid}-${Date.now()}-${nonce}`;
@@ -48,7 +53,8 @@ export function createTmux(): Tmux {
     send(paneId: string, message: string, options?: { enterDelayMs?: number }): void {
       const enterDelayMs = Math.max(0, options?.enterDelayMs ?? 500);
       const bufferName = makeBufferName();
-      const payload = ensureTrailingNewline(message);
+      const escaped = escapeExclamation(message);
+      const payload = ensureTrailingNewline(escaped);
 
       try {
         execSync(`tmux set-buffer -b "${bufferName}" -- ${JSON.stringify(payload)}`, {

package/src/types.ts

@@ -64,6 +64,7 @@ export interface Flags {
   timeout?: number; // seconds
   lines?: number; // lines to capture before end marker
   noPreamble?: boolean;
+  team?: string; // shared team name for cross-folder collaboration
 }
 
 export interface Paths {