# Ntm

> Run NTM for multi-agent tmux orchestration, work triage, robot mode, safety, coordination, and local APIs. Use when spawning swarms, dispatching work, or operating `ntm` as an agent or human operator.

- Skill: `dicklesworthstone/ntm` (Agent Skill, multi-file: 29 files)
- Install (CLI): `npx get-skill add dicklesworthstone/ntm`
- Raw SKILL.md: https://api.skillmd.com/api/skills/dicklesworthstone/ntm/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: dicklesworthstone (https://skillmd.com/u/dicklesworthstone)
- Updated: 2026-11-15
- Page: https://skillmd.com/skills/dicklesworthstone/ntm

---


<!-- TOC: Quick Start | Session Orchestration | Dispatch & Reusable Assets | Reasoning Ensembles | Work Intelligence | Coordination | Safety | Robot Mode | Serve API | Project Resolution | References | Related Skills -->

# NTM — Named Tmux Manager

> **Core capability:** Turn `tmux` into a structured, recoverable multi-agent workspace.

> **Read the repo first.** If the target repository has `AGENTS.md` or `README.md`, read those before applying this skill. Repo-local instructions override generic NTM advice.

> **Interactive vs automation:**
> - `ntm dashboard`, `ntm palette`, `ntm web`, and other TUI/web surfaces are for humans.
> - For machine-readable automation, prefer `--robot-*`.
> - Non-interactive CLI commands such as `ntm send`, `ntm work triage`, `ntm attention list`, `ntm locks list`, `ntm pipeline status`, and `ntm serve` are fine when they are the clearest tool.

> **Coordination and isolation:**
> - Agent Mail reservations are the default coordination primitive.
> - `--worktrees` and `ntm worktrees ...` are supported isolation tools when the repo policy allows them.
> - If a repo `AGENTS.md` prefers reservations-only or has worktree-specific rules, follow that repo.

## Quick Start

```bash
# Install / sanity check
curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh?$(date +%s)" | bash -s -- --easy-mode
ntm deps -v

# Create or resolve a project
ntm quick myproject --template=go

# Launch a mixed swarm
ntm spawn myproject --cc=2 --cod=1 --agy=1

# Dispatch work
ntm send myproject --cc "Map the auth layer and propose a refactor plan."

# Inspect the current work graph and system state
ntm work triage --format=markdown
ntm --robot-snapshot
```

## Session Orchestration

Use these for day-to-day session lifecycle management:

```bash
ntm spawn myproject --cc=3 --cod=2 --agy=1
ntm spawn myproject --grok=1 --omp=1 --oc=1
ntm spawn myproject --label frontend --cc=2
ntm spawn myproject --label backend --cc=2 --worktrees
ntm add myproject --cc=1
ntm add myproject --label frontend --cod=1
ntm list
ntm status myproject
ntm view myproject
ntm zoom myproject 3
ntm attach myproject
ntm dashboard myproject
ntm palette myproject
ntm web
```

In `ntm palette`, target selection keys cover every built-in harness: `1-5` (All / Claude / Codex / Gemini / Antigravity), `7` Oh My Pi (`omp`), `8` Grok (`grok`), `9` OpenCode (`oc`), and `6` to pick individual agent panes.

Useful spawn patterns:

```bash
ntm spawn myproject --prompt "Read AGENTS.md and start on ready work"
ntm spawn myproject -r full-stack
ntm spawn myproject -t red-green
ntm spawn myproject --persona=architect --persona=implementer:2
ntm spawn myproject --stagger-mode=smart --cc=6 --cod=4
```

Stagger defaults can live in config so every spawn paces prompts (flags win):

```toml
[spawn]
stagger_mode = "fixed"   # none | fixed | smart
stagger_delay = "90s"    # 0-5m
```

## Dispatch and Reusable Assets

High-leverage NTM usage is not just `spawn` plus `send`. The real power shows up when
you combine richer dispatch patterns with reusable session and prompt assets.

```bash
ntm send myproject --all "Checkpoint and summarize blockers."
ntm send myproject --pane=2 "Own the auth migration."
ntm send --project myproject "Sync to main and report conflicts."
ntm send myproject -c internal/auth/service.go "Review this subsystem"
ntm send myproject -t fix --var issue="nil pointer" --file internal/auth/service.go
ntm send myproject --route=affinity "Take the auth follow-up in internal/auth/service.go"
ntm send myproject --distribute --dist-strategy=dependency

ntm recipes list
ntm recipes show full-stack
ntm workflows list
ntm workflows show red-green
ntm template list
ntm template show refactor
ntm session-templates list
ntm session-templates show refactor
```

User-level and project-level assets both matter. NTM can resolve configuration from
`~/.config/ntm/...` and project-local `.ntm/...` trees, so check the repo before
assuming defaults.

## Reasoning Ensembles

Multi-mode reasoning ensembles are graduated into default NTM builds for structured diagnosis, adversarial review, synthesis, run comparison, and finding provenance:

```bash
ntm modes list --tier core
ntm ensemble suggest "What security issues exist in the auth layer?" --json
ntm ensemble spawn myensemble --preset project-diagnosis --question "What are the main architectural risks?"
ntm ensemble status myensemble --format=json
ntm ensemble synthesize myensemble --format=json
ntm ensemble compare myensemble-v1 myensemble-v2 --format=json
ntm ensemble provenance --all --format=json
```

## Work Intelligence

NTM is no longer just a pane launcher. It has first-class work selection and assignment:

```bash
ntm work triage
ntm work triage --by-track
ntm work alerts
ntm work search "JWT auth"
ntm work impact internal/api/auth.go
ntm work next
ntm work graph

ntm assign myproject --auto --strategy=dependency
ntm assign myproject --beads=br-123,br-124 --agent=codex
```

Use `ntm work ...` when you want NTM to wrap `bv` and present work in operator-friendly form.
Use raw `bv --robot-*` when you specifically want the graph engine's native robot output.

## Coordination and Recovery

NTM now exposes the surrounding coordination stack directly:

```bash
ntm mail send myproject --all "Report blockers and current file focus."
ntm mail inbox myproject
ntm locks list myproject --all-agents
ntm locks renew myproject
ntm locks force-release myproject 42 --note "agent inactive"
ntm coordinator status myproject
ntm coordinator digest myproject
ntm coordinator conflicts myproject
ntm attention list --json
ntm attention ack 42 --reason "investigating pane_2"
ntm attention snooze 42 --until 30m --reason "waiting on build"
ntm attention pin 42 --reason "release blocker"
ntm attention dismiss 42 --reason "false alarm"
ntm checkpoint save myproject -m "before risky refactor"
ntm checkpoint list myproject
ntm checkpoint restore myproject
ntm timeline list
ntm timeline show <session-id>
ntm history search "authentication error"
ntm audit show myproject
ntm conflicts myproject
ntm resume myproject
```

`ntm locks force-release` is approval-gated by default (`automation.force_release: approval`): the first run files a durable approval request, a second operator grants it with `ntm approve <id>` (self-approval is rejected), and re-running the command consumes the approval and executes once. A solo operator can set `ntm policy automation --force-release auto` to allow unattended force-release.

Treat `ntm checkpoint save` as a routine cadence, not just a pre-disaster snapshot. Good points to checkpoint: once prompts are confirmed received after a spawn or restore, after an investigation isolates a root cause, before risky edits, after significant uncommitted work but before verification, after a green verification, and before a merge/cleanup/handoff. Cheap checkpoints make any later `ntm checkpoint restore` land on a known-good state.

Note that Agent Mail may run as an external MCP or service-manager process **outside** the tmux session. If Agent Mail and tmux appear to fail together, don't assume tmux took Agent Mail down — check the service manager, process/cgroup ancestry, and OOM/memory signals at the service boundary before relaunching workers.

Isolation options:

```bash
# Coordination-first
ntm locks list myproject

# Isolation-first when policy allows it
ntm spawn myproject --cc=3 --worktrees
ntm worktrees list
ntm worktrees merge claude_1
```

## Safety and Approvals

NTM has built-in safety, policy, and approval surfaces. Use them instead of ad hoc shell habits:

```bash
ntm safety status
ntm safety check -- git reset --hard
ntm safety blocked --hours 24
ntm safety install   # also registers the Claude hook in ~/.claude/settings.json

ntm policy show --all
ntm policy validate
ntm policy edit
ntm policy automation

ntm approve list
ntm approve show abc123
ntm approve abc123
ntm approve deny abc123 --reason "wrong target branch"
```

If the repo instructions require offloading builds or tests through another tool such as `rch`, obey the repo instructions.

## Canonical Robot Mode

Start with these:

```bash
ntm --robot-help
ntm --robot-capabilities
ntm --robot-status
ntm --robot-snapshot
ntm --robot-plan
ntm --robot-dashboard
ntm --robot-markdown --compact
ntm --robot-terse
```

Common task-specific robot surfaces:

```bash
ntm --robot-spawn=myproject --spawn-cc=3 --spawn-prompt="Read AGENTS.md and start on ready work" --spawn-stagger-mode=fixed --spawn-stagger-delay=90s
ntm --robot-send=myproject --msg="Summarize blockers." --type=claude
ntm --robot-ack=myproject --timeout=30s
ntm --robot-tail=myproject --lines=50
ntm --robot-mail-check --mail-project=myproject --urgent-only
ntm --robot-cass-search="authentication error"
ntm --robot-beads-list --status=open
ntm --robot-bead-claim=br-123 --bead-assignee=agent1
ntm --robot-bead-close=br-123 --bead-close-reason="Completed"
ntm --robot-ensemble=myensemble
ntm --robot-ensemble-modes --tier=core
ntm --robot-ensemble-presets
ntm --robot-ensemble-suggest="What security issues exist?"
ntm --robot-ensemble-synthesize=myensemble --synth-force
ntm --robot-send=myproject --msg="Apply schema migration" --op-id=deploy-42
ntm --robot-action-status=deploy-42
ntm --robot-wait-request=deploy-42 --timeout=30s
ntm --robot-cancel-request=deploy-42
```

`--spawn-prompt` (or `--spawn-prompt-file`) waits for readiness, then reaches
each agent through robot send's dispatch path; the JSON reports the
`stagger.schedule[]` (per-agent `delay_ms`/`scheduled_at`) and
`prompt_deliveries[]` (per-agent `prompt_sent`/`delivered_at`). The same
`--spawn-stagger-*` flags pace `--spawn-assign-work` prompts.

Operator loop:

```text
1. Bootstrap with --robot-snapshot
2. Tend with --robot-attention or --robot-wait
3. Act with --robot-send, ntm send, ntm assign, ntm locks, or ntm mail
4. Re-bootstrap with --robot-snapshot if the cursor expires
```

Prefer `--robot-*` when another agent or script needs structured output.

## Serve API and Pipeline Surfaces

NTM also exposes the embedded web cockpit, local REST/SSE/WebSocket API, and durable workflow surfaces:

```bash
ntm web
ntm serve --port 7337
ntm openapi generate
ntm pipeline run .ntm/pipelines/review.yaml --session myproject
ntm pipeline status run-20241230-123456-abcd
ntm pipeline list
ntm pipeline resume run-20241230-123456-abcd
ntm pipeline cleanup --older=7d
```

`ntm web` mounts the embedded browser cockpit at `http://127.0.0.1:7337` alongside the REST/SSE/WebSocket API and live OpenAPI 3.1 spec at `http://127.0.0.1:7337/api/v1/openapi.json`. Use `ntm serve` for headless local integrations, and `--robot-*` for single-shot agent control.

## Project Resolution

`ntm spawn` needs a project directory that NTM can resolve.

```bash
ntm config get projects_base
ntm quick myproject --template=go

# Or point projects_base at an existing repo layout / create a symlink when needed
```

The session name usually matches the project directory name. Labels extend the session name as `project--label`.

## Reference Index

Read these when you need deeper detail without bloating the main skill body:

| Topic | Reference |
| --- | --- |
| High-leverage command patterns, output capture, monitoring, reusable assets | [COMMANDS.md](references/COMMANDS.md) |
| Attention feed, robot output formats, wait conditions, mail/cass/bead robot flows | [ROBOT-MODE.md](references/ROBOT-MODE.md) |
| Human dashboard, palette, keybindings, and TUI implementation notes | [DASHBOARD.md](references/DASHBOARD.md) |
| Project resolution, `projects_base`, config paths, and project-local assets | [CONFIG.md](references/CONFIG.md) |

## Related Skills

- `agent-mail` for inboxes, contact handshakes, and file reservations
- `br` for bead state changes and syncing
- `bv` for graph-aware task prioritization
- `cass` for prior-session retrieval

