ntm

What this skill does

# NTM — Named Tmux Manager

A Go CLI that transforms tmux into a **multi-agent command center** for orchestrating Claude Code, Codex, and Gemini agents in parallel. Spawn, manage, and coordinate AI agents across tiled panes with stunning TUI, automated context rotation, and deep integrations with the Agent Flywheel ecosystem.

## Why This Exists

Managing multiple AI coding agents is painful:
- **Window chaos**: Each agent needs its own terminal
- **Context switching**: Jumping between windows breaks flow
- **No orchestration**: Same prompt to multiple agents requires manual copy-paste
- **Session fragility**: Disconnecting from SSH loses all agent sessions
- **No visibility**: Hard to see agent status at a glance

NTM solves all of this with one session containing many agents, persistent across SSH disconnections.

## Quick Start

```bash
# Install
curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh | bash

# Add shell integration
echo 'eval "$(ntm init zsh)"' >> ~/.zshrc && source ~/.zshrc

# Interactive tutorial
ntm tutorial

# Check dependencies
ntm deps -v

# Create multi-agent session
ntm spawn myproject --cc=2 --cod=1 --gmi=1

# Send prompt to all Claude agents
ntm send myproject --cc "Explore this codebase and summarize its architecture."

# Open command palette (or press F6 after `ntm bind`)
ntm palette myproject
```

## Session Creation

### Spawn Agents

```bash
ntm spawn myproject --cc=3 --cod=2 --gmi=1   # 3 Claude + 2 Codex + 1 Gemini
ntm quick myproject --template=go             # Full project scaffold + agents
ntm create myproject --panes=10               # Empty panes only
ntm spawn myproject --profiles=architect,implementer,tester
```

### Agent Flags

| Flag | Agent | CLI Command |
|------|-------|-------------|
| `--cc=N` | Claude Code | `claude` |
| `--cod=N` | Codex CLI | `codex` |
| `--gmi=N` | Gemini CLI | `gemini` |

### Add More Agents

```bash
ntm add myproject --cc=2              # Add 2 more Claude agents
ntm add myproject --cod=1 --gmi=1     # Add mixed agents
```

## Sending Prompts

```bash
ntm send myproject --cc "Implement user auth"     # To all Claude
ntm send myproject --cod "Write unit tests"       # To all Codex
ntm send myproject --gmi "Review and document"    # To all Gemini
ntm send myproject --all "Review current state"   # To ALL agents
ntm interrupt myproject                           # Ctrl+C to all
```

## Session Navigation

| Command | Alias | Description |
|---------|-------|-------------|
| `ntm list` | `lnt` | List all tmux sessions |
| `ntm attach` | `rnt` | Attach to session |
| `ntm status` | `snt` | Show pane details with agent counts |
| `ntm view` | `vnt` | Unzoom, tile layout, attach |
| `ntm zoom` | `znt` | Zoom to specific pane |
| `ntm dashboard` | `dash`, `d` | Interactive visual dashboard |
| `ntm kill` | `knt` | Kill session (`-f` to force) |

## Command Palette

Fuzzy-searchable TUI with pre-configured prompts:

```bash
ntm palette myproject    # Open palette
ntm bind                 # Set up F6 keybinding
ntm bind --key=F5        # Use different key
```

### Palette Features

- Animated gradient banner with Catppuccin themes
- Fuzzy search with live filtering
- Pin/favorite commands (`Ctrl+P` / `Ctrl+F`)
- Live preview pane with metadata
- Quick select with numbers 1-9
- Visual target selector (All/Claude/Codex/Gemini)

### Palette Navigation

| Key | Action |
|-----|--------|
| `↑/↓` or `j/k` | Navigate |
| `1-9` | Quick select |
| `Enter` | Select command |
| `Esc` | Back / Quit |
| `?` | Help overlay |
| `Ctrl+P` | Pin/unpin |
| `Ctrl+F` | Favorite |

## Interactive Dashboard

```bash
ntm dashboard myproject   # Or: ntm dash myproject
```

### Dashboard Features

- Visual pane grid with color-coded agent cards
- Live agent counts (Claude/Codex/Gemini/User)
- Token velocity badges (tokens-per-minute)
- Context usage indicators (green/yellow/orange/red)
- Real-time refresh with `r`

### Dashboard Navigation

| Key | Action |
|-----|--------|
| `↑/↓` or `j/k` | Navigate panes |
| `1-9` | Quick select |
| `z` or `Enter` | Zoom to pane |
| `r` | Refresh |
| `c` | View context |
| `m` | Open Agent Mail |
| `q` | Quit |

## Output Capture

```bash
ntm copy myproject:1              # Copy specific pane
ntm copy myproject --all          # Copy all panes
ntm copy myproject --cc           # Copy Claude panes only
ntm copy myproject --pattern 'ERROR'  # Filter by regex
ntm copy myproject --code         # Extract code blocks only
ntm copy myproject --output out.txt   # Save to file
ntm save myproject -o ~/logs      # Save all outputs
```

## Monitoring & Analysis

```bash
ntm activity myproject --watch    # Real-time activity
ntm health myproject              # Health status
ntm watch myproject --cc          # Stream output
ntm extract myproject --lang=go   # Extract code blocks
ntm diff myproject cc_1 cod_1     # Compare panes
ntm grep 'error' myproject -C 3   # Search with context
ntm analytics --days 7            # Session statistics
ntm locks myproject --all-agents  # File reservations
```

### Activity States

| State | Icon | Description |
|-------|------|-------------|
| WAITING | ● | Idle, ready for work |
| GENERATING | ▶ | Producing output |
| THINKING | ◐ | Processing (no output yet) |
| ERROR | ✗ | Encountered error |
| STALLED | ◯ | Stopped unexpectedly |

## Checkpoints

```bash
ntm checkpoint save myproject -m "Before refactor"
ntm checkpoint list myproject
ntm checkpoint show myproject 20251210-143052
ntm checkpoint delete myproject 20251210-143052 -f
```

## Context Window Rotation

NTM monitors context usage and auto-rotates agents before exhausting context.

### How It Works

1. **Monitoring**: Token usage estimated per agent
2. **Warning**: Alert at 80% usage
3. **Compaction**: Try `/compact` or summarization first
4. **Rotation**: Fresh agent with handoff summary if needed

### Context Indicators

| Color | Usage | Status |
|-------|-------|--------|
| Green | < 40% | Plenty of room |
| Yellow | 40-60% | Comfortable |
| Orange | 60-80% | Approaching threshold |
| Red | > 80% | Needs attention |

### Automatic Compaction Recovery

When context is compacted, NTM sends a recovery prompt:

```toml
[context_rotation.recovery]
enabled = true
prompt = "Reread AGENTS.md so it's still fresh in your mind. Use ultrathink."
include_bead_context = true   # Include project state from bv
```

## Robot Mode (AI Automation)

Machine-readable JSON output for AI agents and automation.

### State Inspection

```bash
ntm --robot-status              # Sessions, panes, agent states
ntm --robot-context=SESSION     # Context window usage
ntm --robot-snapshot            # Unified state: sessions + beads + mail
ntm --robot-tail=SESSION        # Recent pane output
ntm --robot-inspect-pane=SESS   # Detailed pane inspection
ntm --robot-files=SESSION       # File changes with attribution
ntm --robot-metrics=SESSION     # Session metrics
ntm --robot-plan                # bv execution plan
ntm --robot-dashboard           # Dashboard summary
ntm --robot-health              # Project health
```

### Agent Control

```bash
ntm --robot-send=SESSION --msg="Fix auth" --type=claude
ntm --robot-spawn=SESSION --spawn-cc=2 --spawn-wait
ntm --robot-interrupt=SESSION
ntm --robot-assign=SESSION --assign-beads=bd-1,bd-2
ntm --robot-replay=SESSION --replay-id=ID
```

### Bead Management

```bash
ntm --robot-bead-claim=BEAD_ID --bead-assignee=agent
ntm --robot-bead-create --bead-title="Fix bug" --bead-type=bug
ntm --robot-bead-show=BEAD_ID
ntm --robot-bead-close=BEAD_ID --bead-close-reason="Fixed"
```

### CASS Integration

```bash
ntm --robot-cass-search="auth error" --cass-since=7d
ntm --robot-cass-context="how to implement auth"
ntm --robot-cass-status
```

### Exit Codes

| Code | Meaning |
|------|---------|
| `0` | Success |
| `1` | Error |
| `2` | Unavailable/Not implemented |

## Work Distribution

Integration with BV for intelligent work assignment:

```bash
ntm work triage