tmux-team 4.0.0 → 4.2.0

package/README.md

@@ -18,26 +18,35 @@ npm install -g tmux-team
 # 1. Install for your AI agent
 tmt install claude   # or: tmt install codex
 
-# 2. Go to working folder and initialize
-tmt init
-
-# 3. Register agents (run inside each agent's pane)
+# 2. Go to working folder and register agents (run inside each agent's pane)
 tmt this claude      # registers current pane as "claude"
 tmt this codex       # registers current pane as "codex"
 
-# 4. Talk to agents
+# 3. Talk to agents
 tmt talk codex "Review this code"    # waits for response by default
 
-# 5. Update or remove an agent
+# 4. Update or remove an agent
 tmt update codex --pane 2.3
 tmt rm codex
 ```
 
 > **Tip:** Most AI agents support `!` to run bash commands. From inside Claude Code, Codex, or Gemini CLI, you can run `!tmt this myname` to quickly register that pane.
 
+### How scopes work
+
+Registrations live in tmux pane metadata, not in a JSON file you have to track.
+By default they are scoped to the current **workspace** — the nearest Git root,
+or the current folder when you are not inside a Git repo. So `tmt this`,
+`tmt add`, `tmt rm`, `tmt update`, `tmt preamble`, and `tmt list` all act on
+the workspace you are currently in.
+
+Reach for `--team <name>` only when you want an explicit shared team that spans
+folders (see [Shared Teams](#shared-teams)).
+
 ## Cross-Folder Collaboration
 
-Agents don't need to be in the same folder to collaborate. You can add an agent from one project to another:
+Agents don't need to be in the same folder to collaborate. From your current
+workspace you can add an agent whose pane lives in another project:
 
 ```bash
 # In project-a folder, add an agent that's running in project-b
@@ -46,6 +55,10 @@ tmt add codex-reviewer 5.1    # Use the pane ID from the other project
 
 Find pane IDs with: `tmux display-message -p "#{pane_id}"`
 
+This still uses the default workspace scope: the registration is visible from
+project-a, not from project-b. For long-running collaboration that should be
+visible on both sides, use a [shared team](#shared-teams).
+
 ## Commands
 
 | Command | Description |
@@ -55,7 +68,13 @@ Find pane IDs with: `tmux display-message -p "#{pane_id}"`
 | `talk <agent> "msg"` | Send message and wait for response |
 | `talk all "msg"` | Broadcast to all agents |
 | `check <agent> [lines]` | Read agent's pane output |
-| `list` | Show configured agents |
+| `list [team\|pane]` | Show current workspace agents, one shared team, or one pane's registrations |
+| `migrate [--dry-run] [--cleanup]` | Move legacy `tmux-team.json` entries into tmux pane metadata |
+| `team` | List shared team names |
+| `team ls <team>` | List members of a shared team |
+| `team add <team> <name> [pane]` | Add current or specified pane to a shared team |
+| `team panes [--json]` | Inspect tmux panes grouped by scope |
+| `team rm <team> --force` | Remove a shared team registration from every pane |
 | `learn` | Show educational guide |
 
 **Options for `talk`:**
@@ -76,39 +95,117 @@ tmt config set pasteEnterDelayMs 500
 
 ## Managing Your Team
 
-Configuration lives in `tmux-team.json` in your project root.
+Agent registrations live in tmux pane metadata, scoped per workspace by
+default. The same-folder workflow never needs `--team`.
+
+**List agents and status:**
+```bash
+tmt ls              # agents in this workspace
+tmt ls myproject    # members of a shared team
+tmt ls 10.1         # registrations on a pane
+tmt ls main.10.1    # shorthand for main:10.1
+```
+
+**Manage shared teams** with the `team` namespace:
+
+```bash
+tmt team                         # list shared team names
+tmt team ls myproject            # list team members
+tmt team add myproject claude    # add current pane to a team
+tmt team add myproject codex 1.1 # add a specific pane to a team
+tmt team rm myproject --force    # remove a team from every pane
+```
+
+A single pane can belong to multiple teams. Commands never guess across teams:
+`tmt talk codex` uses the current workspace, while `tmt talk codex --team
+myproject` uses only that shared team. If an agent name appears in multiple
+shared teams and is not in the current workspace, tmux-team asks you to specify
+the team.
+
+**Inspect every tmux pane** with `tmt team panes`. Output is grouped by scope —
+shared teams first, then workspaces, then unregistered panes — and each
+section's title lists the agents living there:
+
+```
+Team: acme-app (codex, gemini)
+PANE   TARGET             CWD              CMD
+%12    main:1.0           ~/acme/frontend  node
+%17    main:2.0           ~/acme/backend   python
+
+Workspace: ~/dev/tmux-team (claude)
+PANE   TARGET             CWD              CMD
+%3     work:0.1           ~/dev/tmux-team  node
+
+Unregistered panes
+PANE   TARGET             CWD              CMD
+%9     misc:0.0           ~/scratch        zsh
+```
 
-**List** - Show configured agents:
 ```bash
-tmt ls
+tmt team panes        # grouped pane inventory
+tmt team panes --json # { teams, panes } incl. each pane's registrations
 ```
 
-**Edit** - Modify `tmux-team.json` directly:
-```json
-{
-  "$config": { "pasteEnterDelayMs": 500 },
-  "codex": { "pane": "1.1", "remark": "Code reviewer" },
-  "gemini": { "pane": "1.2", "remark": "Documentation" }
-}
+**Add an agent from any pane.** Targets can be `%pane_id`, `window.pane`, or
+`session:window.pane`; tmux-team stores the canonical `%pane_id`.
+
+```bash
+tmt add codex 1.1 "Code reviewer"
 ```
 
-**Remove** - Delete an agent:
+**Remove an agent** from the current scope:
 ```bash
 tmt rm codex
 ```
 
+**Migrate from legacy `tmux-team.json`.** Versions before v4 stored agents in
+a JSON file. `tmt migrate` copies those entries into tmux pane metadata so the
+new commands can see them. Run it once per project that still has the file:
+
+```bash
+tmt migrate --dry-run     # preview what would move
+tmt migrate               # move entries into tmux metadata
+tmt migrate --cleanup     # also delete the migrated entries from the JSON file
+```
+
+`tmux-team.json` is still loaded as a fallback when no tmux metadata exists,
+and it remains the home for local `$config` overrides. If you don't use it,
+you can ignore it.
+
 ---
 
+## Agent Preambles
+
+Set a per-agent preamble to steer behavior (stored with the pane registration):
+
+```bash
+tmt preamble set codex "You are the code quality guard. Be strict."
+```
+
+### What Happens When a Preamble Is Set
+
+When you send a message, tmux-team injects the preamble like this:
+
+```
+[SYSTEM: You are the code quality guard. Be strict.]
+
+Review the login flow changes.
+```
+
+Control how often it’s injected with `preambleEvery`:
+
+```bash
+tmt config set preambleEvery 3
+```
+
 ## 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:
+By default, registrations are scoped to the current workspace. The `--team` flag
+creates an explicit shared team that works across folders:
 
 ```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
@@ -128,16 +225,17 @@ tmt talk all "Starting deploy - heads up" --team myproject
 
 **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
+tmt team                                   # list shared teams
+tmt team ls acme-app                       # list members
+tmt team rm acme-app --force               # remove the team from every pane
 ```
 
 ### Multi-team coordination

package/package.json

@@ -1,25 +1,12 @@
 {
   "name": "tmux-team",
-  "version": "4.0.0",
+  "version": "4.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": "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",
@@ -37,7 +24,6 @@
   "engines": {
     "node": ">=18"
   },
-  "packageManager": "pnpm@9.15.4",
   "os": [
     "darwin",
     "linux"
@@ -57,5 +43,18 @@
     "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.test.ts

@@ -16,7 +16,14 @@ function makeStubContext(): Context {
     config: {
       mode: 'polling',
       preambleMode: 'always',
-      defaults: { timeout: 180, pollInterval: 1, captureLines: 100, maxCaptureLines: 2000, preambleEvery: 3, pasteEnterDelayMs: 500 },
+      defaults: {
+        timeout: 180,
+        pollInterval: 1,
+        captureLines: 100,
+        maxCaptureLines: 2000,
+        preambleEvery: 3,
+        pasteEnterDelayMs: 500,
+      },
       agents: {},
       paneRegistry: {},
     },
@@ -25,6 +32,13 @@ function makeStubContext(): Context {
       capture: vi.fn(),
       listPanes: vi.fn(() => []),
       getCurrentPaneId: vi.fn(() => null),
+      resolvePaneTarget: vi.fn((target: string) => target),
+      getAgentRegistry: vi.fn(() => ({ paneRegistry: {}, agents: {} })),
+      setAgentRegistration: vi.fn(),
+      clearAgentRegistration: vi.fn(() => false),
+      listTeams: vi.fn(() => ({})),
+      listTeamPanes: vi.fn(() => []),
+      removeTeam: vi.fn(() => ({ removed: 0, agents: [] })),
     },
     paths: {
       globalDir: '/g',

package/src/cli.ts

@@ -22,6 +22,8 @@ import { cmdPreamble } from './commands/preamble.js';
 import { cmdInstall } from './commands/install.js';
 import { cmdLearn } from './commands/learn.js';
 import { cmdThis } from './commands/this.js';
+import { cmdMigrate } from './commands/migrate.js';
+import { cmdTeam } from './commands/team.js';
 
 // ─────────────────────────────────────────────────────────────
 // Argument parsing
@@ -164,7 +166,11 @@ function main(): void {
 
       case 'list':
       case 'ls':
-        cmdList(ctx);
+        if (args[0] === undefined) {
+          cmdList(ctx);
+        } else {
+          cmdList(ctx, args[0]);
+        }
         break;
 
       case 'add':
@@ -206,6 +212,14 @@ function main(): void {
         cmdRemove(ctx, args[0]);
         break;
 
+      case 'migrate':
+        cmdMigrate(ctx, args);
+        break;
+
+      case 'team':
+        cmdTeam(ctx, args);
+        break;
+
       case 'this':
         if (args.length < 1) {
           ctx.ui.error('Usage: tmux-team this <name> [remark]');

package/src/commands/add.ts

@@ -2,54 +2,39 @@
 // add command - register a new agent
 // ─────────────────────────────────────────────────────────────
 
-import fs from 'fs';
-import type { Context, PaneEntry } from '../types.js';
+import type { Context } from '../types.js';
 import { ExitCodes } from '../exits.js';
-import { loadLocalConfigFile, saveLocalConfigFile, ensureTeamsDir } from '../config.js';
+import { getRegistryScope, registrationFromEntry } from '../registry.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) {
-      if (flags.team) {
-        ui.info(`Created shared team "${flags.team}"`);
-      } else {
-        ui.info(`Created ${paths.localConfig}`);
-      }
-    }
-  }
+  const { ui, config, tmux, flags, exit } = ctx;
 
   if (config.paneRegistry[name]) {
     ui.error(`Agent '${name}' already exists. Use 'tmux-team update' to modify.`);
     exit(ExitCodes.ERROR);
   }
 
-  // Load existing config to preserve all fields (preamble, deny, etc.)
-  const localConfig = loadLocalConfigFile(paths);
-
-  const newEntry: PaneEntry = { pane };
-  if (remark) {
-    newEntry.remark = remark;
+  const resolvedPane = tmux.resolvePaneTarget(pane);
+  if (!resolvedPane) {
+    ui.error(`Pane '${pane}' not found. Is tmux running?`);
+    exit(ExitCodes.PANE_NOT_FOUND);
   }
-  localConfig[name] = newEntry;
+  const paneId = resolvedPane as string;
 
-  saveLocalConfigFile(paths, localConfig);
+  const scope = getRegistryScope(ctx);
+  const registration = registrationFromEntry(name, {
+    pane: paneId,
+    ...(remark !== undefined && { remark }),
+  });
+  tmux.setAgentRegistration(paneId, scope, registration);
 
   if (flags.json) {
-    ui.json({ added: name, pane, remark, team: flags.team });
+    ui.json({ added: name, pane: paneId, remark, team: flags.team });
   } else {
     if (flags.team) {
-      ui.success(`Added agent '${name}' to team "${flags.team}" at pane ${pane}`);
+      ui.success(`Added agent '${name}' to team "${flags.team}" at pane ${paneId}`);
     } else {
-      ui.success(`Added agent '${name}' at pane ${pane}`);
+      ui.success(`Added agent '${name}' at pane ${paneId}`);
     }
   }
 }