tmux-team 4.1.0 → 4.2.0

package/README.md

@@ -68,9 +68,12 @@ visible on both sides, use a [shared team](#shared-teams).
 | `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 agents in the current workspace (or `--team <name>`) |
+| `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 ls [--summary\|--json]` | Inspect tmux panes grouped by scope; `--summary` aggregates shared teams |
+| `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 |
 
@@ -95,13 +98,31 @@ tmt config set pasteEnterDelayMs 500
 Agent registrations live in tmux pane metadata, scoped per workspace by
 default. The same-folder workflow never needs `--team`.
 
-**List agents in this workspace:**
+**List agents and status:**
 ```bash
-tmt ls
-tmt ls --team myproject   # or list a shared team
+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
 ```
 
-**Inspect every tmux pane** with `tmt team ls`. Output is grouped by scope —
+**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:
 
@@ -121,9 +142,8 @@ PANE   TARGET             CWD              CMD
 ```
 
 ```bash
-tmt team ls               # grouped pane inventory (default)
-tmt team ls --summary     # collapse to a shared-team aggregate (TEAM / AGENTS)
-tmt team ls --json        # { teams, panes } incl. each pane's registrations
+tmt team panes        # grouped pane inventory
+tmt team panes --json # { teams, panes } incl. each pane's registrations
 ```
 
 **Add an agent from any pane.** Targets can be `%pane_id`, `window.pane`, or
@@ -213,8 +233,8 @@ tmt add codex 1.1
 ```bash
 tmt this frontend-claude --team acme-app   # from ~/acme/frontend
 tmt this backend-codex --team acme-app     # from ~/acme/backend
-tmt ls --team acme-app                     # list members
-tmt team ls --summary                      # all shared teams at a glance
+tmt team                                   # list shared teams
+tmt team ls acme-app                       # list members
 tmt team rm acme-app --force               # remove the team from every pane
 ```
 

package/package.json

@@ -1,25 +1,12 @@
 {
   "name": "tmux-team",
-  "version": "4.1.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.ts

@@ -166,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':

package/src/commands/basic-commands.test.ts

@@ -284,6 +284,98 @@ describe('basic commands', () => {
     expect(tableCall[1][0][2]).toBe('-');
   });
 
+  it('cmdList can list a shared team by positional name', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({ egp: ['claude'] });
+    (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([
+      {
+        pane: '%1',
+        target: 'main:1.0',
+        cwd: '/repo',
+        command: 'claude',
+        suggestedName: 'claude',
+        registrations: [{ scopeType: 'team', scope: 'egp', agent: 'claude' }],
+      },
+    ]);
+
+    cmdList(ctx, 'egp');
+
+    expect(ctx.ui.table).toHaveBeenCalledWith(
+      ['NAME', 'PANE', 'TARGET', 'CWD', 'CMD', 'REMARK'],
+      [['claude', '%1', 'main:1.0', '/repo', 'claude', '-']]
+    );
+  });
+
+  it('cmdList can show pane status by pane target', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.resolvePaneTarget as ReturnType<typeof vi.fn>).mockImplementation((target: string) =>
+      target === 'main:1.0' ? '%1' : null
+    );
+    (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([
+      {
+        pane: '%1',
+        target: 'main:1.0',
+        cwd: '/repo',
+        command: 'claude',
+        suggestedName: 'claude',
+        registrations: [
+          { scopeType: 'workspace', scope: '/repo', agent: 'claude' },
+          { scopeType: 'team', scope: 'egp', agent: 'reviewer', remark: 'strict' },
+        ],
+      },
+    ]);
+
+    cmdList(ctx, 'main.1.0');
+
+    expect(ctx.tmux.resolvePaneTarget).toHaveBeenCalledWith('main.1.0');
+    expect(ctx.tmux.resolvePaneTarget).toHaveBeenCalledWith('main:1.0');
+    expect(ctx.ui.table).toHaveBeenCalledWith(
+      ['SCOPE', 'NAME', 'REMARK'],
+      [
+        ['workspace:/repo', 'claude', '-'],
+        ['team:egp', 'reviewer', 'strict'],
+      ]
+    );
+  });
+
+  it('cmdList outputs pane status JSON and handles unregistered panes', () => {
+    const ctx = createCtx(testDir, { flags: { json: true } });
+    (ctx.tmux.resolvePaneTarget as ReturnType<typeof vi.fn>).mockReturnValue('%9');
+    (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([
+      {
+        pane: '%9',
+        target: 'main:9.0',
+        cwd: '/tmp',
+        command: 'zsh',
+        suggestedName: null,
+        registrations: [],
+      },
+    ]);
+
+    cmdList(ctx, '9.0');
+
+    expect((ctx.ui as any).jsonCalls).toEqual([
+      {
+        pane: {
+          pane: '%9',
+          target: 'main:9.0',
+          cwd: '/tmp',
+          command: 'zsh',
+          suggestedName: null,
+          registrations: [],
+        },
+      },
+    ]);
+  });
+
+  it('cmdList errors when positional target is neither team nor pane', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.resolvePaneTarget as ReturnType<typeof vi.fn>).mockReturnValue(null);
+
+    expect(() => cmdList(ctx, 'missing')).toThrow(`exit(${ExitCodes.PANE_NOT_FOUND})`);
+    expect(ctx.ui.error).toHaveBeenCalledWith("Pane or team 'missing' not found.");
+  });
+
   it('cmdCheck captures pane output', () => {
     const ctx = createCtx(testDir, {
       config: { paneRegistry: { claude: { pane: '1.0' } } },
@@ -299,6 +391,31 @@ describe('basic commands', () => {
     expect(() => cmdCheck(ctx, 'nope')).toThrow(`exit(${ExitCodes.PANE_NOT_FOUND})`);
   });
 
+  it('cmdCheck points at shared teams when a missing agent is only registered there', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({
+      alpha: ['codex'],
+      beta: ['codex'],
+    });
+
+    expect(() => cmdCheck(ctx, 'codex')).toThrow(`exit(${ExitCodes.PANE_NOT_FOUND})`);
+    expect(ctx.ui.error).toHaveBeenCalledWith(
+      "Agent 'codex' is in multiple shared teams: alpha, beta. Specify one with --team <team>."
+    );
+  });
+
+  it('cmdCheck points at the single shared team when there is no ambiguity', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({
+      alpha: ['codex'],
+    });
+
+    expect(() => cmdCheck(ctx, 'codex')).toThrow(`exit(${ExitCodes.PANE_NOT_FOUND})`);
+    expect(ctx.ui.error).toHaveBeenCalledWith(
+      "Agent 'codex' is in shared team 'alpha'. Specify it: tmt check codex --team alpha"
+    );
+  });
+
   it('cmdCheck errors when tmux capture fails', () => {
     const ctx = createCtx(testDir, {
       config: { paneRegistry: { claude: { pane: '1.0' } } },
@@ -468,7 +585,18 @@ describe('basic commands', () => {
     expect(ctx.ui.info).toHaveBeenCalledWith(`No legacy agents found in ${ctx.paths.localConfig}`);
   });
 
-  it('cmdTeam lists all pane team/workspace scopes', () => {
+  it('cmdTeam lists team names by default', () => {
+    const ctx = createCtx(testDir, { flags: { json: true } });
+    (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({
+      egp: ['claude', 'codex'],
+    });
+
+    cmdTeam(ctx, []);
+
+    expect((ctx.ui as any).jsonCalls).toEqual([{ teams: { egp: ['claude', 'codex'] } }]);
+  });
+
+  it('cmdTeam panes lists all pane team/workspace scopes', () => {
     const ctx = createCtx(testDir, { flags: { json: true } });
     (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({
       egp: ['claude', 'codex'],
@@ -487,7 +615,7 @@ describe('basic commands', () => {
       },
     ]);
 
-    cmdTeam(ctx, ['ls']);
+    cmdTeam(ctx, ['panes']);
 
     expect((ctx.ui as any).jsonCalls).toEqual([
       {
@@ -512,8 +640,8 @@ describe('basic commands', () => {
   it('cmdTeam shows empty state and errors on unknown subcommands', () => {
     const ctx = createCtx(testDir);
 
-    cmdTeam(ctx, ['ls']);
-    expect(ctx.ui.info).toHaveBeenCalledWith('No tmux panes found.');
+    cmdTeam(ctx, []);
+    expect(ctx.ui.info).toHaveBeenCalledWith('No shared teams found.');
 
     expect(() => cmdTeam(ctx, ['wat'])).toThrow(`exit(${ExitCodes.ERROR})`);
   });
@@ -527,7 +655,117 @@ describe('basic commands', () => {
     expect(ctx.ui.table).toHaveBeenCalledWith(['TEAM', 'AGENTS'], [['egp', 'claude']]);
   });
 
-  it('cmdTeam table groups by team/workspace scope before pane order', () => {
+  it('cmdTeam ls lists members for one team', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([
+      {
+        pane: '%2',
+        target: 'main:2.0',
+        cwd: '/repo',
+        command: 'codex',
+        suggestedName: 'codex',
+        registrations: [{ scopeType: 'team', scope: 'egp', agent: 'codex', remark: 'review' }],
+      },
+      {
+        pane: '%1',
+        target: 'main:1.0',
+        cwd: '/repo',
+        command: 'claude',
+        suggestedName: 'claude',
+        registrations: [{ scopeType: 'team', scope: 'egp', agent: 'claude' }],
+      },
+    ]);
+
+    cmdTeam(ctx, ['ls', 'egp']);
+
+    expect(ctx.ui.table).toHaveBeenCalledWith(
+      ['NAME', 'PANE', 'TARGET', 'CWD', 'CMD', 'REMARK'],
+      [
+        ['claude', '%1', 'main:1.0', '/repo', 'claude', '-'],
+        ['codex', '%2', 'main:2.0', '/repo', 'codex', 'review'],
+      ]
+    );
+  });
+
+  it('cmdTeam ls outputs JSON and reports empty teams', () => {
+    const ctx = createCtx(testDir, { flags: { json: true } });
+    (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([]);
+
+    cmdTeam(ctx, ['ls', 'missing']);
+
+    expect((ctx.ui as any).jsonCalls).toEqual([{ team: 'missing', members: [] }]);
+
+    const humanCtx = createCtx(testDir);
+    cmdTeam(humanCtx, ['ls', 'missing']);
+    expect(humanCtx.ui.info).toHaveBeenCalledWith(
+      'No agents in team "missing". Use \'tmt team add missing <name>\' to add one.'
+    );
+  });
+
+  it('cmdTeam add registers current pane in a team', () => {
+    const ctx = createCtx(testDir);
+    (ctx.tmux.getCurrentPaneId as ReturnType<typeof vi.fn>).mockReturnValue('%5');
+    (ctx.tmux.resolvePaneTarget as ReturnType<typeof vi.fn>).mockReturnValue('%5');
+
+    cmdTeam(ctx, ['add', 'egp', 'claude']);
+
+    expect(ctx.tmux.setAgentRegistration).toHaveBeenCalledWith(
+      '%5',
+      { type: 'team', teamName: 'egp' },
+      { name: 'claude' }
+    );
+  });
+
+  it('cmdTeam add supports explicit panes, remarks, JSON, and duplicate errors', () => {
+    const ctx = createCtx(testDir, { flags: { json: true } });
+    (ctx.tmux.resolvePaneTarget as ReturnType<typeof vi.fn>).mockReturnValue('%6');
+
+    cmdTeam(ctx, ['add', 'egp', 'codex', '1.2', 'reviewer']);
+
+    expect(ctx.tmux.setAgentRegistration).toHaveBeenCalledWith(
+      '%6',
+      { type: 'team', teamName: 'egp' },
+      { name: 'codex', remark: 'reviewer' }
+    );
+    expect((ctx.ui as any).jsonCalls).toEqual([
+      { added: 'codex', team: 'egp', pane: '%6', remark: 'reviewer' },
+    ]);
+
+    const duplicateCtx = createCtx(testDir);
+    (duplicateCtx.tmux.getAgentRegistry as ReturnType<typeof vi.fn>).mockReturnValue({
+      paneRegistry: { codex: { pane: '%6' } },
+      agents: {},
+    });
+    expect(() => cmdTeam(duplicateCtx, ['add', 'egp', 'codex', '1.2'])).toThrow(
+      `exit(${ExitCodes.ERROR})`
+    );
+  });
+
+  it('cmdTeam add requires a pane when outside tmux', () => {
+    const ctx = createCtx(testDir);
+
+    expect(() => cmdTeam(ctx, ['add', 'egp', 'codex'])).toThrow(`exit(${ExitCodes.ERROR})`);
+    expect(ctx.ui.error).toHaveBeenCalledWith(
+      'Not running inside tmux. Provide a pane target: tmt team add <team> <name> <pane>'
+    );
+  });
+
+  it('cmdTeam add validates arguments and pane targets', () => {
+    const ctx = createCtx(testDir);
+    expect(() => cmdTeam(ctx, ['add', 'egp'])).toThrow(`exit(${ExitCodes.ERROR})`);
+    expect(ctx.ui.error).toHaveBeenCalledWith(
+      'Usage: tmux-team team add <team> <name> [pane] [remark]'
+    );
+
+    const paneCtx = createCtx(testDir);
+    (paneCtx.tmux.resolvePaneTarget as ReturnType<typeof vi.fn>).mockReturnValue(null);
+    expect(() => cmdTeam(paneCtx, ['add', 'egp', 'codex', 'missing'])).toThrow(
+      `exit(${ExitCodes.PANE_NOT_FOUND})`
+    );
+    expect(paneCtx.ui.error).toHaveBeenCalledWith("Pane 'missing' not found. Is tmux running?");
+  });
+
+  it('cmdTeam panes table groups by team/workspace scope before pane order', () => {
     const ctx = createCtx(testDir);
     const logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
     (ctx.tmux.listTeamPanes as ReturnType<typeof vi.fn>).mockReturnValue([
@@ -565,7 +803,7 @@ describe('basic commands', () => {
       },
     ]);
 
-    cmdTeam(ctx, ['ls']);
+    cmdTeam(ctx, ['panes']);
 
     expect(logSpy.mock.calls.map((call) => call[0])).toEqual([
       'Team: alpha (gemini)',
@@ -610,6 +848,9 @@ describe('basic commands', () => {
     const ctx = createCtx(testDir);
     (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({ egp: ['claude'] });
 
+    expect(() => cmdTeam(ctx, ['rm'])).toThrow(`exit(${ExitCodes.ERROR})`);
+    expect(ctx.ui.error).toHaveBeenCalledWith('Usage: tmux-team team rm <team> --force');
+
     expect(() => cmdTeam(ctx, ['rm', 'egp'])).toThrow(`exit(${ExitCodes.ERROR})`);
 
     (ctx.tmux.listTeams as ReturnType<typeof vi.fn>).mockReturnValue({});

package/src/commands/check.ts

@@ -6,11 +6,31 @@ import type { Context } from '../types.js';
 import { ExitCodes } from '../exits.js';
 import { colors } from '../ui.js';
 
+function teamHintForMissingAgent(ctx: Context, target: string): string | null {
+  if (ctx.flags.team) return null;
+
+  const matches = Object.entries(ctx.tmux.listTeams())
+    .filter(([, agents]) => agents.includes(target))
+    .map(([teamName]) => teamName)
+    .sort();
+
+  if (matches.length === 0) return null;
+  if (matches.length === 1) {
+    return `Agent '${target}' is in shared team '${matches[0]}'. Specify it: tmt check ${target} --team ${matches[0]}`;
+  }
+  return `Agent '${target}' is in multiple shared teams: ${matches.join(', ')}. Specify one with --team <team>.`;
+}
+
 export function cmdCheck(ctx: Context, target: string, lines?: number): void {
   const { ui, config, tmux, flags, exit } = ctx;
 
   if (!config.paneRegistry[target]) {
     const available = Object.keys(config.paneRegistry).join(', ');
+    const teamHint = teamHintForMissingAgent(ctx, target);
+    if (teamHint) {
+      ui.error(teamHint);
+      exit(ExitCodes.PANE_NOT_FOUND);
+    }
     ui.error(`Agent '${target}' not found. Available: ${available || 'none'}`);
     exit(ExitCodes.PANE_NOT_FOUND);
   }

package/src/commands/help.ts

@@ -47,13 +47,13 @@ ${colors.yellow('USAGE')}
 ${colors.yellow('COMMANDS')}
   ${colors.green('talk')} <target> <message>     Send message to an agent (or "all")
   ${colors.green('check')} <target> [lines]      Capture output from agent's pane
-  ${colors.green('list')}                        List all configured agents
+  ${colors.green('list')} [team|pane]             List workspace, team, or pane status
   ${colors.green('add')} <name> <pane> [remark]  Add a new agent
   ${colors.green('this')} <name> [remark]       Register current pane as an agent
   ${colors.green('update')} <name> [options]     Update an agent's config
   ${colors.green('remove')} <name>               Remove an agent
   ${colors.green('migrate')} [--dry-run]          Copy legacy JSON registry to tmux metadata
-  ${colors.green('team')} [ls|rm]                 Inspect pane scopes and manage teams
+  ${colors.green('team')} [ls|add|rm|panes]       Manage shared teams
   ${colors.green('install')} [claude|codex]       Install tmux-team for an AI agent
   ${colors.green('init')}                        Create empty tmux-team.json
   ${colors.green('config')} [show|set|clear]     View/modify settings
@@ -88,13 +88,15 @@ ${colors.yellow('EXAMPLES')}${
   tmux-team check codex                     ${colors.dim('← read response later')}`
   }
   tmux-team list --json
+  tmux-team list acme-app
+  tmux-team list main.1.0
   tmux-team add codex 10.1 "Code review specialist"
 
 ${colors.yellow('CONFIG')}
   Runtime: tmux pane metadata (agent registry)
   Local:  ./tmux-team.json (legacy registry + $config override)
   Global: ~/.config/tmux-team/config.json (settings)
-  Teams:  tmux pane metadata; team ls shows pane cwd + workspace/team scopes
+  Teams:  tmux pane metadata; team panes shows cwd + workspace/team scopes
 
 ${colors.yellow('CHANGE MODE')}
   tmux-team config set mode wait            ${colors.dim('Enable wait mode (local)')}

package/src/commands/list.ts

@@ -3,9 +3,22 @@
 // ─────────────────────────────────────────────────────────────
 
 import type { Context } from '../types.js';
+import { listPaneStatus, listTeamMembers } from './team.js';
 
-export function cmdList(ctx: Context): void {
+export function cmdList(ctx: Context, target?: string): void {
   const { ui, config, flags } = ctx;
+
+  if (target) {
+    const teams = ctx.tmux.listTeams();
+    if (teams[target]) {
+      listTeamMembers(ctx, [target]);
+      return;
+    }
+
+    listPaneStatus(ctx, target);
+    return;
+  }
+
   const agents = Object.entries(config.paneRegistry);
 
   if (flags.json) {

package/src/commands/talk.test.ts

@@ -468,6 +468,27 @@ describe('cmdTalk - basic send', () => {
     expect(ui.errors[0]).toContain("Agent 'unknown' not found");
   });
 
+  it('requires explicit team when a missing agent appears in shared teams', async () => {
+    const tmux = createMockTmux();
+    vi.spyOn(tmux, 'listTeams').mockReturnValue({
+      frontend: ['codex'],
+      release: ['codex'],
+    });
+    const ui = createMockUI();
+    const ctx = createContext({
+      tmux,
+      ui,
+      paths: createTestPaths(testDir),
+      config: { paneRegistry: {} },
+    });
+
+    await expect(cmdTalk(ctx, 'codex', 'Hello')).rejects.toThrow('exit(3)');
+
+    expect(ui.errors).toEqual([
+      "Agent 'codex' is in multiple shared teams: frontend, release. Specify one with --team <team>.",
+    ]);
+  });
+
   it('outputs JSON when --json flag is set', async () => {
     const tmux = createMockTmux();
     const ui = createMockUI();

package/src/commands/talk.ts

@@ -319,6 +319,21 @@ function buildMessage(message: string, agentName: string, ctx: Context): string
   return `[SYSTEM: ${preamble}]\n\n${message}`;
 }
 
+function teamHintForMissingAgent(ctx: Context, target: string): string | null {
+  if (ctx.flags.team) return null;
+
+  const matches = Object.entries(ctx.tmux.listTeams())
+    .filter(([, agents]) => agents.includes(target))
+    .map(([teamName]) => teamName)
+    .sort();
+
+  if (matches.length === 0) return null;
+  if (matches.length === 1) {
+    return `Agent '${target}' is in shared team '${matches[0]}'. Specify it: tmt talk ${target} "..." --team ${matches[0]}`;
+  }
+  return `Agent '${target}' is in multiple shared teams: ${matches.join(', ')}. Specify one with --team <team>.`;
+}
+
 export async function cmdTalk(ctx: Context, target: string, message: string): Promise<void> {
   const { ui, config, tmux, flags, exit } = ctx;
   const waitEnabled = Boolean(flags.wait) || config.mode === 'wait';
@@ -389,6 +404,11 @@ export async function cmdTalk(ctx: Context, target: string, message: string): Pr
   // Single agent
   if (!config.paneRegistry[target]) {
     const available = Object.keys(config.paneRegistry).join(', ');
+    const teamHint = teamHintForMissingAgent(ctx, target);
+    if (teamHint) {
+      ui.error(teamHint);
+      exit(ExitCodes.PANE_NOT_FOUND);
+    }
     ui.error(`Agent '${target}' not found. Available: ${available || 'none'}`);
     exit(ExitCodes.PANE_NOT_FOUND);
   }

package/src/commands/team.ts

@@ -2,44 +2,57 @@
 // team command - inspect pane team/workspace scope and manage explicit shared teams
 // ─────────────────────────────────────────────────────────────
 
-import type { Context, TeamPaneInfo, TeamPaneRegistration } from '../types.js';
+import type { Context, RegistryScope, TeamPaneInfo, TeamPaneRegistration } from '../types.js';
 import { ExitCodes } from '../exits.js';
+import { registrationFromEntry } from '../registry.js';
 
 export function cmdTeam(ctx: Context, args: string[]): void {
-  const subcommand = args[0] ?? 'ls';
+  const subcommand = args[0];
 
   switch (subcommand) {
+    case undefined:
+      listTeamNames(ctx, []);
+      break;
     case 'ls':
     case 'list':
-      listTeams(ctx, args.slice(1));
+      listTeamMembers(ctx, args.slice(1));
+      break;
+    case 'add':
+      addTeamMember(ctx, args.slice(1));
       break;
     case 'rm':
     case 'remove':
       removeTeam(ctx, args.slice(1));
       break;
+    case 'panes':
+    case 'inventory':
+      listPaneInventory(ctx, args.slice(1));
+      break;
     default:
       ctx.ui.error(`Unknown team subcommand: ${subcommand}`);
-      ctx.ui.error('Usage: tmux-team team [ls [--summary]|rm <team> --force]');
+      ctx.ui.error(
+        'Usage: tmux-team team [ls <team>|add <team> <name> [pane]|rm <team> --force|panes]'
+      );
       ctx.exit(ExitCodes.ERROR);
   }
 }
 
-function listTeams(ctx: Context, args: string[]): void {
+function listTeamNames(ctx: Context, args: string[]): void {
   const teams = ctx.tmux.listTeams();
-  const panes = ctx.tmux.listTeamPanes();
   const summaryOnly = args.includes('--summary');
 
   if (ctx.flags.json) {
-    ctx.ui.json({ teams, panes });
+    ctx.ui.json({ teams });
+    return;
+  }
+
+  const rows = Object.entries(teams).sort(([a], [b]) => a.localeCompare(b));
+  if (rows.length === 0) {
+    ctx.ui.info('No shared teams found.');
     return;
   }
 
   if (summaryOnly) {
-    const rows = Object.entries(teams).sort(([a], [b]) => a.localeCompare(b));
-    if (rows.length === 0) {
-      ctx.ui.info('No shared teams found.');
-      return;
-    }
     ctx.ui.table(
       ['TEAM', 'AGENTS'],
       rows.map(([teamName, agents]) => [teamName, agents.join(', ') || '-'])
@@ -47,6 +60,92 @@ function listTeams(ctx: Context, args: string[]): void {
     return;
   }
 
+  ctx.ui.table(
+    ['TEAM', 'MEMBERS'],
+    rows.map(([teamName, agents]) => [teamName, String(agents.length)])
+  );
+}
+
+export function listTeamMembers(ctx: Context, args: string[]): void {
+  const teamName = args.find((arg) => !arg.startsWith('-'));
+  if (!teamName) {
+    listTeamNames(ctx, args);
+    return;
+  }
+
+  const rows = teamMemberRows(ctx.tmux.listTeamPanes(), teamName);
+  if (ctx.flags.json) {
+    ctx.ui.json({ team: teamName, members: rows.map(rowToMemberJson) });
+    return;
+  }
+
+  if (rows.length === 0) {
+    ctx.ui.info(
+      `No agents in team "${teamName}". Use 'tmt team add ${teamName} <name>' to add one.`
+    );
+    return;
+  }
+
+  ctx.ui.table(['NAME', 'PANE', 'TARGET', 'CWD', 'CMD', 'REMARK'], rows);
+}
+
+function addTeamMember(ctx: Context, args: string[]): void {
+  const [teamName, name, maybePane, ...remarkParts] = args.filter((arg) => !arg.startsWith('-'));
+  if (!teamName || !name) {
+    ctx.ui.error('Usage: tmux-team team add <team> <name> [pane] [remark]');
+    ctx.exit(ExitCodes.ERROR);
+  }
+
+  const scope: RegistryScope = { type: 'team', teamName };
+  const registry = ctx.tmux.getAgentRegistry(scope);
+  if (registry.paneRegistry[name]) {
+    ctx.ui.error(
+      `Agent '${name}' already exists in team '${teamName}'. Use 'tmux-team update --team ${teamName}' to modify.`
+    );
+    ctx.exit(ExitCodes.ERROR);
+  }
+
+  const targetPane = maybePane ?? ctx.tmux.getCurrentPaneId();
+  if (!targetPane) {
+    ctx.ui.error(
+      'Not running inside tmux. Provide a pane target: tmt team add <team> <name> <pane>'
+    );
+    ctx.exit(ExitCodes.ERROR);
+  }
+
+  const resolvedPane = ctx.tmux.resolvePaneTarget(targetPane);
+  if (!resolvedPane) {
+    ctx.ui.error(`Pane '${targetPane}' not found. Is tmux running?`);
+    ctx.exit(ExitCodes.PANE_NOT_FOUND);
+  }
+
+  const remark = remarkParts.length > 0 ? remarkParts.join(' ') : undefined;
+  ctx.tmux.setAgentRegistration(
+    resolvedPane,
+    scope,
+    registrationFromEntry(name, {
+      pane: resolvedPane,
+      ...(remark !== undefined && { remark }),
+    })
+  );
+
+  if (ctx.flags.json) {
+    ctx.ui.json({ added: name, team: teamName, pane: resolvedPane, remark });
+    return;
+  }
+
+  ctx.ui.success(`Added agent '${name}' to team '${teamName}' at pane ${resolvedPane}`);
+}
+
+function listPaneInventory(ctx: Context, _args: string[]): void {
+  const teams = ctx.tmux.listTeams();
+  const panes = ctx.tmux.listTeamPanes();
+
+  if (ctx.flags.json) {
+    ctx.ui.json({ teams, panes });
+    return;
+  }
+
   const groups = panesToGroups(panes);
   if (groups.length === 0) {
     ctx.ui.info('No tmux panes found.');
@@ -60,6 +159,96 @@ function listTeams(ctx: Context, args: string[]): void {
   }
 }
 
+export function listPaneStatus(ctx: Context, target: string): void {
+  const resolvedPane = resolvePaneLike(ctx, target);
+  if (!resolvedPane) {
+    ctx.ui.error(`Pane or team '${target}' not found.`);
+    ctx.exit(ExitCodes.PANE_NOT_FOUND);
+  }
+
+  const pane = ctx.tmux.listTeamPanes().find((item) => item.pane === resolvedPane);
+  if (!pane) {
+    ctx.ui.error(`Pane '${target}' not found.`);
+    ctx.exit(ExitCodes.PANE_NOT_FOUND);
+  }
+
+  if (ctx.flags.json) {
+    ctx.ui.json({ pane });
+    return;
+  }
+
+  console.log(`Pane: ${pane.pane}${pane.target ? ` (${pane.target})` : ''}`);
+  console.log(`CWD:  ${pane.cwd ?? '-'}`);
+  console.log(`CMD:  ${pane.command || '-'}`);
+
+  if (pane.registrations.length === 0) {
+    ctx.ui.info('No registrations on this pane.');
+    return;
+  }
+
+  ctx.ui.table(
+    ['SCOPE', 'NAME', 'REMARK'],
+    pane.registrations.map((registration) => [
+      registration.scopeType === 'team'
+        ? `team:${registration.scope}`
+        : `workspace:${registration.scope}`,
+      registration.agent,
+      registration.remark ?? '-',
+    ])
+  );
+}
+
+function resolvePaneLike(ctx: Context, target: string): string | null {
+  const candidates = [target];
+  const dotted = target.match(/^([^.]+)\.([^.]+)\.([^.]+)$/);
+  if (dotted) {
+    candidates.push(`${dotted[1]}:${dotted[2]}.${dotted[3]}`);
+  }
+
+  for (const candidate of candidates) {
+    const resolved = ctx.tmux.resolvePaneTarget(candidate);
+    if (resolved) return resolved;
+  }
+
+  return null;
+}
+
+function teamMemberRows(panes: TeamPaneInfo[], teamName: string): string[][] {
+  const rows: string[][] = [];
+  for (const pane of panes) {
+    for (const registration of pane.registrations) {
+      if (registration.scopeType !== 'team' || registration.scope !== teamName) continue;
+      rows.push([
+        registration.agent,
+        pane.pane,
+        pane.target ?? '-',
+        pane.cwd ?? '-',
+        pane.command || '-',
+        registration.remark ?? '-',
+      ]);
+    }
+  }
+  return rows.sort((a, b) => a[0].localeCompare(b[0]) || a[1].localeCompare(b[1]));
+}
+
+function rowToMemberJson(row: string[]): {
+  name: string;
+  pane: string;
+  target: string;
+  cwd: string;
+  command: string;
+  remark?: string;
+} {
+  return {
+    name: row[0],
+    pane: row[1],
+    target: row[2],
+    cwd: row[3],
+    command: row[4],
+    ...(row[5] !== '-' && { remark: row[5] }),
+  };
+}
+
 interface PaneGroup {
   key: string;
   title: string;