name: ntm user-invocable: false skill_api_version: 1 hexagonal_role: supporting metadata: tier: execution description: >- Orchestrates NTM tmux agent swarms and robot APIs. Use when spawning/sending panes, reading robot state, triaging work, locks/mail, safety, pipelines, serve, or NTM errors. practices:
- pragmatic-programmer
Scope: this skill is the NTM tool reference — every verb, flag, schema, and integration point. For operator loops, marching orders, unstick ladders, swarm anti-patterns, and tending cadence, use the companion
vibing-with-ntmskill.
NTM — Named Tmux Manager
The One Rule: Discover the live NTM contract first, then use the least interactive surface that can prove and execute the action. No
--robot-capabilities/--robot-snapshotevidence -> no automation assumption.
Outcome — When an NTM Action Has Delivered
A state-changing NTM action is complete only when all of the following hold:
- The intended state transition is visible in
ntm --robot-snapshot— not just acknowledged by the command's exit code. (NTM commands can succeed at the API layer while panes/work/locks remain unchanged; trust the snapshot, not the return value.) - The attention feed (
--robot-attention/--robot-tail) shows the expected event(s) — pane output, work-graph movement, lock acquire/release, mail delivery. Absence is evidence of failure. - Adjacent state (git, br/beads, mail, pipelines) reflects the action's downstream effects within one observation window — otherwise the action fired in isolation and likely didn't accomplish its real purpose.
- Locks and pipelines you opened are either released / completed by you, or explicitly handed off via mail with a thread the next operator can claim. Orphaned locks block the swarm.
- For dispatched marching orders: the targeted pane has acknowledged (printed the order, started the work, or replied via mail). A sent-but-not-acknowledged order is not "done."
If the snapshot or attention feed disagrees with what the command said happened, trust the snapshot and re-discover the contract — the local model of NTM is stale.
Cold Start: Which NTM Skill?
If you are coming in fresh, pick the narrowest starting point:
| Situation | Start here |
|---|---|
| You need exact NTM command syntax, robot flags, schemas, or failure-mode fixes | This skill |
| You are tending an already-running swarm and deciding whether to nudge, restart, stand down, or dispatch marching orders | /vibing-with-ntm |
| You are running a Brenner-style hypothesis investigation or incident RCA through NTM panes | brennerbot-with-ntm |
| You only need Beads or BV mechanics | /beads-br or /beads-bv |
For any state-changing action, read just enough of this file to choose the command, then verify the live contract with ntm --robot-capabilities before executing.
The Loop (Mandatory)
1. DISCOVER -> ntm --robot-capabilities; ntm --robot-tools; repo AGENTS.md/README.md
2. SNAPSHOT -> ntm --robot-snapshot; inspect sources/degraded_sources, cursor, sessions, panes
3. SELECT -> choose the smallest surface: work/assign/send/wait/pipeline/locks/mail
4. PROVE -> fill the NTM action card: target, contract, safety, ownership, rollback
5. EXECUTE -> prefer --robot-* for automation; avoid human-only TUIs
6. VERIFY -> attention/events/causality/tail plus git/br/mail evidence changed as expected
7. CLEANUP -> release/renew locks, checkpoint/handoff, prune old pipeline state when appropriate
8. REPEAT -> re-snapshot on cursor expiry or after any state-changing action
The most common NTM mistake is treating it like a tmux macro runner. Current NTM is a control plane: robot API, attention feed, work graph, locks/mail, pipelines, ensembles, safety, approvals, serve API, and durability all have explicit contracts. Use the contract.
NTM Action Card
For every state-changing NTM action, be able to answer this before running it:
## NTM action: <command>
- Target session/project: <name/path>; resolved by: `ntm config get projects_base` / `ntm quick` / snapshot
- Live contract checked: `ntm --robot-capabilities` contains <flag>; schema/docs checked if unfamiliar
- Evidence before: cursor=<N>; sources=<fresh/degraded>; panes=<count>; locks=<summary>
- Ownership/safety: Agent Mail reservation or worktree policy is clear; user pane inclusion is intentional
- Blast radius: panes/files/sessions affected; destructive/safety/policy approvals required? <yes/no>
- Verification after: <robot event / tail movement / bead state / git change / pipeline status>
- Recovery: <smart restart / interrupt / checkpoint restore / cancel pipeline / handoff>
If you cannot fill the card, do a read-only discovery pass first.
Command Selection Matrix
Score candidate surfaces when several could work:
Score = (ContractFit x Observability x Reversibility) / BlastRadius
ContractFit 1-5: exact robot/schema match beats human help text
Observability 1-5: action emits cursor/event/status/causality evidence
Reversibility 1-5: easy cancel/retry/restore/checkpoint
BlastRadius 1-5: one pane/file is low; whole session/process tree is high
Pick the highest score. In ties, prefer the surface that produces structured output.
| Need | Best first surface | Usually wrong |
|---|---|---|
| Know what exists | ntm --robot-capabilities |
`ntm --help |
| Tend a swarm | --robot-snapshot -> --robot-attention |
fixed sleep/poll loops |
| Send machine-driven prompt | ntm --robot-send=<session> |
ntm send when CASS/confirm prompts can block |
| Recover a pane | --robot-diagnose -> --robot-smart-restart |
immediate hard restart |
| Run repeatable phase work | ntm pipeline run / --robot-pipeline-run |
copy-paste manual dispatch |
| Explain what happened | --robot-causality + --robot-events |
pane scrollback only |
| No ready work | ntm work queue-dry --format=json |
inventing new work without duplicate/source checks |
| Cross-machine continuity | checkpoint export / handoff create |
shipping attention cursors |
Pattern Tiers
Tier 1: Safe Read-Only Surfaces
| Pattern | Use | Proof |
|---|---|---|
| Capabilities/schema | Current command contract | Flag + params exist |
| Snapshot | Baseline state + cursor | sources / degraded_sources reviewed |
| Events/digest/attention | Tending loop | cursor advances or resync command returned |
| Work triage/queue-dry | Work selection | ready/dry status plus warnings |
| Locks list/check | Coordination truth | no conflicting active reservation |
Tier 2: Reversible Control
| Pattern | Use | Guard |
|---|---|---|
--robot-send |
Directed instruction | panes/type/all explicitly scoped |
--robot-interrupt |
Stop wrong task | tail proves wrong task/stall |
--robot-smart-restart |
Recover stuck pane | refuses active work |
ntm assign |
Match agents to beads | ready work and ownership checked |
pipeline cancel/resume |
Workflow control | run id and state file confirmed |
Tier 3: Durable Orchestration
| Pattern | Use | Guard |
|---|---|---|
| Pipelines | Repeatable multi-step work | dry-run first; state captured |
| Agent Mail / locks | Shared edits | reservation lease and thread id |
| Checkpoint / handoff | Recovery/resume | archive exists and metadata matches |
| Serve API | Long-lived integrations | auth mode and local exposure understood |
| Safety / approve / policy | Risk control | token/policy target, not bead id |
Anti-Patterns (Never Do)
| Bad move | Why it fails | Use instead |
|---|---|---|
Call ntm view from automation |
Retiles the human layout and returns nothing useful | --robot-tail, --robot-snapshot, or --robot-dashboard |
Trust old notes over --robot-capabilities |
NTM surface changes quickly | Discover first |
Send to --all without naming the user-pane intent |
Can hit the operator pane | use type/panes or -s/--skip-first |
| Treat cursor values as portable | Cursors are per-server monotonic | checkpoint/handoff for portability |
| Kill/restart before a liveness proof | Destroys partial work | diagnose -> smart restart -> explicit restart |
| Conflate pipeline status and run | --robot-pipeline=<id> is status |
--robot-pipeline-run=<file> |
| Retry degraded mail/CASS forever | Burns the session | record degraded source, use fallback, continue |
| Infer abandoned beads from silence | NTM deliberately does not implement bead_orphaned |
explicit status/mail/reservation evidence |
Pre-Flight Checklist
- Repo
AGENTS.md/ README read when operating inside a codebase. -
ntm --robot-capabilitieschecked for any unfamiliar flag. -
ntm --robot-snapshotcaptured andsources/degraded_sourcesreviewed. - Session/project resolution verified; labels and
projects_basemake sense. - User pane inclusion/exclusion is explicit.
- File ownership is clear: Agent Mail reservation, bead assignee, or approved worktree policy.
- For pipelines: dry-run passed; run id/state file plan known.
- For recovery: liveness truth stack supports intervention.
- For destructive/risky actions: safety/policy/approval surfaces checked.
- Post-action verifier named before execution.
Core capability: Turn
tmuxinto a structured, recoverable multi-agent workspace.
Read the repo first. If the target repository has
AGENTS.mdorREADME.md, read those before applying this skill. Repo-local instructions override generic NTM advice.
Discover, don't guess.
ntm --robot-capabilitiesreturns the machine-readable API schema.ntm --robot-docs=quickstart|commands|examples|exit-codesreturns focused docs. Use these before parsing human help text or trusting stale instructions.
Interactive vs automation:
ntm dashboard,ntm palette, and other TUI surfaces are for humans.ntm viewretiles the operator's tmux layout and returns nothing to you — never call it from automation.- For machine-readable automation, prefer
--robot-*. Set--robot-format=toon(orNTM_ROBOT_FORMAT=toon) for a token-efficient structured format, and--robot-verbosity=tersewhen context is tight.- Non-interactive CLI commands such as
ntm send,ntm work triage,ntm locks list,ntm pipeline status, andntm serveare fine when they are the clearest tool.
Coordination and isolation:
- Agent Mail reservations are the default coordination primitive.
--worktreesandntm worktrees ...are supported isolation tools when the repo policy allows them.- If a repo
AGENTS.mdprefers reservations-only or has worktree-specific rules, follow that repo.
Quick Start
# 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 --gmi=1
# Codex fallback when --cod opens a bare shell instead of Codex
codex exec -s danger-full-access --skip-git-repo-check -C "$PWD" \
"Read AGENTS.md, claim the assigned bead, implement only that scope, and report evidence."
# 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 work queue-dry --format=json
ntm --robot-snapshot
# Discover the full surface without parsing --help output
ntm --robot-capabilities
ntm --robot-docs=commands
Mental Model
NTM wraps tmux with structured metadata and durable state. Five concepts are worth internalizing:
- Project — resolved via
NTM_PROJECTS_BASE + <session>(orprojects_baseconfig). Session name MUST equal the directory basename under that base, or agent-mail/beads/reservations register under a different key than NTM sees. This is the single most common source of cross-tool breakage. - Session name — bare project (
myproject) or labeled variant (myproject--frontend).--is the reserved label separator; project names cannot contain--. Labels must match^[a-zA-Z0-9][a-zA-Z0-9_-]*$and be ≤50 chars. - Pane — a tmux pane typed as an agent (cc/cod/gmi/cursor/windsurf/aider/oc/opencode/ollama) or the user pane (index 0 by default).
ntm senddefaults exclude the user pane;--allincludes it;-s/--skip-firstexplicitly skips it. - Attention feed — a monotonic event stream.
--robot-snapshotbootstraps;--robot-events --since-cursor=N --events-limit=Mreplays;--robot-attention --attention-cursor=Nblocks until new events. Cursors are per-server monotonic and not portable across machines; expired cursors return aresync_commandready to paste. - Robot mode — every state-read has a
--robot-*variant returning structured JSON or TOON. Prefer robot mode over TUIs in all automation;ntm view,ntm dashboard,ntm paletteare operator-only and will return nothing useful to automation (andntm viewadditionally retiles the human's layout).
Current Reality Snapshot
Recent NTM builds are a full operator control plane, not only a launcher:
--robot-capabilitiesis the source of truth; the current mainline advertises 137 robot surfaces across attention, state, control, beads, BV, CASS, ensemble, pipeline, spawn, and utility lanes.--oc/ opencode is a first-class agent type in spawn/add/adopt/controller paths; older docs that list only cc/cod/gmi/cursor/ws/aider/ollama are incomplete.- Operator state now includes source-health, capture provenance, resource pressure, assurance/quiescence, and degraded coordination signals. Check
sourcesanddegraded_sourcesbefore acting on stale beads/mail/CASS-derived advice. - Queue-dry is a concrete workflow:
ntm work queue-drydiagnoses no-ready-work states, and--ideate --create-beads --yesis the explicit mutation path. - Ensemble catalog/status/suggest surfaces are useful in normal builds, but ensemble spawn is experimental; if
--robot-ensemble-spawnreturnsNOT_IMPLEMENTED, rebuild NTM with-tags ensemble_experimentalor use ordinaryntm spawn/ pipeline orchestration. - Serve/robot pane targeting is pane-ID aware; avoid code or docs that assume
session:indexis stable under tmux base-index changes.
Tool Selection Kernel
When you are unsure which NTM surface to use, route by intent:
| Intent | First surface | Act only after |
|---|---|---|
| Discover current API shape | ntm --robot-capabilities |
Command + parameter exists in registry |
| Understand live swarm state | ntm --robot-snapshot or ntm --robot-is-working=<session> |
Relevant sources entry is fresh or degraded status is acknowledged |
| Pick work | ntm work triage / bv --robot-triage |
Ready item is unblocked and not owned by another agent |
| No ready work | ntm work queue-dry --format=json |
Dry queue is confirmed; warnings/guards are reviewed |
| Push work to panes | ntm assign or ntm --robot-send |
File/domain ownership is clear |
| Recover a pane | ntm --robot-diagnose, then --robot-smart-restart |
Liveness truth stack says the pane is not productively working |
| Integrate with scripts/services | --robot-* or ntm serve |
JSON/OpenAPI contract is validated |
Session Orchestration
Use these for day-to-day session lifecycle management:
ntm spawn myproject --cc=3 --cod=2 --gmi=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 zoom myproject 3
ntm attach myproject
ntm dashboard myproject # human only
ntm palette myproject # human only
Useful spawn patterns:
ntm spawn myproject --prompt "Read AGENTS.md and start on ready work"
ntm spawn myproject -r full-stack # named recipe (see `ntm recipes list`)
ntm spawn myproject -t red-green # named workflow (see `ntm workflows list`)
ntm spawn myproject --persona=architect --persona=implementer:2
ntm spawn myproject --stagger-mode=smart --cc=6 --cod=4 # smart|fixed|none
ntm spawn myproject --no-user --cc=5 --cod=5 # no human-driver pane
Adjust a running swarm instead of re-spawning:
ntm scale myproject --cc=4 # grow/shrink one agent type
ntm rebalance myproject # even out agents by workload
ntm swarm plan # show what a spawn would do
ntm swarm status # cross-session swarm view
ntm swarm stop <pattern> # stop sessions by name pattern
ntm respawn myproject # recover dead agents in place
ntm adopt <tmux-session> # bring an existing tmux session under ntm
Codex spawn fallback
Treat ntm spawn <project> --cod=N as provisional until observed. Some local
NTM builds have created and registered the cod pane but left it at a bare zsh
prompt; the next sent "contract" then executes as shell text and fails with parse or
command not found noise.
Verification:
ntm spawn myproject --cod=1
ntm --robot-tail=myproject --panes=2 --lines=20
ntm --robot-snapshot
If the Codex pane is a shell instead of an active codex session, do not keep
sending prompts to that pane. Use a Codex-native one-shot worker from the repo root
or the intended worktree:
codex exec -s danger-full-access --skip-git-repo-check -C /path/to/gitdir \
"Read AGENTS.md, claim bead <id>, implement only that scope, run the gate, and report evidence."
For parallel lanes, prefer one codex exec -C <isolated-worktree> per worker until
the live NTM --cod launcher is verified fixed by --robot-tail evidence.
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.
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 --smart --route=affinity "Take the auth follow-up"
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.
Work Intelligence
NTM is no longer just a pane launcher. It has first-class work selection and assignment:
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 work queue-dry --format=markdown
ntm work queue-dry --ideate --format=json
ntm work queue-dry --ideate --create-beads --yes
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:
# Mail (Agent Mail MCP, wrapped for CLI use)
ntm mail send myproject --all "Report blockers and current file focus."
ntm mail inbox myproject # or: ntm mail inbox myproject --json
# File reservations (advisory locks)
ntm locks list myproject --all-agents
ntm locks check internal/auth/service.go --session myproject --pane 2 --json
ntm locks renew myproject --extend 30 # minutes
ntm locks force-release myproject 42 --note "agent inactive"
# Multi-agent coordinator
ntm coordinator status myproject # alias: ntm coord status
ntm coordinator digest myproject
ntm coordinator conflicts myproject
ntm coordinator enable auto-assign # background automation
ntm coordinator enable digest --interval=30m
# Durable session state
ntm checkpoint save myproject -m "before risky refactor"
ntm checkpoint list myproject
ntm checkpoint restore myproject # latest; takes optional <id>
ntm checkpoint export myproject <id> # portable archive
ntm checkpoint import <archive>
# Persisted timelines of agent state transitions
ntm timeline list
ntm timeline show <session-id>
ntm timeline stats
# Audit, conflict, history surfaces
ntm history search "authentication error"
ntm audit show myproject
ntm changes myproject # recent file changes attributed to agents
ntm conflicts myproject --since 6h # top-level command; not a changes subcommand
ntm resume myproject # re-attach + context-inject after restart
# Handoff bundles for cross-machine or cross-session resumes
ntm handoff create myproject
ntm handoff list
ntm handoff show <path>
Isolation options:
# 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:
ntm safety status
ntm safety check --json git status # checks a candidate command without running it
ntm safety blocked --hours 24
ntm safety install
ntm policy show --all
ntm policy validate
ntm policy edit
ntm policy automation
ntm approve list
ntm approve show <token>
ntm approve <token> # approve by token (not bead/issue id)
ntm approve deny <token> --reason "wrong target branch"
ntm approve history
If the repo instructions require offloading builds or tests through another tool such as rch, obey the repo instructions.
Current hook/tool contracts to remember:
ntm safety installwritesgit/rmwrappers plus a Claude Code PreToolUse hook. The hook reads the modern Claude JSON payload on stdin (tool_name,tool_input.command) and exits2to block;CLAUDE_TOOL_*env vars are legacy fallback only.- NTM's DCG adapter uses DCG's real contract:
dcg doctor --format jsonfor status anddcg --robot test --format json <command>for checks. Do not document or calldcg check. - RCH is external build offload. Use
rch exec -- <build command>directly when repo rules require offloading; the NTM robot surface reports RCH health/workers, it does not replace the build command.
Canonical Robot Mode
Start with these:
ntm --robot-help
ntm --robot-capabilities # canonical machine-readable API schema
ntm --robot-docs=quickstart # also: commands, examples, exit-codes
ntm --robot-schema=all # JSON Schema for every robot response
ntm --robot-status
ntm --robot-snapshot
ntm --robot-plan
ntm --robot-dashboard
ntm --robot-markdown --md-compact
ntm --robot-terse
Format and verbosity knobs (token-budget friendly):
ntm --robot-snapshot --robot-format=toon # toon is far more token-efficient than json
ntm --robot-snapshot --robot-verbosity=terse # terse | default | debug
# Env fallbacks honored: NTM_ROBOT_FORMAT / NTM_OUTPUT_FORMAT / TOON_DEFAULT_FORMAT
Common task-specific robot surfaces:
ntm --robot-send=myproject --panes=2 --msg="Summarize blockers." --type=claude
ntm --robot-ack=myproject --timeout=30s
ntm --robot-tail=myproject --panes=2 --lines=50
ntm --robot-mail-check --mail-project=myproject --urgent-only
ntm --robot-cass-search="authentication error"
ntm --robot-beads-list --beads-status=open
ntm --robot-bead-claim=br-123 --bead-assignee=agent1
ntm --robot-bead-close=br-123 --bead-close-reason="Completed"
Polite-probe-then-act (preferred over raw interrupt):
ntm --robot-is-working=myproject --panes=2,3 # check first
ntm --robot-smart-restart=myproject --panes=2 # refuses if the pane is actively working
ntm --robot-probe=myproject --panes=2 # responsiveness probe
ntm --robot-diagnose=myproject # comprehensive health + recommendations
ntm --robot-context=myproject # context-window usage per agent
Event-driven tending instead of polling:
ntm --robot-wait=myproject --wait-until=attention --timeout=5m
ntm --robot-wait=myproject --wait-until=action_required
ntm --robot-wait=myproject --wait-until=mail_ack_required
ntm --robot-events --since-cursor=42 --events-limit=50 --events-category=agent
Operator loop:
1. Bootstrap with --robot-snapshot
2. Tend with --robot-attention or --robot-wait (blocks until an event)
3. Act with --robot-send / --robot-smart-restart / ntm send / ntm assign / ntm mail / ntm locks
4. Re-bootstrap with --robot-snapshot if the cursor expires
Prefer --robot-* when another agent or script needs structured output.
Controller Agents
ntm controller <session> launches a coordinator agent in pane 1 whose job is to
watch the other agents, resolve conflicts, and drive the operator loop.
ntm controller myproject # default: Claude controller, coord prompt
ntm controller myproject --agent-type=cod # cc|cod|gmi|cursor|windsurf|ws|aider|ollama
ntm controller myproject --prompt=ctrl.txt # custom prompt template
ntm controller myproject --no-prompt # launch agent, send no initial prompt
Custom prompts support template variables: {{.Session}}, {{.AgentList}}, {{.ProjectDir}}.
The built-in default prompt tells the controller to:
- Prefer
--robot-*commands over interactive TUIs. - Start with
ntm --robot-snapshot, then block onntm --robot-attention --attention-session={{.Session}}. - Tail panes with
ntm --robot-tail={{.Session}} --panes=N --lines=50. - Check Agent Mail via
ntm mail inbox {{.Session}} --jsonfor the CLI path; use--mail-project=only with--robot-mail-check. - Use
ntm send {{.Session}} --pane N "message"for single pane,--panes=1,2for many. - Use
ntm --robot-interrupt={{.Session}} --panes=Nto interrupt without killing. - Never call
ntm view— it retiles the human operator's tmux layout and returns nothing.
Serve API and Pipeline Surfaces
NTM also exposes local API and durable workflow surfaces:
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
Use ntm serve for long-lived local integrations. Use --robot-* for single-shot agent control.
Project Resolution
ntm spawn needs a project directory that NTM can resolve.
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.
Gotchas (distilled from real agent sessions)
These are the NTM-specific trip-wires most commonly hit in practice. Each has a full entry in TROUBLESHOOTING.md; these are the one-liners.
- Project resolution —
NTM_PROJECTS_BASE+ session name must equal the directory basename. Mismatch breaks agent-mail registration silently. If agent-mail and ntm "see different projects," fix this first. ntm senddefault skips the user pane — so plainntm send myproject --cc "msg"is safe;ntm send myproject --all "msg"hits the operator's zsh. Use-s/--skip-firstif you want--allagents but no user pane.- CASS dedup blocks sends — default
--cass-check=truewith 0.7 similarity, 7-day lookback. Ifntm sendaborts with "similar past prompt," either add a rotating suffix (e.g."... pass 17 at 16:40") or pass--no-cass-check. In robot automation,--robot-sendis non-interactive and never prompts. - Label separator is literal
--— project names cannot contain--.myproject--frontendis the labeled variant;my-projectis a valid project name;my--projectis rejected. send --cc=Xvsspawn --cc=N:X— same flag name, different parsers.send --cc=opusfilters existing panes by variant;spawn --cc=2:opuscreates 2 new panes of modelopus.--route=affinityis a send flag, not an assign strategy —assign --strategy=acceptsbalanced|speed|quality|dependency|round-robinonly.--robot-pipeline=<id>is status, not run — to run, use--robot-pipeline-run=<file>. Conflating these is common.- Pipeline state files accumulate forever —
.ntm/pipelines/<run-id>.jsonis never auto-pruned. Runntm pipeline cleanup --older=7dperiodically. - Safety wrappers need PATH precedence —
ntm safety installdropsgit/rmwrappers at~/.ntm/bin/but does NOT modify$PATH. Confirm~/.ntm/binis earlier in$PATHthan/usr/bin. bead_orphanedis deliberately unsupported — ntm refuses to infer abandonment from silence; explicitbead abandonmail messages would be required and don't exist yet. Don't try to wait on it.- Cursors are per-server monotonic — they are NOT portable across machines. Cross-machine continuity is via
checkpoint export/importorhandoff, not cursor shipping. ntm approvetakes a token, not a bead id — tokens are issued by the approval engine and returned with each approval request; beads ids likebr-123will be rejected.ntm changesandntm conflictsare separate top-level commands — there is nontm changes conflicts(use one or the other).- Attention flags are namespaced — events use
--since-cursor,--events-limit,--events-category, and--events-actionability; attention/digest waits use--attention-cursor,--attention-timeout, and--attention-condition. - Agent Mail can be degraded without blocking work — if the mail/reservation source in
sourcesis stale/unavailable or reservations time out, stop retry loops and use bead assignee/status notes as the temporary soft lock. locks checkis for wrappers and commit guards — it returnsfree|held|blockedfor one path and caller context; use it instead of inventing per-wrapper reservation ledgers.--ocis opencode — if a prompt or profile says "opencode" but no agent appears, check[agents] occonfig or thatopencodeis on PATH.--codmust be observed before use — if a Codex pane is just a bare shell, stop sending prompts to it and runcodex exec -s danger-full-access --skip-git-repo-check -C <gitdir> "<contract>"from an isolated repo/worktree instead.
Reference Index
Keep depth out of this file. Load these on demand for the operator-handbook-level detail.
| Topic | Reference |
|---|---|
ntm send deep reference — agent-type selectors with variants, pane selectors, input sources, file context ranges, templates & vars, smart/route, distribute, batch, CASS dedup, prefix/suffix, dry-run, error modes |
SEND.md |
ntm spawn deep reference — agent counts & model variants, labels, worktrees, personas/recipes/workflows, stagger modes, session profiles, CASS context, assign pipeline, privacy, interactive wizard |
SPAWN.md |
Work intelligence & assignment — ntm work *, ntm assign, strategies, bv integration, robot wrappers |
WORK-AND-ASSIGN.md |
Ensemble mode — reasoning modes, presets, multi-agent debate sessions, --robot-ensemble-* surfaces |
ENSEMBLE.md |
Pipelines — YAML schema v2.0, steps / conditionals / loops / retries, run IDs, resume & cancel, robot pipeline flags, legacy exec |
PIPELINES.md |
Serve API — auth modes (local/api_key/oidc/mtls), OIDC/mTLS flags, REST v1 route map, OpenAPI endpoint, SSE streams |
SERVE.md |
Safety, Policy, Approvals — policy.yaml schema, precedence, automation flags, approval tokens & TTL, SLB two-person, what safety install actually drops on disk |
SAFETY.md |
| Durability stack — checkpoint vs timeline vs handoff vs resume vs rollback; export/import archives; cross-machine continuity | DURABILITY.md |
| Integration surfaces — DCG, SLB, CAAM, RCH, RANO, mail, cass-from-ntm, quota, ru, giil, context-inject | INTEGRATIONS.md |
Environment variables — every NTM_* + TOON_* + inherited vars with source citations |
ENV-VARS.md |
Troubleshooting — failure symptoms / root cause / fix, including projects_base, stale ntm view, --mail-project scope, cursor expiry |
TROUBLESHOOTING.md |
| Self-test / trigger phrases — canonical phrasings the skill should activate on, mapped to first action | SELF-TEST.md |
| High-leverage command patterns, output capture, monitoring, reusable assets | COMMANDS.md |
Attention feed, robot output formats, wait conditions, mail/cass/bead robot flows, full --robot-* index |
ROBOT-MODE.md |
| Human dashboard, palette, keybindings, and TUI implementation notes | DASHBOARD.md |
Project resolution, projects_base, config paths, and project-local assets |
CONFIG.md |
Quick Search (grep hints)
When scanning the skill without loading every file, these literal strings are indexed:
# From the ntm skill root:
rg 'robot-' references/ROBOT-MODE.md # every --robot-* flag with root.go line
rg '^###' references/SEND.md # every send flag family
rg '^###' references/SPAWN.md # every spawn knob
rg 'Symptom' references/TROUBLESHOOTING.md # all failure-mode entries
rg '^-' references/SELF-TEST.md # trigger phrases agents should match
rg '^| `' references/ENV-VARS.md # every NTM_* env var (leading table cell)
grep -l 'policy.yaml' references/ # finds SAFETY.md
grep -l 'schema_version' references/ # finds PIPELINES.md
Assets
Drop-in examples live under assets/:
pipeline-example.yaml— a review pipeline with parallel step + retrypolicy-example.yaml— opinionated~/.ntm/policy.yamlstarterenvrc.example— recommendeddirenv/shell env vars
Related Skills
vibing-with-ntm— the companion operator / orchestration skill: tending loops, marching-orders prompts, autonomous unstick recipes, anti-patterns, steady-state cadence. Use it whenever the question is "how do I run the swarm well?" rather than "what does NTM do?"agent-mailfor inboxes, contact handshakes, and file reservationsbrfor bead state changes and syncingbvfor graph-aware task prioritizationcassfor prior-session retrievalcaamfor account rotation across providers (paired with--robot-switch-account)dcg,slbfor destructive-command and two-person approval policy