tmux-team 2.1.0 → 3.0.0-alpha.1

package/README.md

@@ -2,7 +2,7 @@
 
 **The lightweight coordination layer for terminal-based AI agents.**
 
-tmux-team is a protocol-agnostic "Team Lead" that enables multi-agent collaboration directly within your existing tmux workflow. It provides the transport layer, synchronization, and project management needed to turn a collection of isolated terminal panes into a coordinated AI task force.
+tmux-team is a protocol-agnostic transport layer that enables multi-agent collaboration directly within your existing tmux workflow. It turns a collection of isolated terminal panes into a coordinated AI team.
 
 ---
 
@@ -24,7 +24,7 @@ Unlike heavyweight frameworks that require specific SDKs or cloud infrastructure
 - **Model Agnostic** — Works with Claude Code, Gemini CLI, Codex, Aider, or any CLI tool
 - **Zero Infrastructure** — No servers, no MCP setup, no complex configuration. If it runs in tmux, tmux-team can talk to it
 - **Whitelist-Friendly** — A single `tmux-team talk:*` prefix covers all operations, keeping AI tool permissions simple and safe
-- **Local-First** — Per-project `tmux-team.json` lives with your repo; global config in `~/.tmux-team/` (v2)
+- **Local-First** — Per-project `tmux-team.json` lives with your repo; global config in `~/.config/tmux-team/`
 
 ---
 
@@ -34,32 +34,24 @@ Unlike heavyweight frameworks that require specific SDKs or cloud infrastructure
 
 ### 1. Deterministic Transport (`--delay` vs. `sleep`)
 
-**The Problem**: Tool allowlists typically approve one safe command (`tmux-team talk ...`) but not arbitrary shell commands. Using `sleep` is often blocked by security policies, requires shell availability and proper quoting, and creates a separate process that's hard to manage.
+**The Problem**: Tool allowlists typically approve one safe command (`tmux-team talk ...`) but not arbitrary shell commands. Using `sleep` is often blocked by security policies.
 
-**The Why**: Internal delay keeps the workflow as a single tool call. This guarantees "First-Packet Integrity"—the CLI validates units (`500ms`, `2s`) and ensures the TTY buffer is ready to receive input specifically for that agent. No shell dependency, no policy friction.
+**The Why**: Internal delay keeps the workflow as a single tool call. No shell dependency, no policy friction.
 
 ### 2. Stateless Handshakes (The "Nonce" Strategy)
 
-**The Problem**: Terminal panes are streams, not RPC channels. A simple `[DONE]` string could already be in scrollback, or the agent might say "I'm almost done" and trigger a false positive.
+**The Problem**: Terminal panes are streams, not RPC channels. A simple `[DONE]` string could already be in scrollback.
 
-**The Why**: We use a unique **Nonce** (Number used once) for every request: `{tmux-team-end:8f3a}`.
+**The Why**: We use a unique **Nonce** for every request: `{tmux-team-end:8f3a}`.
 - **Collision Avoidance** — Prevents matching markers from previous turns
-- **Completion Safety** — Ensures the agent has truly finished, not just paused mid-response
-- **Zero-API RPC** — Creates request/response semantics over a standard TTY without requiring agents to support a special protocol
-
-Combined with one-at-a-time locking, nonce markers ensure state stays consistent and debuggable.
+- **Completion Safety** — Ensures the agent has truly finished
+- **Zero-API RPC** — Creates request/response semantics over a standard TTY
 
 ### 3. Context Injection (Preambles)
 
-**The Problem**: AI agents are prone to "instruction drift." Over a long session, they might stop using your preferred format or forget constraints. Manually re-typing system instructions is a "token tax" on your own brain.
-
-**The Why**: Preambles act as a forced system prompt for CLI environments. By injecting these "hidden instructions" at the transport level, we ensure the agent remains in character (e.g., "You are the code reviewer, do not edit files") without cluttering the human's command history. It's about reducing **Cognitive Load**—the human focuses on intent, the CLI enforces protocol.
-
-### 4. Token-Efficient Polling
-
-**The Problem**: The `--wait` feature is powerful but higher-risk: long-running commands, more state to manage, potential for hung processes.
+**The Problem**: AI agents are prone to "instruction drift." Over a long session, they might forget constraints.
 
-**The Why**: Default to the simple mental model (send → manually check). Teams opt into `--wait` when they're ready. By capturing only the last few lines of the buffer and searching for the short, high-entropy nonce, we keep overhead near zero—we're looking for a single "heartbeat" at the TTY's edge, not re-parsing the whole history.
+**The Why**: Preambles act as a forced system prompt for CLI environments. By injecting these "hidden instructions" at the transport level, we ensure the agent remains in character.
 
 ---
 
@@ -69,7 +61,7 @@ Combined with one-at-a-time locking, nonce markers ensure state stays consistent
 npm install -g tmux-team
 ```
 
-**Requirements:** Node.js >= 16, tmux, macOS/Linux
+**Requirements:** Node.js >= 18, tmux, macOS/Linux
 
 ### Shell Completion
 
@@ -139,10 +131,8 @@ Once the plugin is installed, coordinate directly from your Claude Code session:
 | `update <name> --pane/--remark` | Update agent configuration |
 | `remove <name>` | Unregister an agent |
 | `init` | Create `tmux-team.json` in current directory |
-| `pm init --name "Project"` | Initialize project management |
-| `pm m add/list/done` | Manage milestones |
-| `pm t add/list/update/done` | Manage tasks |
-| `pm log` | View audit event log |
+| `config [show/set/clear]` | View/modify settings |
+| `preamble [show/set/clear]` | Manage agent preambles |
 | `completion [zsh\|bash]` | Output shell completion script |
 
 ---
@@ -151,36 +141,58 @@ Once the plugin is installed, coordinate directly from your Claude Code session:
 
 ### Local Config (`./tmux-team.json`)
 
-Per-project agent registry:
+Per-project agent registry with optional preambles:
 
 ```json
 {
-  "claude": { "pane": "10.0", "remark": "Frontend specialist" },
-  "codex": { "pane": "10.1", "remark": "Backend engineer" }
+  "claude": {
+    "pane": "10.0",
+    "remark": "Frontend specialist",
+    "preamble": "Focus on UI components. Ask for review before merging."
+  },
+  "codex": {
+    "pane": "10.1",
+    "remark": "Code reviewer",
+    "preamble": "You are the code quality guard. Review changes thoroughly."
+  }
 }
 ```
 
+| Field | Description |
+|-------|-------------|
+| `pane` | tmux pane ID (required) |
+| `remark` | Description shown in `list` |
+| `preamble` | Hidden instructions prepended to every message |
+
 ### Global Config (`~/.config/tmux-team/config.json`)
 
+Global settings that apply to all projects:
+
 ```json
 {
   "mode": "polling",
   "preambleMode": "always",
   "defaults": {
-    "timeout": 60000,
-    "pollInterval": 1000
-  },
-  "agents": {
-    "gemini": {
-      "preamble": "Do not edit files until explicitly asked."
-    }
+    "timeout": 180,
+    "pollInterval": 1,
+    "captureLines": 100,
+    "preambleEvery": 3
   }
 }
 ```
 
+| Field | Description |
+|-------|-------------|
+| `mode` | Default mode: `polling` (manual check) or `wait` (auto-wait) |
+| `preambleMode` | `always` (inject preambles) or `disabled` |
+| `defaults.timeout` | Default --wait timeout in seconds |
+| `defaults.pollInterval` | Polling interval in seconds |
+| `defaults.captureLines` | Default lines for `check` command |
+| `defaults.preambleEvery` | Inject preamble every N messages (default: 3) |
+
 ---
 
-## ✨ v2 Features
+## ✨ Features
 
 ### 📡 Enhanced `talk` Command
 
@@ -194,32 +206,23 @@ tmux-team talk codex "message" --wait --timeout 60
 
 ### 📜 Agent Preambles
 
-Inject hidden instructions into every message:
+Inject hidden instructions into every message via local `tmux-team.json`:
 
 ```json
 {
-  "agents": {
-    "gemini": {
-      "preamble": "Always explain your reasoning. Do not edit files directly."
-    }
+  "gemini": {
+    "pane": "10.2",
+    "preamble": "Always explain your reasoning. Do not edit files directly."
   }
 }
 ```
 
-### 🎯 Project Management
+Use the CLI to manage preambles:
 
 ```bash
-# Initialize a team project
-tmux-team pm init --name "Auth Refactor"
-
-# Manage milestones and tasks
-tmux-team pm m add "MVP Release"
-tmux-team pm t add "Implement login" --milestone 1
-tmux-team pm t update 1 --status in_progress
-tmux-team pm t done 1
-
-# View audit log
-tmux-team pm log --limit 10
+tmux-team preamble show gemini      # View current preamble
+tmux-team preamble set gemini "..." # Set preamble
+tmux-team preamble clear gemini     # Remove preamble
 ```
 
 ---
@@ -228,16 +231,49 @@ tmux-team pm log --limit 10
 
 tmux-team intentionally stays lightweight:
 
-- **Not an orchestrator** — No automatic task routing or agent selection
-- **Not a session manager** — Doesn't create/manage tmux sessions or git worktrees
+- **Not an orchestrator** — No automatic agent selection or routing
+- **Not a session manager** — Doesn't create/manage tmux sessions
 - **Not an LLM wrapper** — Doesn't process or route messages through AI
 
 It's the plumbing layer that lets humans and AI agents coordinate via tmux, nothing more.
 
 ---
 
+## 📖 Command Reference
+
+### talk Options
+
+| Option | Description |
+|--------|-------------|
+| `--delay <seconds>` | Wait before sending (whitelist-friendly alternative to `sleep`) |
+| `--wait` | Block until agent responds (nonce-based completion detection) |
+| `--timeout <seconds>` | Max wait time (default: 180s) |
+| `--no-preamble` | Skip agent preamble for this message |
+
+### config Command
+
+```bash
+tmux-team config show                  # Show current config
+tmux-team config set mode wait         # Enable wait mode
+tmux-team config set preambleMode disabled  # Disable preambles
+tmux-team config set preambleEvery 5   # Inject preamble every 5 messages
+tmux-team config clear <key>           # Clear a config value
+```
+
+### preamble Command
+
+```bash
+tmux-team preamble show <agent>        # Show agent's preamble
+tmux-team preamble set <agent> "..."   # Set agent's preamble
+tmux-team preamble clear <agent>       # Clear agent's preamble
+```
+
+---
+
 *Built for developers who live in the terminal and want their AIs to do the same.*
 
+---
+
 ## License
 
 MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-team",
-  "version": "2.1.0",
+  "version": "3.0.0-alpha.1",
   "description": "CLI tool for AI agent collaboration in tmux - manage cross-pane communication",
   "type": "module",
   "bin": {

package/src/cli.ts

@@ -17,7 +17,6 @@ import { cmdRemove } from './commands/remove.js';
 import { cmdTalk } from './commands/talk.js';
 import { cmdCheck } from './commands/check.js';
 import { cmdCompletion } from './commands/completion.js';
-import { cmdPm } from './pm/commands.js';
 import { cmdConfig } from './commands/config.js';
 import { cmdPreamble } from './commands/preamble.js';
 
@@ -203,10 +202,6 @@ function main(): void {
         cmdCheck(ctx, args[0], args[1] ? parseInt(args[1], 10) : undefined);
         break;
 
-      case 'pm':
-        await cmdPm(ctx, args);
-        break;
-
       case 'config':
         cmdConfig(ctx, args);
         break;

package/src/commands/add.ts

@@ -3,9 +3,9 @@
 // ─────────────────────────────────────────────────────────────
 
 import fs from 'fs';
-import type { Context } from '../types.js';
+import type { Context, PaneEntry } from '../types.js';
 import { ExitCodes } from '../exits.js';
-import { saveLocalConfig } from '../config.js';
+import { loadLocalConfigFile, saveLocalConfigFile } from '../config.js';
 
 export function cmdAdd(ctx: Context, name: string, pane: string, remark?: string): void {
   const { ui, config, paths, flags, exit } = ctx;
@@ -23,12 +23,16 @@ export function cmdAdd(ctx: Context, name: string, pane: string, remark?: string
     exit(ExitCodes.ERROR);
   }
 
-  config.paneRegistry[name] = { pane };
+  // Load existing config to preserve all fields (preamble, deny, etc.)
+  const localConfig = loadLocalConfigFile(paths);
+
+  const newEntry: PaneEntry = { pane };
   if (remark) {
-    config.paneRegistry[name].remark = remark;
+    newEntry.remark = remark;
   }
+  localConfig[name] = newEntry;
 
-  saveLocalConfig(paths, config.paneRegistry);
+  saveLocalConfigFile(paths, localConfig);
 
   if (flags.json) {
     ui.json({ added: name, pane, remark });

package/src/commands/config.ts

@@ -13,11 +13,15 @@ import {
   clearLocalSettings,
 } from '../config.js';
 
-type ConfigKey = 'mode' | 'preambleMode';
+type EnumConfigKey = 'mode' | 'preambleMode';
+type NumericConfigKey = 'preambleEvery';
+type ConfigKey = EnumConfigKey | NumericConfigKey;
 
-const VALID_KEYS: ConfigKey[] = ['mode', 'preambleMode'];
+const ENUM_KEYS: EnumConfigKey[] = ['mode', 'preambleMode'];
+const NUMERIC_KEYS: NumericConfigKey[] = ['preambleEvery'];
+const VALID_KEYS: ConfigKey[] = [...ENUM_KEYS, ...NUMERIC_KEYS];
 
-const VALID_VALUES: Record<ConfigKey, string[]> = {
+const VALID_VALUES: Record<EnumConfigKey, string[]> = {
   mode: ['polling', 'wait'],
   preambleMode: ['always', 'disabled'],
 };
@@ -26,7 +30,15 @@ function isValidKey(key: string): key is ConfigKey {
   return VALID_KEYS.includes(key as ConfigKey);
 }
 
-function isValidValue(key: ConfigKey, value: string): boolean {
+function isEnumKey(key: ConfigKey): key is EnumConfigKey {
+  return ENUM_KEYS.includes(key as EnumConfigKey);
+}
+
+function isNumericKey(key: ConfigKey): key is NumericConfigKey {
+  return NUMERIC_KEYS.includes(key as NumericConfigKey);
+}
+
+function isValidValue(key: EnumConfigKey, value: string): boolean {
   return VALID_VALUES[key].includes(value);
 }
 
@@ -43,6 +55,7 @@ function showConfig(ctx: Context): void {
       resolved: {
         mode: ctx.config.mode,
         preambleMode: ctx.config.preambleMode,
+        preambleEvery: ctx.config.defaults.preambleEvery,
         defaults: ctx.config.defaults,
       },
       sources: {
@@ -52,6 +65,12 @@ function showConfig(ctx: Context): void {
           : globalConfig.preambleMode
             ? 'global'
             : 'default',
+        preambleEvery:
+          localSettings?.preambleEvery !== undefined
+            ? 'local'
+            : globalConfig.defaults?.preambleEvery !== undefined
+              ? 'global'
+              : 'default',
       },
       paths: {
         global: ctx.paths.globalConfig,
@@ -68,6 +87,12 @@ function showConfig(ctx: Context): void {
     : globalConfig.preambleMode
       ? '(global)'
       : '(default)';
+  const preambleEverySource =
+    localSettings?.preambleEvery !== undefined
+      ? '(local)'
+      : globalConfig.defaults?.preambleEvery !== undefined
+        ? '(global)'
+        : '(default)';
 
   ctx.ui.info('Current configuration:\n');
   ctx.ui.table(
@@ -75,6 +100,7 @@ function showConfig(ctx: Context): void {
     [
       ['mode', ctx.config.mode, modeSource],
       ['preambleMode', ctx.config.preambleMode, preambleSource],
+      ['preambleEvery', String(ctx.config.defaults.preambleEvery), preambleEverySource],
       ['defaults.timeout', String(ctx.config.defaults.timeout), '(global)'],
       ['defaults.pollInterval', String(ctx.config.defaults.pollInterval), '(global)'],
       ['defaults.captureLines', String(ctx.config.defaults.captureLines), '(global)'],
@@ -95,11 +121,25 @@ function setConfig(ctx: Context, key: string, value: string, global: boolean): v
     ctx.exit(ExitCodes.ERROR);
   }
 
-  if (!isValidValue(key, value)) {
-    ctx.ui.error(
-      `Invalid value for ${key}: ${value}. Valid values: ${VALID_VALUES[key].join(', ')}`
-    );
-    ctx.exit(ExitCodes.ERROR);
+  const validKey = key as ConfigKey;
+
+  // Validate enum keys
+  if (isEnumKey(validKey)) {
+    if (!isValidValue(validKey, value)) {
+      ctx.ui.error(
+        `Invalid value for ${key}: ${value}. Valid values: ${VALID_VALUES[validKey].join(', ')}`
+      );
+      ctx.exit(ExitCodes.ERROR);
+    }
+  }
+
+  // Validate numeric keys
+  if (isNumericKey(validKey)) {
+    const numValue = parseInt(value, 10);
+    if (isNaN(numValue) || numValue < 0) {
+      ctx.ui.error(`Invalid value for ${key}: ${value}. Must be a non-negative integer.`);
+      ctx.exit(ExitCodes.ERROR);
+    }
   }
 
   if (global) {
@@ -109,6 +149,17 @@ function setConfig(ctx: Context, key: string, value: string, global: boolean): v
       globalConfig.mode = value as 'polling' | 'wait';
     } else if (key === 'preambleMode') {
       globalConfig.preambleMode = value as 'always' | 'disabled';
+    } else if (key === 'preambleEvery') {
+      if (!globalConfig.defaults) {
+        globalConfig.defaults = {
+          timeout: 180,
+          pollInterval: 1,
+          captureLines: 100,
+          preambleEvery: parseInt(value, 10),
+        };
+      } else {
+        globalConfig.defaults.preambleEvery = parseInt(value, 10);
+      }
     }
     saveGlobalConfig(ctx.paths, globalConfig);
     ctx.ui.success(`Set ${key}=${value} in global config`);
@@ -118,6 +169,8 @@ function setConfig(ctx: Context, key: string, value: string, global: boolean): v
       updateLocalSettings(ctx.paths, { mode: value as 'polling' | 'wait' });
     } else if (key === 'preambleMode') {
       updateLocalSettings(ctx.paths, { preambleMode: value as 'always' | 'disabled' });
+    } else if (key === 'preambleEvery') {
+      updateLocalSettings(ctx.paths, { preambleEvery: parseInt(value, 10) });
     }
     ctx.ui.success(`Set ${key}=${value} in local config (repo override)`);
   }

package/src/commands/help.ts

@@ -42,7 +42,6 @@ ${colors.yellow('COMMANDS')}
   ${colors.green('init')}                        Create empty tmux-team.json
   ${colors.green('config')} [show|set|clear]     View/modify settings
   ${colors.green('preamble')} [show|set|clear]   Manage agent preambles
-  ${colors.green('pm')} <subcommand>             Project management (run 'pm help')
   ${colors.green('completion')}                  Output shell completion script
   ${colors.green('help')}                        Show this help message
 
@@ -78,6 +77,7 @@ ${colors.yellow('CONFIG')}
 ${colors.yellow('CHANGE MODE')}
   tmux-team config set mode wait            ${colors.dim('Enable wait mode (local)')}
   tmux-team config set mode polling         ${colors.dim('Enable polling mode (local)')}
-  tmux-team config set timeout 120          ${colors.dim('Set timeout to 120s')}
+  tmux-team config set preambleMode disabled ${colors.dim('Disable preambles (local)')}
+  tmux-team config set preambleEvery 5      ${colors.dim('Inject preamble every 5 messages')}
 `);
 }

package/src/commands/preamble.ts

@@ -1,10 +1,10 @@
 // ─────────────────────────────────────────────────────────────
-// Preamble command - manage agent preambles
+// Preamble command - manage agent preambles (local config only)
 // ─────────────────────────────────────────────────────────────
 
 import type { Context } from '../types.js';
 import { ExitCodes } from '../context.js';
-import { loadGlobalConfig, saveGlobalConfig } from '../config.js';
+import { loadLocalConfigFile, saveLocalConfigFile } from '../config.js';
 
 /**
  * Show preamble(s) for agent(s).
@@ -57,25 +57,27 @@ function showPreamble(ctx: Context, agentName?: string): void {
 }
 
 /**
- * Set preamble for an agent.
+ * Set preamble for an agent (in local config).
  */
 function setPreamble(ctx: Context, agentName: string, preamble: string): void {
-  const { ui, paths, flags } = ctx;
-
-  const globalConfig = loadGlobalConfig(paths);
+  const { ui, paths, flags, config } = ctx;
 
-  // Ensure agents object exists
-  if (!globalConfig.agents) {
-    globalConfig.agents = {};
+  // Check if agent exists in pane registry
+  if (!config.paneRegistry[agentName]) {
+    ui.error(`Agent '${agentName}' not found in local config`);
+    ui.error('Add the agent with: tmux-team add <agent> <pane>');
+    ctx.exit(ExitCodes.ERROR);
   }
 
-  // Ensure agent config exists
-  if (!globalConfig.agents[agentName]) {
-    globalConfig.agents[agentName] = {};
+  const localConfig = loadLocalConfigFile(paths);
+
+  // Update preamble in local config
+  const agentEntry = localConfig[agentName] as { pane: string; preamble?: string } | undefined;
+  if (agentEntry) {
+    agentEntry.preamble = preamble;
   }
 
-  globalConfig.agents[agentName].preamble = preamble;
-  saveGlobalConfig(paths, globalConfig);
+  saveLocalConfigFile(paths, localConfig);
 
   if (flags.json) {
     ui.json({ agent: agentName, preamble, status: 'set' });
@@ -85,22 +87,17 @@ function setPreamble(ctx: Context, agentName: string, preamble: string): void {
 }
 
 /**
- * Clear preamble for an agent.
+ * Clear preamble for an agent (in local config).
  */
 function clearPreamble(ctx: Context, agentName: string): void {
   const { ui, paths, flags } = ctx;
 
-  const globalConfig = loadGlobalConfig(paths);
-
-  if (globalConfig.agents?.[agentName]?.preamble) {
-    delete globalConfig.agents[agentName].preamble;
-
-    // Clean up empty agent config
-    if (Object.keys(globalConfig.agents[agentName]).length === 0) {
-      delete globalConfig.agents[agentName];
-    }
+  const localConfig = loadLocalConfigFile(paths);
+  const agentEntry = localConfig[agentName] as { pane?: string; preamble?: string } | undefined;
 
-    saveGlobalConfig(paths, globalConfig);
+  if (agentEntry?.preamble) {
+    delete agentEntry.preamble;
+    saveLocalConfigFile(paths, localConfig);
 
     if (flags.json) {
       ui.json({ agent: agentName, status: 'cleared' });

package/src/commands/remove.ts

@@ -4,7 +4,7 @@
 
 import type { Context } from '../types.js';
 import { ExitCodes } from '../exits.js';
-import { saveLocalConfig } from '../config.js';
+import { loadLocalConfigFile, saveLocalConfigFile } from '../config.js';
 
 export function cmdRemove(ctx: Context, name: string): void {
   const { ui, config, paths, flags, exit } = ctx;
@@ -14,8 +14,10 @@ export function cmdRemove(ctx: Context, name: string): void {
     exit(ExitCodes.PANE_NOT_FOUND);
   }
 
-  delete config.paneRegistry[name];
-  saveLocalConfig(paths, config.paneRegistry);
+  // Load existing config to preserve other agents' fields (preamble, deny, etc.)
+  const localConfig = loadLocalConfigFile(paths);
+  delete localConfig[name];
+  saveLocalConfigFile(paths, localConfig);
 
   if (flags.json) {
     ui.json({ removed: name });