tmux-team 2.2.0 → 3.0.0-alpha.2

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.
 
 ---
 
@@ -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**: AI agents are prone to "instruction drift." Over a long session, they might forget constraints.
 
-**The Problem**: The `--wait` feature is powerful but higher-risk: long-running commands, more state to manage, potential for hung processes.
-
-**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
 
@@ -88,6 +80,24 @@ eval "$(tmux-team completion bash)"
 /plugin install tmux-team@tmux-team
 ```
 
+### Agent Skills (Optional)
+
+Install tmux-team as a native skill for your AI coding agent:
+
+```bash
+# Install for Claude Code (user-wide)
+tmux-team install-skill claude
+
+# Install for OpenAI Codex (user-wide)
+tmux-team install-skill codex
+
+# Install to project directory instead
+tmux-team install-skill claude --local
+tmux-team install-skill codex --local
+```
+
+See [skills/README.md](./skills/README.md) for detailed instructions.
+
 ---
 
 ## ⌨️ Quick Start
@@ -139,10 +149,9 @@ 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/delete` | 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 |
+| `install-skill <agent>` | Install skill for Claude/Codex (--local/--user) |
 | `completion [zsh\|bash]` | Output shell completion script |
 
 ---
@@ -151,15 +160,14 @@ Once the plugin is installed, coordinate directly from your Claude Code session:
 
 ### Local Config (`./tmux-team.json`)
 
-Per-project agent registry with optional preambles and permissions:
+Per-project agent registry with optional preambles:
 
 ```json
 {
   "claude": {
     "pane": "10.0",
     "remark": "Frontend specialist",
-    "preamble": "Focus on UI components. Ask for review before merging.",
-    "deny": ["pm:task:update(status)"]
+    "preamble": "Focus on UI components. Ask for review before merging."
   },
   "codex": {
     "pane": "10.1",
@@ -174,7 +182,6 @@ Per-project agent registry with optional preambles and permissions:
 | `pane` | tmux pane ID (required) |
 | `remark` | Description shown in `list` |
 | `preamble` | Hidden instructions prepended to every message |
-| `deny` | Permission patterns to block (e.g., `pm:task:update(status)`) |
 
 ### Global Config (`~/.config/tmux-team/config.json`)
 
@@ -188,7 +195,7 @@ Global settings that apply to all projects:
     "timeout": 180,
     "pollInterval": 1,
     "captureLines": 100,
-    "hideOrphanTasks": false
+    "preambleEvery": 3
   }
 }
 ```
@@ -200,13 +207,11 @@ Global settings that apply to all projects:
 | `defaults.timeout` | Default --wait timeout in seconds |
 | `defaults.pollInterval` | Polling interval in seconds |
 | `defaults.captureLines` | Default lines for `check` command |
-| `defaults.hideOrphanTasks` | Hide tasks without milestone in `pm t list` |
-
-> **Note:** Agent-specific config (preamble, deny) lives in local `tmux-team.json` only.
+| `defaults.preambleEvery` | Inject preamble every N messages (default: 3) |
 
 ---
 
-## ✨ v2 Features
+## ✨ Features
 
 ### 📡 Enhanced `talk` Command
 
@@ -235,100 +240,26 @@ Use the CLI to manage preambles:
 
 ```bash
 tmux-team preamble show gemini      # View current preamble
-tmux-team preamble set gemini "..." # Set preamble
+tmux-team preamble set gemini "Be concise" # Set preamble
 tmux-team preamble clear gemini     # Remove preamble
 ```
 
-### 🔐 Agent Permissions
-
-Control what agents can do with `deny` patterns in `tmux-team.json`:
-
-```json
-{
-  "claude": {
-    "pane": "10.0",
-    "deny": ["pm:task:update(status)", "pm:milestone:update(status)"]
-  }
-}
-```
-
-Pattern format: `pm:<resource>:<action>(<fields>)`
-
-| Pattern | Effect |
-|---------|--------|
-| `pm:task:update(status)` | Block status changes only |
-| `pm:task:update(*)` | Block all task updates |
-| `pm:task:update` | Block entire update action |
-
-Permissions are enforced via pane identity—agents are identified by which tmux pane they run in, not environment variables.
-
-### 🎯 Project Management
-
-```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
-```
-
 ---
 
 ## 🚫 Non-Goals
 
 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.
 
 ---
 
-*Built for developers who live in the terminal and want their AIs to do the same.*
-
----
-
 ## 📖 Command Reference
 
-### Core Commands
-
-```
-tmux-team <command> [arguments]
-```
-
-| Command | Description |
-|---------|-------------|
-| `talk <target> <message>` | Send message to an agent (or `all` for broadcast) |
-| `check <target> [lines]` | Capture output from agent's pane (default: 100 lines) |
-| `list` | List all configured agents |
-| `add <name> <pane> [remark]` | Register a new agent |
-| `update <name> [options]` | Update an agent's config |
-| `remove <name>` | Unregister an agent |
-| `init` | Create empty `tmux-team.json` in current directory |
-| `config [show\|set\|clear]` | View/modify configuration settings |
-| `preamble [show\|set\|clear]` | Manage agent preambles |
-| `pm <subcommand>` | Project management commands |
-| `completion [zsh\|bash]` | Output shell completion script |
-| `help` | Show help message |
-
-**Aliases:** `send` = talk, `read` = check, `ls` = list, `rm` = remove
-
-### Global Options
-
-| Option | Description |
-|--------|-------------|
-| `--json` | Output in JSON format |
-| `--verbose` | Show detailed output |
-| `--force` | Skip warnings |
-
 ### talk Options
 
 | Option | Description |
@@ -342,105 +273,23 @@ tmux-team <command> [arguments]
 
 ```bash
 tmux-team config show                  # Show current config
-tmux-team config set <key> <value>     # Set a config value
 tmux-team config set mode wait         # Enable wait mode
 tmux-team config set preambleMode disabled  # Disable preambles
-tmux-team config set hideOrphanTasks true   # Hide tasks without milestone
+tmux-team config set preambleEvery 5   # Inject preamble every 5 messages
 tmux-team config clear <key>           # Clear a config value
-tmux-team config --global set ...      # Modify global config
 ```
 
 ### preamble Command
 
 ```bash
 tmux-team preamble show <agent>        # Show agent's preamble
-tmux-team preamble set <agent> "..."   # Set agent's preamble
+tmux-team preamble set <agent> "text"  # Set agent's preamble
 tmux-team preamble clear <agent>       # Clear agent's preamble
 ```
 
 ---
 
-### Project Management (`pm`)
-
-```
-tmux-team pm <subcommand>
-```
-
-**Shorthands:** `pm m` = milestone, `pm t` = task, `pm ls` = list
-
-#### pm init
-
-```bash
-tmux-team pm init --name "Project Name"
-tmux-team pm init --name "Sprint 1" --backend github --repo owner/repo
-```
-
-| Option | Description |
-|--------|-------------|
-| `--name <name>` | Project name (required) |
-| `--backend <fs\|github>` | Storage backend (default: `fs`) |
-| `--repo <owner/repo>` | GitHub repo (required for github backend) |
-
-#### pm list
-
-```bash
-tmux-team pm list                      # List all teams/projects
-tmux-team pm ls                        # Shorthand
-```
-
-#### pm milestone (shorthand: `pm m`)
-
-```bash
-tmux-team pm m                         # List all milestones
-tmux-team pm m add "Phase 1"           # Add milestone
-tmux-team pm m add "Phase 1" -d "..."  # Add with description
-tmux-team pm m list                    # List milestones
-tmux-team pm m done <id>               # Mark milestone complete
-tmux-team pm m delete <id>             # Delete milestone (or: rm)
-tmux-team pm m doc <id>                # Print milestone documentation
-tmux-team pm m doc <id> --edit         # Edit doc in $EDITOR
-tmux-team pm m doc <id> ref            # Print doc path/reference
-tmux-team pm m doc <id> --body "..."   # Set doc content directly
-tmux-team pm m doc <id> --body-file x  # Set doc content from file
-```
-
-#### pm task (shorthand: `pm t`)
-
-```bash
-tmux-team pm t                         # List all tasks
-tmux-team pm t add "Task title"        # Add task
-tmux-team pm t add "..." --milestone 1 # Add task to milestone
-tmux-team pm t add "..." --body "..."  # Add task with body
-tmux-team pm t add "..." -a @user      # Add task with assignee
-tmux-team pm t list                    # List tasks
-tmux-team pm t list --status pending   # Filter by status
-tmux-team pm t list --milestone 1      # Filter by milestone
-tmux-team pm t show <id>               # Show task details
-tmux-team pm t update <id> --status in_progress
-tmux-team pm t update <id> -a @user    # Assign task
-tmux-team pm t done <id>               # Mark task complete
-tmux-team pm t doc <id>                # Print task documentation
-tmux-team pm t doc <id> --edit         # Edit doc in $EDITOR
-tmux-team pm t doc <id> ref            # Print doc path/reference
-tmux-team pm t doc <id> --body "..."   # Set doc content directly
-tmux-team pm t doc <id> --body-file x  # Set doc content from file
-```
-
-#### pm log
-
-```bash
-tmux-team pm log                       # Show audit event log
-tmux-team pm log --limit 10            # Limit to 10 events
-```
-
----
-
-### Storage Backends
-
-| Backend | Description |
-|---------|-------------|
-| `fs` | Local filesystem (default). Tasks stored in `~/.config/tmux-team/teams/` |
-| `github` | GitHub Issues. Tasks become issues, milestones sync with GitHub |
+*Built for developers who live in the terminal and want their AIs to do the same.*
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tmux-team",
-  "version": "2.2.0",
+  "version": "3.0.0-alpha.2",
   "description": "CLI tool for AI agent collaboration in tmux - manage cross-pane communication",
   "type": "module",
   "bin": {
@@ -42,7 +42,8 @@
   ],
   "files": [
     "bin",
-    "src"
+    "src",
+    "skills"
   ],
   "dependencies": {
     "tsx": "^4.7.0"

package/skills/README.md

@@ -0,0 +1,101 @@
+# Agent Skills Installation
+
+tmux-team provides pre-built skills for popular AI coding agents.
+
+## Quick Install
+
+Use the CLI to install skills automatically:
+
+```bash
+# Install for Claude Code (user-wide)
+tmux-team install-skill claude
+
+# Install for OpenAI Codex (user-wide)
+tmux-team install-skill codex
+
+# Install to project directory (local scope)
+tmux-team install-skill claude --local
+tmux-team install-skill codex --local
+```
+
+## Claude Code
+
+Claude Code uses slash commands stored in `~/.claude/commands/` (user) or `.claude/commands/` (local).
+
+### Manual Install
+
+```bash
+mkdir -p ~/.claude/commands
+cp skills/claude/team.md ~/.claude/commands/team.md
+```
+
+### Usage
+
+```bash
+# In Claude Code, use the slash command:
+/team talk codex "Review this PR"
+
+# Or invoke implicitly - Claude will recognize when to use it
+```
+
+## OpenAI Codex CLI
+
+Codex uses skills stored in `~/.codex/skills/<skill-name>/` (user) or `.codex/skills/<skill-name>/` (local).
+
+### Manual Install
+
+```bash
+mkdir -p ~/.codex/skills/tmux-team
+cp skills/codex/SKILL.md ~/.codex/skills/tmux-team/SKILL.md
+```
+
+### Enable Skills (Required)
+
+Skills require the feature flag:
+
+```bash
+codex --enable skills
+```
+
+Or set in your config to enable by default.
+
+### Usage
+
+```bash
+# Explicit invocation
+$tmux-team talk codex "Review this PR"
+
+# Implicit - Codex auto-selects when you mention other agents
+"Ask the codex agent to review the authentication code"
+```
+
+## Gemini CLI
+
+Gemini CLI doesn't have a native skill system yet. Use the preamble feature instead:
+
+```json
+{
+  "gemini": {
+    "pane": "%2",
+    "preamble": "You can communicate with other agents using tmux-team CLI. Run `tmux-team help` to learn more."
+  }
+}
+```
+
+Save this to `tmux-team.json` in your project root.
+
+## Verify Installation
+
+After installation, verify the skill is recognized:
+
+**Claude Code:**
+```
+/help
+# Should show: /team - Talk to peer agents...
+```
+
+**Codex:**
+```
+/skills
+# Should show: tmux-team
+```

package/skills/claude/team.md

@@ -0,0 +1,46 @@
+---
+allowed-tools: Bash(tmux-team:*)
+description: Talk to peer agents in different tmux panes
+---
+
+Execute this tmux-team command: `tmux-team $ARGUMENTS`
+
+You are working in a multi-agent tmux environment.
+Use the tmux-team CLI to communicate with other agents.
+
+## Commands
+
+```bash
+# Send message to an agent
+tmux-team talk codex "your message"
+tmux-team talk gemini "your message"
+tmux-team talk all "broadcast message"
+
+# Send with delay (useful for rate limiting)
+tmux-team talk codex "message" --delay 5
+
+# Send and wait for response (blocks until agent replies)
+tmux-team talk codex "message" --wait --timeout 120
+
+# Read agent response (default: 100 lines)
+tmux-team check codex
+tmux-team check gemini 200
+
+# List all configured agents
+tmux-team list
+```
+
+## Workflow
+
+1. Send message: `tmux-team talk codex "Review this code"`
+2. Wait 5-15 seconds (or use `--wait` flag)
+3. Read response: `tmux-team check codex`
+4. If response is cut off: `tmux-team check codex 200`
+
+## Notes
+
+- `talk` automatically sends Enter key after the message
+- `talk` automatically filters exclamation marks for Gemini (TTY issue)
+- Use `--delay` instead of sleep (safer for tool whitelists)
+- Use `--wait` for synchronous request-response patterns
+- Run `tmux-team help` for full CLI documentation

package/skills/codex/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: tmux-team
+description: Communicate with other AI agents in tmux panes. Use when you need to talk to codex, claude, gemini, or other agents.
+---
+
+When invoked, execute the tmux-team command with the provided arguments.
+
+You are working in a multi-agent tmux environment.
+Use the tmux-team CLI to communicate with other agents.
+
+## Commands
+
+```bash
+# Send message to an agent
+tmux-team talk codex "your message"
+tmux-team talk gemini "your message"
+tmux-team talk all "broadcast message"
+
+# Send with delay (useful for rate limiting)
+tmux-team talk codex "message" --delay 5
+
+# Send and wait for response (blocks until agent replies)
+tmux-team talk codex "message" --wait --timeout 120
+
+# Read agent response (default: 100 lines)
+tmux-team check codex
+tmux-team check gemini 200
+
+# List all configured agents
+tmux-team list
+```
+
+## Workflow
+
+1. Send message: `tmux-team talk codex "Review this code"`
+2. Wait 5-15 seconds (or use `--wait` flag)
+3. Read response: `tmux-team check codex`
+4. If response is cut off: `tmux-team check codex 200`
+
+## Notes
+
+- `talk` automatically sends Enter key after the message
+- `talk` automatically filters exclamation marks for Gemini (TTY issue)
+- Use `--delay` instead of sleep (safer for tool whitelists)
+- Use `--wait` for synchronous request-response patterns
+- Run `tmux-team help` for full CLI documentation

package/src/cli.ts

@@ -17,9 +17,9 @@ 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';
+import { cmdInstallSkill } from './commands/install-skill.js';
 
 // ─────────────────────────────────────────────────────────────
 // Argument parsing
@@ -203,10 +203,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;
@@ -215,6 +211,24 @@ function main(): void {
         cmdPreamble(ctx, args);
         break;
 
+      case 'install-skill':
+        {
+          // Parse --local or --user flag
+          let scope = 'user';
+          const filteredArgs: string[] = [];
+          for (const arg of args) {
+            if (arg === '--local') {
+              scope = 'local';
+            } else if (arg === '--user') {
+              scope = 'user';
+            } else {
+              filteredArgs.push(arg);
+            }
+          }
+          cmdInstallSkill(ctx, filteredArgs[0], scope);
+        }
+        break;
+
       default:
         ctx.ui.error(`Unknown command: ${command}. Run 'tmux-team help' for usage.`);
         ctx.exit(ExitCodes.ERROR);