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.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Check it deeper on your machine
It has changed since its scan on 16 Nov 2026. Its scripts were only partly scanned.
As a Claude Code plugin, install it and then ask Claude Code:
/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/Dicklesworthstone/ntm with scanskillsafety
Or from a terminal, clone it and run it:
git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/Dicklesworthstone/ntm'
It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.
Badge for your README
Markdown
[](/listings/dicklesworthstone--ntm)HTML
<a href="/listings/dicklesworthstone--ntm"><img src="/api/listings/dicklesworthstone--ntm/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
These steps run a script from the network that findsafeskills does not scan.
Requirements
NTM is a pure Go project, but the runtime experience is intentionally integration-heavy.
- Required: `tmux` - Required for agent spawning: whichever CLIs you want to run, typically Claude Code, Codex, Antigravity CLI, Oh My Pi (`omp`), or Grok Build (Gemini CLI is supported as legacy) - Optional but powerful: `br`, `bv`, Agent Mail, `cass`, `dcg`, `pt` - Sanity check everything with `ntm deps -v`
First Session
# Install curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh?$(date +%s)" | bash -s -- --easy-mode # Enable shell integration eval "$(ntm shell zsh)" # Verify tools and integrations ntm deps -v # Scaffold a project directory ntm quick api --template=go # Launch a mixed swarm ntm spawn api --cc=2 --cod=1 --agy=1 # Open the live operator surfaces ntm dashboard api ntm palette api # Dispatch work ntm send api --cc "Map the auth layer and propose a refactor plan." # If the repo uses br/bv, inspect the work graph ntm work triage --format=markdown # Save a recoverable checkpoint ntm checkpoint save api -m "before auth refactor" # Expose local APIs for dashboards, scripts, and agents ntm serve --port 7337 ntm --robot-snapshot
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
SKILL.md · Manifest · 335 lines · 1 finding marked
- ---
- name: ntm
- description: >-
- 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.
- ---
- <!-- 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
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 31 on GitHub
- 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
- ntm --robot-handoff=myproject
- ntm --robot-handoff=myproject --handoff-create --handoff-goal="Implemented auth" --handoff-now="Run E2E suite"
- ntm --robot-handoff=myproject --handoff-create --handoff-auto
- ntm --robot-analytics
- ntm --robot-analytics --analytics-days=7 --analytics-sessions
- ntm --robot-analytics --analytics-since=2026-01-01
- ntm --robot-audit=myproject --audit-verify
- ntm --robot-audit --audit-search=spawn --audit-days=7
- ntm --robot-timeline=myproject --timeline-events
- ntm --robot-timeline --timeline-stats
- ntm --robot-doctor --doctor-contention
- ntm --robot-preflight="fix the bug in auth.go" --preflight-strict
- ntm audit http --limit=20 --json
- ```
- `--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
README.md · README · 2,050 lines · 4 findings marked
- # NTM - Named Tmux Manager
- <div align="center">
- <img src="ntm_dashboard.webp" alt="NTM dashboard">
- </div>
- <div align="center">
- 
- 
- 
- 
- </div>
- NTM turns `tmux` into a local control plane for multi-agent software development.
- It combines session orchestration, graph-aware work triage, safety policy and approvals,
- Agent Mail coordination, durable state capture, machine-readable robot surfaces, and a
- local REST/WebSocket API in one Go binary.
- <div align="center">
- ```bash
- curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh?$(date +%s)" | bash -s -- --easy-mode
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 24 on GitHub
- ```
- </div>
- ## TL;DR
- ### The Problem
- Running several coding agents in parallel is easy to start and annoying to sustain.
- Plain `tmux` gives you panes, but it does not give you durable coordination, work
- selection, safety policy, approvals, history, replayable automation surfaces, or a
- shared control model that both humans and agents can use.
- ### The Solution
- NTM gives you a single local system for:
- - spawning labeled multi-agent sessions in `tmux`
- - sending work, interrupts, and follow-ups across panes
- - triaging what to do next with `br` and `bv`
- - coordinating agents with Agent Mail, file reservations, and assignments
- - protecting dangerous operations with policy, approvals, and guards
- - exposing the whole system through `--robot-*`, REST, SSE, WebSocket, and OpenAPI
- - capturing state with checkpoints, timelines, audit trails, and pipeline state
- ### Why NTM
- | Area | What NTM provides | Typical commands |
- | --- | --- | --- |
- | Session orchestration | Spawn, label, inspect, zoom, dashboard, palette | `ntm spawn`, `ntm dashboard`, `ntm palette` |
- | Work intelligence | Graph-aware triage, next-step selection, impact analysis, assignment | `ntm work triage`, `ntm work next`, `ntm assign` |
- | Coordination | Human overseer mail, inbox views, file reservations, worktrees | `ntm mail`, `ntm locks`, `ntm worktrees` |
- | Safety | Destructive-command protection, policy editing, approval workflows | `ntm safety`, `ntm policy`, `ntm approve`, `ntm guards` |
- | Durable operations | Checkpoints, timelines, audit logs, saved sessions, pipelines | `ntm checkpoint`, `ntm timeline`, `ntm audit`, `ntm pipeline` |
- | Automation surfaces | Robot JSON, REST API, SSE/WebSocket streams, OpenAPI | `ntm --robot-snapshot`, `ntm serve`, `ntm openapi generate` |
- ## Quick Start
- ### Requirements
- NTM is a pure Go project, but the runtime experience is intentionally integration-heavy.
- - Required: `tmux`
- - Required for agent spawning: whichever CLIs you want to run, typically Claude Code, Codex, Antigravity CLI, Oh My Pi (`omp`), or Grok Build (Gemini CLI is supported as legacy)
- - Optional but powerful: `br`, `bv`, Agent Mail, `cass`, `dcg`, `pt`
- - Sanity check everything with `ntm deps -v`
- ### First Session
- ```bash
- # Install
- curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh?$(date +%s)" | bash -s -- --easy-mode
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 76 on GitHub
- # Enable shell integration
- eval "$(ntm shell zsh)"
- # Verify tools and integrations
- ntm deps -v
- # Scaffold a project directory
- ntm quick api --template=go
- # Launch a mixed swarm
- ntm spawn api --cc=2 --cod=1 --agy=1
- # Open the live operator surfaces
- ntm dashboard api
- ntm palette api
- # Dispatch work
- ntm send api --cc "Map the auth layer and propose a refactor plan."
- # If the repo uses br/bv, inspect the work graph
- ntm work triage --format=markdown
- # Save a recoverable checkpoint
- ntm checkpoint save api -m "before auth refactor"
- # Expose local APIs for dashboards, scripts, and agents
- ntm serve --port 7337
- ntm --robot-snapshot
- ```
- ## Core Workflows
- ### 1. Multi-Agent Session Orchestration
- NTM is built around named `tmux` sessions with explicit agent panes and a user pane.
- It handles session naming, pane layout, agent startup, labels, and inspection so you
- can treat a swarm like a manageable unit instead of a pile of terminals.
- ```bash
- ntm quick payments --template=go
- ntm spawn payments --cc=3 --cod=2 --agy=1
- ntm add payments --cc=1
- ntm list
- ntm status payments
- ntm view payments
- ntm zoom payments 3
- ntm attach payments
- ```
- A bare `--cc=N` passes no `--model`, so Claude Code starts with its own default
- or saved model and context setting. Pin one with `--cc=N:MODEL` (the built-in
- aliases `opus`, `sonnet`, and `haiku` pass Claude Code's own family aliases,
- which track the newest model) or set `[models] default_claude` in
- `~/.config/ntm/config.toml`; `default_claude = ""` restores the delegate
- behaviour.
- #### Grok Build
- NTM recognizes the official xAI Grok Build CLI as the canonical `grok` agent
- type. Install it using [xAI's current instructions](https://docs.x.ai/build/overview),
- then authenticate without putting credentials in NTM configuration:
- ```bash
- curl -fsSL https://x.ai/cli/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 141 on GitHub
- grok login # browser authentication
- grok login --device-auth # SSH/headless alternative
- ntm deps -v
- ```
- A bare spec delegates model selection to Grok Build. Use `grok models` to inspect
- the models available to the authenticated account, then pass an exact model ID
- only when an override is needed:
- ```bash
- ntm spawn research --grok=1
- ntm spawn research --grok=1:MODEL_ID
- ntm spawn research --grok=1:MODEL_ID:EFFORT
- ntm --robot-spawn=research --spawn-grok=1
- ```
- NTM launches Grok Build with its official `--always-approve` automation flag.
- Phase 2 (GH#251) implements the interactive TUI protocol against live Grok Build
- captures: readiness and working-state detection, composer-gated and
- submission-verified prompt delivery (send, assign, `--robot-spawn --spawn-wait`
- and `--spawn-assign-work`), interrupt, restart, and restore-time relaunch. The
- one deliberate refusal is personas: the Grok Build CLI has no system-prompt
- flag or environment variable, so a persona on a Grok agent fails the launch
- instead of being silently dropped.
- #### Oh My Pi (`omp`)
- NTM operates [Oh My Pi](https://omp.sh) as the built-in `omp` agent type (panes
- are named `session__omp_N`; `oh-my-pi` is accepted as an alias). Finish omp's
- own setup once before the first spawn, otherwise the first prompt lands in the
- setup wizard:
- ```bash
- omp setup
- ntm deps -v # probes the omp binary
- ntm spawn swarm --omp=8 # omp picks its default model
- ntm spawn swarm --omp=2:MODEL # pins MODEL (omp fuzzy-matches it)
- ntm spawn swarm --omp=2:MODEL:high # also sets the thinking level (or MODEL@high)
- ntm add swarm --omp=1
- ntm adopt swarm --omp=1,2,3 # adopt existing omp panes
- ntm --robot-spawn=swarm --spawn-omp=8 --spawn-wait
- ntm send swarm --omp "Run the test suite and report failures"
- ```
- The launch command is `omp --auto-approve`, plus `--model`, `--thinking`, and
- `--append-system-prompt <file>` (personas) when requested. Override it with
- `[agents] omp = "..."` (a template; keep `{{.ReasoningEffort}}` if you want
- effort specs honoured, otherwise NTM rejects them rather than dropping them),
- set `[models] default_omp` or `[models.omp]` aliases, and `[prompts]
- omp_default`. `[spawn_pacing.agent_caps] omp_max_concurrent` (default 8) is
- omp's share of the host-wide agent budget robot spawn admission enforces
- (running plus requested agents may not exceed the sum of all agent caps);
- launches are never serialized per type, and the default admits a full
- `--spawn-omp=8` swarm alongside the default Claude/Codex/Gemini budget.
- Everything NTM does to an omp pane is derived from omp's live TUI (v18.2.3,
- across its nerd, unicode and ascii symbol presets):
- - **Ready / working / idle.** omp keeps a bordered composer at the bottom of the
- pane. A turn in flight shows a spinner and elapsed timer in the composer's top
- border (`╭── ⠧ 1s`), an Esc-hint activity line above it (`⎋ Working…` or an
- intent label), a queued `Steering · N` block, or a ` Subagents` panel listing
- running subagents. A ` TODO` tree alone is not read as working, since a plan
- can outlive its turn. A quiet composer with nothing below it is idle.
- - **Delivery.** Enter submits. A message sent to a busy pane is queued by omp
- as steering; delivery is confirmed when the payload leaves the composer. A
- staged large paste (`#1` token) is reported by `--robot-dialogs` as paste
- limbo and cleared with Ctrl+C.
- - **Interrupt and exit.** omp interrupts on **Escape** (Ctrl+C only clears the
- draft, and a double Ctrl+C quits), so `ntm interrupt`, `--robot-interrupt`,
- restart, and the REST interrupt send Escape to omp panes. Graceful exit is
- Escape, Ctrl+C, then Ctrl+D.
- - **Context.** `--robot-context`, `--robot-snapshot`, `ntm status`, and the
- coordinator's context-rotation trigger read omp's own context gauge from the
- composer border (`7%` … `262K`), reported as `source: "status_bar"`, so the
- reading stays per-pane even when many omp panes share one directory. Compaction
- uses native `/compact` and verifies a fresh reduction in the context gauge.
- - **Sessions.** `ntm sessions save` binds each pane to its omp session (omp
- holds its transcript under `~/.omp/agent/sessions/` open, so the binding is
- exact per pane; profile, XDG and `PI_CODING_AGENT_*` stores are honoured), and
- resume relaunches with `omp --auto-approve --resume <id>`.
- - **Errors.** A failed turn leaves a provider-error block framed by rules
- directly above the quiet composer (`server_error: ERROR`, `401 Invalid API
- Key`, then `Dismissed when you send your next message.`). NTM reports it as
- an error, never as idle-after-completion: `--robot-is-working` returns
- `ERROR_STATE` with `indicator_basis: "provider_error"` and a retry hint, the
- status observation and coordinator report an error (`auth` for 401/403,
- otherwise generic), and assignment will not feed the pane new work. An
- `F5 to Retry` hint may sit between the block and the input box. Press `F5`
- (omp's retry key) to re-run the failed turn, or send any message, such as a
- continue prompt, which dismisses the block and retries.
- `Error: No model selected.` is an error too. No omp rate-limit screen has
- been captured yet, so omp panes are never marked rate-limited from
- transcript text; a provider 429 surfaces as a provider error.
- - **Quota.** omp has no quota or usage command. `ntm quota` lists omp panes as
- "no quota API (provider-error classification)", `ntm rotate all-limited`
- skips them with that reason, and `--robot-quota-check --provider=omp` answers
- `NOT_IMPLEMENTED` (exit 2) naming the same fallback.
- - **Palette, assignment, boot checks.** In `ntm palette`, key `7` targets omp
- panes (`6` still picks individual agents). `--assign` scores omp with the
- per-task midpoint of the Claude and Codex capability profiles, since omp's
- strengths follow whichever model it runs. `--verify-boot` counts a pane as
- booted when it is idle, or when it received a spawn prompt (recovery context,
- CASS context, or your prompt) and is working on it.
- #### OpenCode (`oc`)
- [OpenCode](https://opencode.ai) panes are named `session__oc_N`. The model is
- OpenCode's `provider/model` form; with no model, OpenCode uses its own default.
- ```bash
- ntm spawn swarm --oc=2 # OpenCode picks its default model
- ntm spawn swarm --oc=2:opencode/big-pickle # pins the model
- ntm add swarm --oc=1
- ntm --robot-spawn=swarm --spawn-oc=2:opencode/big-pickle --spawn-wait
- ntm send swarm --oc "Run the test suite and report failures"
- ```
- The launch command is `opencode --model <model>`. There is no effort knob: the
- TUI has no `--variant` flag (only `opencode run` does), so an effort in the
- spec is ignored. Override the command with `[agents] oc = "..."` (a template;
- keep `{{if .Model}} --model {{shellQuote .Model}}{{end}}` if you want model
- specs honoured), and set `[models] default_opencode` or `[models.opencode]`
- aliases. Prompts are delivered with bracketed paste and verified against the
- composer: a prompt the TUI drops fails the send instead of reporting success.
- **Unattended panes and permissions.** OpenCode asks before actions its
- permission config marks `ask` (by default this includes paths outside the
- project, `external_directory`). With nobody at the pane, the request is
- auto-rejected and the turn stops. Two ways to pre-approve:
- - Launch with `--auto` (OpenCode 1.18.0+), which approves every request that
- is not explicitly denied, for that pane only:
- ```toml
- [agents]
- oc = "opencode --auto{{if .Model}} --model {{shellQuote .Model}}{{end}}"
- ```
- `deny` rules still apply, so you can pair `--auto` with deny rules for
- anything a pane must never do.
- - Set OpenCode's own `"permission"` config. It is global for every OpenCode
- session that reads it, not per pane: `~/.config/opencode/opencode.json`, a
- project `opencode.json`, or the `OPENCODE_CONFIG` /
- `OPENCODE_CONFIG_CONTENT` environment variables. Each key takes `allow`,
- `ask` or `deny`, and `"permission": "allow"` sets them all at once:
- ```json
- {
- "$schema": "https://opencode.ai/config.json",
- "permission": {
- "edit": "allow",
- "bash": "allow",
- "external_directory": { "~/shared/fixtures/**": "allow" }
- }
- }
- ```
- Path patterns support `*`, `?` and a leading `~`. Use `**` to cover a
- directory tree: OpenCode may check the parent directory's glob rather than
- the exact path it touches, so a pattern for one leaf directory can still be
- rejected.
- Use labels when you want multiple coordinated swarms on the same project while
- keeping a shared project directory:
- ```bash
- ntm quick payments --template=go
- ntm spawn payments --label backend --cc=2 --cod=1
- ntm spawn payments --label frontend --cc=2
- ntm add payments --label frontend --cc=1
- ```
- #### Staggered prompts (thundering-herd prevention)
- When several agents boot together and all pick work from `bv`/`br` at once,
- they race for the same bead. Stagger their initial prompts so each agent has
- claimed something before the next one starts looking:
- ```bash
- ntm spawn payments --cc=3 --prompt="Read AGENTS.md, then pick ready work" --stagger-mode=fixed --stagger-delay=90s
- ntm spawn payments --cc=5 --prompt="..." --stagger-mode=smart # learned rate-limit spacing
- ntm --robot-spawn=payments --spawn-cc=3 --spawn-prompt="Read AGENTS.md, then pick ready work" \
- --spawn-stagger-mode=fixed --spawn-stagger-delay=90s
- ```
- The agent at position `i` receives its prompt `i × interval` after the first.
- `--robot-spawn --spawn-prompt` (or `--spawn-prompt-file`, `-` for stdin)
- waits for readiness, delivers through robot send's dispatch path, and reports
- `stagger.schedule[]` and per-agent `prompt_deliveries[]`; the same
- `--spawn-stagger-*` flags pace `--spawn-assign-work` prompts. Set defaults for
- both commands in `~/.config/ntm/config.toml` (flags still win):
- ```toml
- [spawn]
- stagger_mode = "fixed" # none (default), fixed, or smart
- stagger_delay = "90s" # fixed-mode interval, 0-5m (default 30s)
- ```
- #### Worktree isolation and reservations
- Use `--worktrees` when agents need independent Git checkouts as well as separate
- tmux panes. NTM creates one `ntm/<session>/<agent>` branch and worktree per
- agent, so filesystem changes and destructive Git operations stay isolated until
- you deliberately merge them:
- ```bash
- ntm spawn payments --cc=3 --worktrees
- ntm worktrees list
- ntm worktrees merge cc_1
- ntm worktrees clean --session payments
- ```
- Worktrees do not replace Agent Mail reservations. Continue to reserve the files
- or areas an agent owns: reservations communicate intent, reduce merge conflicts,
- and give operators an auditable ownership record; worktrees provide the separate
- checkout boundary. Merge reviewed agent branches into `main`, then clean the
- session's worktrees when that session is finished.
- Reservations are enforced at commit time: the pre-commit hook `ntm init`
- installs runs `ntm guards check --staged`, which refuses a commit touching files
- another agent holds an exclusive reservation on and names the holder (when Agent
- Mail is unreachable it warns and records a degraded run for `ntm doctor`; set
- `NTM_GUARD_STRICT=1` to fail closed). `ntm guards install` adds the check to a
- repository without that hook, or updates an older `ntm init` hook in place.
- ### 2. Dispatch, Monitoring, and Recovery
- Humans can broadcast prompts, interrupt panes, stream output, inspect health, compare
- responses, search pane history, and keep an eye on activity without dropping to raw
- `tmux` commands.
- ```bash
- ntm send payments --all "Checkpoint and summarize current progress."
- ntm interrupt payments
- ntm activity payments --watch
- ntm health payments
- ntm watch payments --cc
- ntm extract payments --lang=go
- ntm diff payments cc_1 cod_1
- ntm grep "timeout" payments -C 3
- ntm analytics --days 7
- ```
- Pending context rotations can be acted on directly:
- ```bash
- ntm rotate context pending
- ntm rotate context confirm payments__cc_1 --action=rotate
- ntm rotate context confirm payments__cc_1 --action=compact
- ```
- CLI and dashboard confirmation execute the selected action and report its actual
- result. Rotation verifies the original process, requests a fresh handoff, and
- delivers it to a ready replacement before retiring the old pane. Confirmation
- ownership and results survive process interruption: repeating a completed choice
- returns its saved result, while a failed or interrupted choice remains visible in
- `pending`. The pending output identifies the execution, both physical panes, the
- handoff phase, and the available recovery actions. Inspect the affected panes
- before using the indicated retry or recovery action.
- Rotation transfers the existing task, Agent Mail identity, file reservations, and
- restart configuration to the replacement. Both panes are fenced against new task
- dispatch and automatic restarts while ownership is being transferred; existing
- reservation leases continue to renew. If an accepted handoff is interrupted during
- ownership transfer, `--retry` finishes that transfer without launching another
- agent or resending the handoff. When handoff delivery is uncertain, the pending
- record and pane fences remain in place for inspection, and retry or ignore cannot
- silently discard that unresolved state.
- Resolve an interrupted rotation with an explicit operator decision:
- ```bash
- ntm rotate context pending --json
- ntm rotate context recover payments__cc_1 --execution-id=EXECUTION_ID \
- --action=accept --reason="Replacement is working on the handed-off task"
- # Alternatively, stop the replacement and keep the original agent:
- ntm rotate context recover payments__cc_1 --execution-id=EXECUTION_ID \
- --action=abort --reason="Continue the task in the original pane"
- ```
- `accept` records the operator's observation of an uncertain handoff and finishes
- the existing ownership transfer without spawning or sending again. `abort`
- verifies the original ownership, stops only the recorded replacement, and verifies
- its absence before releasing the original task's rotation barrier. Work already
- performed by the replacement is preserved. An accepted ownership transfer cannot
- be aborted. Both actions require the exact execution ID and a nonempty reason;
- the decision is recorded durably, conflicting decisions are rejected, and the
- same command can resume recovery after another interruption. Changed process
- identities, foreign ownership, and unaccounted-for panes keep the recovery fenced
- for further inspection.
- Native compaction preserves the conversation and requires fresh provider context
- accounting to prove a reduction; it does not automatically clear history. Claude
- compaction reads the transcript the pane's own Claude process names in its
- session record, so it works when many Claude panes share one project directory.
- Without that binding it falls back to the directory's newest transcript and
- refuses ambiguous scope, including another Claude pane in a different session
- using the same transcript directory.
- ### 3. Work Graph Triage and Assignment
- NTM integrates with `br` and `bv` so the operator loop is not just "send prompts and
- hope." It can surface the best next task, highlight blockers, analyze impact, forecast
- work, and push assignments to specific panes or agent types.
- ```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 payments --auto --strategy=dependency
- ntm assign payments --beads=br-123,br-124 --agent=codex
- ```
- Automated assignment treats tracker labels as an authorization boundary. Add
- organization-specific approval labels globally or in `.ntm/config.toml`; project
- labels extend the global list and cannot remove built-in gates:
- ```toml
- [assign]
- operator_gated_labels = ["security-review", "legal-approval"]
- ```
- Matching is case-insensitive. NTM requires a structurally valid full actionable
- plan, uses scored triage only to rank IDs authorized by that plan, and restores
- every candidate's labels from both `br ready` and `br list --status open` so
- epics are covered. Any plan command, parse, structure, ID, label lookup, or
- coverage failure stops automated assignment before dispatch.
- Executing assignment paths can recover a corrupt local Beads SQLite index
- before reading the evidence needed to claim work. This includes automatic and
- watch assignment, coordinator assignment, and robot assignment preparation.
- NTM retries the failed read once after rebuilding from authoritative JSONL. If
- `br` refuses that rebuild because corruption prevents tombstone enumeration,
- NTM independently checks that the tombstone indexes agree and JSONL preserves
- every known tombstone before running `br doctor --repair --json`. It requires a
- verified database, validates the structured preservation evidence, and checks
- the known tombstones again after repair. An accepted partial repair retains
- its warnings, verified backups, and recovery marker. Unreadable indexes,
- missing tombstones, invalid JSONL, or failed verification stop assignment.
- Preview and dry-run commands do not request this repair. Recovery never replays
- a claim, reservation, or dispatch, and the normal eligibility and ownership
- checks still run against freshly read evidence.
- When `br` and `bv` report that no ready work exists, use the queue-dry flow to
- distinguish a genuinely empty queue from stale coordination state:
- ```bash
- # Confirm the work queue first. Do not run bare bv; use robot output.
- br ready --json
- bv --robot-triage | jq '.triage.quick_ref'
- # Diagnose why the queue appears dry.
- ntm work queue-dry --format=json | jq '{queue_dry, evidence, recommendations}'
- # Render an advisory roadmap only after the dry queue is confirmed.
- ntm work queue-dry --ideate --format=json | jq '{
- queue_dry,
- ideation: {
- status: .ideation.status,
- guard: .ideation.guard.recommendation,
- rendered: .ideation.roadmap.rendered_count,
- preview: .ideation.creation.remaining_commands
- },
- warnings
- }'
- # The same plan is available as markdown for human review.
- ntm work queue-dry --ideate --format=markdown
- ```
- Review the duplicate and novelty evidence before creating anything. If `br ready`
- has work, or `bv --robot-triage` shows actionable recommendations, claim that work
- instead of ideating. `--force` is only for an explicit preview when an operator wants
- to inspect the plan despite ready work or degraded tracker state.
- Gated creation is opt-in and still uses Beads as the source of truth:
- ```bash
- # Re-check the preview and guard before mutating Beads.
- ntm work queue-dry --ideate --format=json | jq '.ideation.creation.remaining_commands'
- # Create proposed beads only after review. The plan version is an audit token.
- ntm work queue-dry --ideate --create-beads --yes --plan-version="$(git rev-parse --short HEAD)"
- # Validate the graph and export Beads state after any mutation.
- br dep cycles --json
- bv --robot-triage | jq '.triage.quick_ref'
- br sync --flush-only
- git add .beads/issues.jsonl
- ```
- If Agent Mail, CASS, or CM are unavailable, `queue-dry --ideate` keeps running and
- marks those sources as degraded in `warnings`. Treat degraded Agent Mail reservation
- visibility as a coordination stop sign for mutating creation; fix coordination or use
- the non-mutating preview. Never edit `.beads/*.jsonl` directly, and use
- `ntm work queue-dry --help` for the current flag surface.
- ### 4. Coordination, Reservations, and Human Oversight
- NTM exposes Agent Mail and reservation workflows directly from the CLI. You can act as
- Human Overseer, inspect inbox state, review reservations, renew or force-release stale
- locks, and coordinate work without inventing an ad hoc protocol.
- ```bash
- ntm mail send payments --all "Sync to main and report blockers."
- ntm mail inbox payments
- ntm locks list payments --all-agents
- ntm locks renew payments
- ntm locks force-release payments 42 --note "agent inactive"
- ntm coordinator status payments
- ntm coordinator digest payments
- ntm coordinator conflicts payments
- ntm coordinator enable auto-assign
- ntm coordinator enable digest --interval=30m
- ntm coordinator disable conflict-negotiate
- ```
- `ntm locks force-release` is approval-gated by default (`automation.force_release:
- approval`): the first invocation files a durable approval request, a second operator
- grants it with `ntm approve <id>` (self-approval is rejected), and re-running the
- command consumes that approval and executes exactly once. Use
- `ntm policy automation --force-release auto` to allow unattended force-release, or
- `never` to disable it entirely; the serve HTTP endpoint and the dashboard conflict
- action honor the same policy setting.
- #### Pane identity badges
- In a mixed session, pane titles name the harness (`payments__cc_1`) while
- coordination happens under Agent Mail names (`BlueLake`). NTM can show each managed
- pane's assigned name in its tmux pane border next to the existing title:
- ```toml
- [agent_mail]
- enabled = true
- pane_badges = true # default false (opt-in)
- # pane_badge_format = "[{name}{drift}]{lifecycle}"
- ```
- The badge is NTM's assigned identity (the session agent registry, keyed by stable
- pane id), never whatever a later process wrote to the pane identity file. At every
- reconciliation NTM compares the assignment with the canonical Agent Mail identity
- file (legacy plain-text name or the structured record Agent Mail >= 0.3.31 writes)
- and caches the outcome in per-pane tmux user options
- (`@ntm_agent_mail_name`, `@ntm_agent_mail_state`, `@ntm_agent_mail_lifecycle`,
- `@ntm_agent_mail_label`); the window's `pane-border-format` gains a fragment that
- renders only the cached label, so tmux never calls Agent Mail while drawing.
- | Border | Meaning |
- |---|---|
- | `[BlueLake]` | current assignment; names agree (binding verified, or a legacy file that cannot be verified) |
- | `[BlueLake!]` | current assignment; the identity file disagrees (`name-disagreement`), is `missing-file` / `unreadable-file` / `invalid-file`, or its binding is `binding-unverifiable` / `binding-stale` — the assigned name is retained |
- | `[?!]` | no current assignment: `assignment-stale` (pane generation changed), `assignment-unobservable` (tmux unreadable) or `assignment-unregistered` |
- | `… (starting)`, `… (exited)`, `… (unknown)` | lifecycle observed at the last reconciliation; running agents carry no marker |
- Badges are written alongside identity assignment before the agent launches
- (`(starting)`) and reconciled on `ntm spawn`, `ntm add`, `ntm adopt`, restart/respawn
- and on explicit refresh with `ntm mapping --session <session>`, which also prints the
- discrepancy report (assigned vs resolved name, source path, assignment/observation
- state, `last_attempt_at` / `last_success_at`) and carries the same data under
- `identity` and `discrepancies` in `--json`. They describe the last reconciliation, not
- continuous liveness. Badge failures warn and never block a launch or change an
- assignment.
- Set `pane_badges = false` and run `ntm mapping --session <session>` to withdraw the
- pane options and restore the window's previous `pane-border-format` (including
- inheritance). Opt a single session out with
- `tmux set-option -t =<session>: @ntm_agent_mail_badges off`. A `pane-border-format`
- you wrote yourself that references `@ntm_agent_mail_*` is left untouched, and windows
- linked into several sessions are skipped with a diagnostic.
- Every session started by `ntm spawn` runs the coordinator inside its session
- monitor; `ntm coordinator status` shows it under Runtime (`runtime` in
- `--json`). The monitor always maintains assignment leases: it renews the file
- reservations of in-progress assignments, including those taken by a one-shot
- `ntm assign`, before their one-hour leases lapse, and releases them when the
- assigned bead closes. Every other coordinator action (`auto-assign`, `digest`,
- `conflict-negotiate`, `mail-nudge`) is off until enabled. `conflict-notify`
- never runs in the session monitor, only under `ntm coordinator run`: older
- `ntm config init` files set it to true, and it mails every holder of
- overlapping reservations in the project (`ntm coordinator status` notes when it
- is set). A foreground `ntm coordinator run` or a reservation-maintaining
- `ntm assign --watch` pauses the monitor's coordinator while it runs, so a
- session is never coordinated twice.
- `coordinator enable` and `disable` persist the selected `--config` file, or the
- global config by default, without replacing unrelated settings or comments.
- Session monitors apply a toggle within 15 seconds; restart an already running
- foreground `ntm coordinator run` to apply it there.
- The selected file may use a `[coordinator]` table or root dotted assignments
- such as `coordinator.auto_assign = false`. A whole-section inline assignment
- such as `coordinator = { auto_assign = false }` is rejected without changing
- the file; convert it to either supported form before toggling a feature.
- `ntm assign <session> --watch --reserve-files` maintains the saved file
- reservations for active assignments immediately on startup and every 30 seconds,
- including while scans or completion handlers are busy. Each maintenance pass is
- bounded to 30 seconds. The watcher renews the exact recorded leases only after
- verifying the current task claim and pane owner, and releases recorded leases
- when the task is confirmed terminal. It does not recreate expired or missing
- leases; failures remain visible, including under `--quiet`, and are retried.
- The monitor-hosted coordinator and `ntm coordinator run` use the same
- maintenance path before admitting new work.
- If one pane cannot be observed, independently verified healthy assignments can
- still renew and confirmed terminal work can still be cleaned up. Unverified
- assignments remain in the ledger, and a degraded coordinator cycle reports an
- error without dispatching new work. Watch mode checks the current saved ledger
- before exiting with `--stop-when-done`.
- The coordinator also recovers a delivered assignment when its original physical
- pane disappears. It verifies absence across the entire tmux server, rereads agent
- registries to rule out a moved or rebound owner, and checks the exact current
- Beads claim and recorded reservations. Only then does it persist task failure,
- release that assignment's leases, and reopen its claim for ordinary reassignment.
- Incomplete observations, a remaining pane, changed ownership, or failed cleanup
- keep the assignment protected. Interrupted cleanup resumes from its durable
- record; the previous prompt remains recorded as sent and is not replayed.
- ### 5. Safety Policy and Approvals
- NTM includes a first-class safety system for destructive or sensitive actions. Policy
- rules define what is allowed, blocked, or approval-gated. Approvals are durable, auditable,
- and support SLB-style two-person workflows for high-risk operations.
- ```bash
- ntm safety status
- ntm safety check -- git reset --hard
- 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 abc123
- ntm approve abc123
- ntm approve deny abc123 --reason "wrong target branch"
- ```
- Every Claude agent NTM launches (spawn, add, robot spawn, restart, restore, rotation,
- swarm) gets a Claude Code `PreToolUse` hook through `--settings` that checks each Bash
- command against this policy and refuses blocked ones (`[safety] claude_policy_hook`,
- default on). Claude Code runs `PreToolUse` hooks even under
- `--dangerously-skip-permissions`, and runs only hooks a settings file or `--settings`
- lists, so `ntm safety install` also registers its hook script in
- `~/.claude/settings.json` for Claude sessions started outside NTM, and `ntm safety status`
- reports the hook as installed only when it is registered. dcg and rch hooks ride on the
- same `--settings` when those integrations are enabled and installed. A custom
- `[agents] claude` command whose last shell command is not the `claude` invocation (a
- pipe, a subshell, a wrapper script) must place the hooks itself with
- `--settings {{shellQuote .ClaudeSettings}}`; otherwise NTM launches it without them and
- warns at every launch.
- With `[integrations.dcg] enabled = true`, command lines in messages bound for non-Claude
- agents are checked by dcg before delivery. `ntm send`, `--robot-send` (including `--track`)
- and REST sends all refuse a blocked command — robot callers get `DESTRUCTIVE_COMMAND_BLOCKED`
- — and each refusal counts toward `ntm metrics` destructive-command incidents. A missing dcg
- binary skips the check; a check that errors or is interrupted refuses the send instead.
- ### 6. Pipelines, Templates, Recipes, and Workflow Assets
- NTM supports several layers of reusable automation:
- - `recipes`: reusable session presets
- - `workflows`: runnable orchestration patterns such as pipeline, ping-pong, and review-gate — `ntm workflow run <name>` executes a template's coordination loop against a live session (`ntm spawn -t <name>` only uses a template's agent counts to size a session)
- - `template`: prompt templates and substitutions
- - `pipeline`: executable multi-step agent workflows with variables, dependencies, resume, and cleanup
- - `session-templates`: higher-level session layouts
- ```bash
- ntm recipes list
- ntm recipes show full-stack
- ntm workflows list
- ntm workflows show red-green
- ntm workflow run red-green --var feature="parser rewrite"
- ntm workflow run ./my-flow.toml --session payments
- ntm template list
- ntm template show fix-bug
- ntm send payments --cc -t marching_orders --bead bd-123 # rendered per pane: own {{agent_num}}/{{agent_type}}
- ntm pipeline run .ntm/pipelines/review.yaml --session payments
- ntm pipeline status run-20241230-123456-abcd
- ntm pipeline list
- ntm pipeline resume run-20241230-123456-abcd --mode=continue
- ntm pipeline cleanup --older=7d
- ```
- Workflow templates with manual gates, including `review-pipeline` and
- `specialist-team`, can wait for an operator to select a specific transition:
- ```bash
- ntm workflow status --session payments --json
- ntm workflow trigger --session payments --token "MANUAL_GATE_TOKEN_FROM_STATUS" \
- --transition 0 --reason "Design reviewed and ready for implementation"
- ```
- Choose the exact index from `manual_gate.transitions`, together with that gate's
- `token`. A gate appears after the stage's prompts have been delivered. Its token
- stays stable while output is observed, and changes when work is retried, an agent
- is replaced, or another stage visit begins. The command records one immutable
- decision; the active runner applies it on its next poll and records it in stage
- history. Repeating the same choice and reason returns the original receipt.
- Decisions can also be recorded while a runner is offline or paused. Continue
- with `ntm workflow run TEMPLATE --session payments --resume` to apply the saved
- decision and continue from the existing delivery checkpoint. Each later manual
- gate requires its own choice. Use `--project-root DIR` with status and trigger
- when the project is elsewhere; `workflow run --fire-manual` remains the explicit
- option for automatically advancing every manual gate.
- Workflow checkpoints also retain the selected tmux endpoint: local, or the exact
- SSH target. `workflow status` reports it, and `--resume` requires that original
- endpoint even if another host has matching pane IDs and PIDs. Legacy checkpoints
- without an endpoint remain inspectable, but require independent inspection and
- an explicit `--restart` before running the workflow again. Changing an endpoint
- also invalidates its manual gate decisions.
- SSH workflows can use agent-output, idle, elapsed-time, and manual triggers.
- File and command triggers require NTM to run on the agents' host; remote workflows
- reject those triggers before starting, including triggers in later stages.
- A same-named local directory or explicit `--project-root` does not establish a
- shared filesystem. For SSH workflows, `--project-root` selects the local project
- directory containing the checkpoint and defaults to the local current directory.
- Workflow `stage_timeout_minutes` deadlines are saved before each prompt round.
- Downtime counts toward the deadline: `--resume` handles an expired stage before
- sending any remaining prompts. A timeout policy of `retry` starts another timed
- round, bounded by `max_retries_per_stage`; retry and agent-restart allowances
- remain consumed across resumes. Command checks and pane observations are bounded
- by the current round's remaining time.
- Successful timeout `pause` and `notify` actions retain receipts, so resuming does
- not repeat them or silently grant a fresh timeout for the same round. A timeout
- `abort`, an interrupted action with an unknown outcome, or an older timed
- checkpoint without its original deadline requires inspection and a deliberate
- `--restart`. Timeout-driven skips commit the destination stage before its prompts
- are sent, including transitions that revisit the same stage.
- The dashboard resumes pipelines in a detached worker, so closing the browser or
- restarting the HTTP server does not cancel an authorized resume. REST clients can
- request the same lifetime with `POST /api/v1/pipelines/{id}/resume` and
- `{"background":true}`. HTTP `202 Accepted` acknowledges worker startup, not
- workflow completion. Poll the existing pipeline status endpoint and cancel
- through `POST /api/v1/pipelines/{id}/cancel`; the run ID stays unchanged.
- The worker acquires exclusive run ownership before reloading the saved state and
- validating its workflow inside the configured project. Omit `session` to use the
- session from that owned checkpoint. Detached resume retains saved variables and
- rejects nonempty variable overrides. Omitting `background`, or setting it to
- `false`, retains synchronous REST resume; `pipeline_resume` jobs also keep their
- own execution and cancellation lifetime.
- Pipeline cleanup removes old checkpoints only after acquiring the run's ownership
- lock and verifying that execution and every saved command, selector, delivery,
- mail, and reservation receipt have settled. Active runs and unresolved receipts
- remain available for recovery, even when their checkpoint is old. Legacy,
- malformed, oversized, or otherwise uninspectable states are also retained;
- cleanup never treats missing evidence as permission to replay work.
- Use `ntm pipeline cleanup --older=7d --dry-run` to inspect the same eligibility
- checks without removing files. Human and JSON output include retained run IDs
- and reason codes, without command output or message contents. Shared workflow
- snapshots and stable ownership lock files are preserved. The REST cleanup
- endpoint applies the same checks and returns deleted, eligible, and retained
- counts with per-run results.
- Pipeline resume preserves completed step outputs. Prompt and template steps also
- save their delivery and response evidence: `--mode=continue` resumes observing a
- confirmed request on its original tmux host and physical pane without submitting
- it again. Partial output survives interruption, and a completed response can be
- restored even if the process stopped before saving the enclosing step result.
- Recognized composer and footer redraws are excluded from response evidence; an
- idle pane showing only the submitted prompt is not counted as completed work.
- Unknown submission outcomes, replaced pane processes or hosts, and missing output
- boundaries stop recovery with the receipt preserved. If you verify that the
- original agent received an uncertain submission, record that observation and
- continue without resending:
- ```bash
- # Inspect saved identities and obtain the exact receipt token.
- ntm pipeline recover run-20241230-123456-abcd --json
- # Accept only the inspected delivery, after checking the original agent.
- ntm pipeline recover run-20241230-123456-abcd --step-id review \
- --receipt <token-from-inspection> --accept-delivery \
- --reason "The original agent is working on the submitted review"
- # Collect the original response and continue dependent steps.
- ntm pipeline resume run-20241230-123456-abcd --mode=continue
- ```
- Recovery runs from the project containing the saved pipeline state. Inspection
- shows receipt identities without prompt or transcript contents. Acceptance
- requires the original tmux endpoint, physical pane and process, an intact output
- boundary, and the frozen workflow. It records the reason and time without sending
- input, completing the task, or starting dependent steps. Resume keeps its existing
- step-definition checks. A live run owner, stale receipt, or conflicting decision
- is refused; repeating the same receipt and reason returns the saved decision,
- including after the run completes.
- Structured `on_failure` recovery has its own delivery receipt, identified by
- the failed step's runtime ID followed by `.on_failure`. Use the exact ID and
- receipt token from inspection, including any enclosing branch or iteration
- namespace. After an uncertain fallback is accepted, resume finishes that
- original fallback without repeating the native command that triggered it.
- The original command receipt remains intact. Parent and fallback definition
- checks still apply, and the parent failure is suppressed only when the saved
- workflow explicitly configures `suppress_failure: true`.
- The dashboard exposes these decisions for failed or cancelled runs under
- **Recovery decisions**. Review the original agent or process, open the relevant
- receipt, enter your observation, and explicitly confirm what you verified.
- Command and selector decisions require the original exit code and complete
- output, including an explicitly verified empty output. Changed receipts require
- a fresh review. Recording a decision does not restart execution; use **Resume**
- separately when ready to continue in the detached worker.
- REST clients can perform the same recovery through the server's configured
- project. `GET /api/v1/pipelines/{id}/recover` requires `pipelines:read` and returns
- the `deliveries`, `commands`, and `selectors` arrays, including receipt identities,
- acceptance eligibility, refusal reasons, and exact `receipt_token` values. To record
- an agent-delivery observation, send `POST /api/v1/pipelines/{id}/recover` with
- `pipelines:write` permission, `Content-Type: application/json`, and this JSON body:
- ```json
- {
- "step_id": "review",
- "receipt": "<receipt_token from GET>",
- "accept_delivery": true,
- "reason": "The original agent is working on the submitted review"
- }
- ```
- To accept a command outcome after independently verifying that the original
- command **and all descendants have finished**, use the command receipt from GET:
- ```json
- {
- "step_id": "migrate",
- "receipt": "<command receipt_token from GET>",
- "accept_command": true,
- "exit_code": 0,
- "output": "Migration completed\n",
- "reason": "Verified the migration and all child processes finished successfully"
- }
- ```
- Use `accept_selector: true` and a selector receipt for an interrupted branch,
- foreach, or bead-query source. Exactly one acceptance flag must be true. Command
- and selector decisions require an explicit `exit_code` from 0 to 255 and `output`;
- an empty string records observed empty output, while omission or `null` is refused.
- Delivery decisions cannot include outcome values. Requests use UTF-8 JSON and must
- fit the server's 10 MiB encoded-body limit, including metadata and escaping, as
- well as the frozen workflow's capture limits. Output is never truncated or
- silently repaired. Use the CLI for binary selector output or larger captures
- within its 16 MiB limit. Enabled request redaction rejects detected secrets in
- output or reasons before persistence.
- Acceptance records the same durable decision as the CLI without launching work,
- signalling processes, or inferring settlement from a saved PID. Continue with
- `POST /api/v1/pipelines/{id}/resume`, or submit a `pipeline_resume` job for
- pollable execution. Inspection and acceptance expose receipt metadata without
- prompt, transcript, or captured output contents. Recovery requests cannot select another project
- or replace the saved session. Stale receipts, conflicting observations, and a live
- run owner produce a conflict response without changing the checkpoint.
- Each REST pipeline request retains the project selected when it was admitted.
- Changing `project_dir` through the configuration API affects subsequent requests;
- it cannot redirect an admitted request's workflow lookup, run ownership,
- execution, or cancellation. HTTP idempotency keys use that same project scope,
- so retrying a key after switching projects cannot replay the previous project's
- success. Clearing the configured project also cannot replay a cached file-based
- operation that required it. File-based run, validation, and resume still require
- a configured project; recovery additionally requires an accessible absolute
- project directory.
- Foreground command steps in the main workflow have an explicit recovery path
- for the case where the command finished but its final checkpoint was lost. `pipeline recover`
- includes these command receipts in its `commands` JSON array, with eligibility
- and refusal information. Before accepting one, independently verify that the
- original command **and all its descendants have finished**, then supply its
- observed exit code and complete captured output.
- A `wait: none` launch acknowledgement does not establish successful execution.
- A later unsuccessful exit makes the final workflow fail, while healthy sidecars
- stopped at normal workflow completion remain expected shutdowns. On Linux, a
- leader failure observed before cleanup signals retains its original exit error
- even if workflow shutdown begins before its receipt is saved. Failed, settled
- background receipts follow the existing resume reconciliation: the failed command
- runs again while completed dependent steps retain their results. Uncertain
- settlement still refuses replay.
- A background command inside a parallel group or parallel foreach keeps running
- after its container finishes normally. It remains available to downstream steps
- and post-pipeline hooks until workflow finalization stops and joins it. Explicit
- cancellation and fail-fast still stop affected commands.
- An explicit command or enclosing parallel-group deadline remains in force even
- after the container returns; expiry is recorded as a background failure. Moving a
- sidecar into a nested container therefore does not shorten its healthy lifetime
- or remove its cancellation and timeout boundaries.
- A fatal main step failure requests cancellation of its main sidecars and joins
- their supervision before running post-pipeline hooks. This lets SIGTERM handlers
- and receipt persistence finish before hooks release resources. The workflow context stays
- live for those hooks; caller cancellation during the wait switches to `on_cancel`
- cleanup. Returned uncertainty still leaves an unresolved receipt and refuses
- replay.
- Cancellation before the first execution attempt retains explicit no-dispatch
- evidence. Native commands cancelled before launch retain a settled receipt with
- process ID zero. Ordinary resume can continue this proven-unstarted work; prior
- attempts and unresolved receipts keep their existing replay restrictions.
- For a command with `wait: none`, an explicit step `timeout` applies to the
- background process's whole lifetime. Expiry requests normal command cleanup,
- records a timeout outcome, and prevents the final workflow from reporting success.
- Already-admitted dependent work keeps its existing scheduling. A later workflow
- cancellation does not erase the original timeout cause. Without an explicit
- timeout, a sidecar retains the workflow's lifetime instead of inheriting the
- foreground command default. Uncertain cleanup still leaves an unresolved receipt
- and refuses replay, even when the deadline has expired.
- On Unix, a failed process-group observation keeps the command under supervision
- and is retried within its existing execution deadline. It does not request
- cancellation or shorten the five-second SIGTERM grace period. After the final
- group signal, NTM retries observation for up to one second while retaining the
- original group leader's identity. If that final census remains unknown after a
- successful signal, a separate five-second recovery window retries observation
- without sending another signal. The original leader and exclusive run ownership
- remain held until recovery finishes, so later quiet evidence can settle the exact
- foreground, background, or selector receipt before the run returns. A confirmed
- live group or failed final signal keeps the original cleanup budget. A complete
- quiet-group observation and complete output capture are both required for a
- `settled` receipt.
- The stdin feeder must also finish copying or receive a kernel broken-pipe
- response confirming that its readers closed. A forced stdin-pipe closure during
- the wait timeout leaves the receipt unresolved, including when a nonzero command
- exit would otherwise hide that pipe error. Completing the feed does not establish
- containment of descendants that deliberately leave the group and no longer keep
- NTM's I/O open.
- Linux observes the original leader through its stable pidfd when supported.
- Transient leader-observation failures then retain supervision within the existing
- execution deadline, so later recovery can still settle the receipt. Cancellation
- allows a separate 250 ms of observation recovery before falling back to leader
- cleanup. A system without a stable handle or pidfd-based wait support retains the
- bounded 250 ms observation fallback. An explicit loss of child ownership ends
- observation and signalling immediately; a saved numeric PID cannot authorize a
- later signal.
- Linux requires cancellation of the command's own context before group cleanup,
- even when an observation error contains a cancellation or deadline error. It rechecks the
- original leader's waitability before SIGTERM, before SIGKILL, and before accepting
- settlement. Lost ownership during observation or grace leaves the receipt
- unresolved and prevents further group signals, preserving the ordinary-resume
- replay barrier.
- If leader observation remains unavailable during explicit cancellation, NTM can
- still send SIGTERM through the original leader's pidfd and wait up to five seconds
- for graceful exit. Failed pidfd observations preserve that grace period before
- SIGKILL. This fallback never signals a numeric PID or process group. Stopping
- only the leader cannot settle the command's receipt because descendants may
- remain alive. If no stable handle is available, the command remains unresolved
- without a fallback numeric signal.
- For normal Linux completion, NTM checks that the kernel's process-creation counter
- did not change during a quiet census and that zombie process leaders have no
- surviving threads. A child that forks and exits during enumeration therefore
- cannot hide a still-running grandchild. A raced census is retried; natural
- completion sends no termination signal. Host-wide process churn can delay this
- proof, while the command's existing deadline and cancellation remain effective.
- The same proof requires a complete, stable `/proc` mount view. Modes that hide
- process directories, such as `hidepid=2` or `hidepid=4`, cannot authorize a settled
- receipt; an apparently empty visible group does not prove hidden work ended.
- The mount must also expose the observer's own PID namespace: a single `NSpid`
- value in `/proc/self/status` must match its process ID before and after the
- census. An ancestor namespace's process numbers can alias unrelated local
- processes, so matching numeric group IDs alone cannot prove settlement. Missing
- namespace evidence (including kernels without `NSpid` support or `CONFIG_PID_NS`)
- also leaves observation uncertain; use a complete procfs mount for the process's
- own namespace on a kernel that supplies this evidence.
- If cleanup returns without that proof, the receipt becomes `unresolved`, with the
- failed or cancelled outcome and cleanup details preserved, rather than remaining
- `running` after supervision ended. Ordinary resume and automatic retry refuse
- these receipts. A saved PID disappearing later is not sufficient evidence for
- automatic reconciliation: its original group identity is no longer pinned.
- Use the explicit recovery procedure below only after independently verifying the
- original command and its effects.
- Handling a command or selector error with `on_error: continue` can let other
- steps finish, but it cannot establish process settlement. At finalization, any
- remaining unsettled process receipt prevents a successful workflow outcome.
- The original receipts remain unchanged for inspection and supported recovery;
- confirmed settled failures keep their existing error-policy behavior.
- An `on_failure` action or fallback waits until its failed source and owned
- process work have a known outcome. Unresolved command and selector receipts keep
- their failed scheduler results, without publishing failure-action variables or
- dispatching fallback work that would prevent later acceptance. Once the original
- outcome is explicitly accepted, ordinary resume applies the authored failure
- policy. Unrelated scopes and healthy supervised background children keep their
- normal failure handling.
- Ordinary execution checks owned command and selector receipts before publishing
- successful scheduler results. An uncertain success hook leaves its parent failed
- and stops later hooks. An uncertain foreach body also stops its iteration before
- a completed-round checkpoint is written. Explicit acceptance and resume can then revisit the
- unfinished work while retaining the successful parent's native receipt, earlier
- completed hooks, and immutable accepted outcomes. Ordinary settled hook failures
- keep their existing logging behavior; healthy background acknowledgements remain
- valid while their command supervision is active.
- Success-hook sequences now checkpoint the completed parent body before the first
- hook, then checkpoint each consumed hook outcome before starting the next one.
- Cancellation leaves the parent unfinished until its remaining hooks settle.
- Ordinary resume reuses the successful body and earlier consumed outcomes,
- including advisory hooks that returned a known failure after producing effects.
- The same continuation applies inside branches, parallel groups, foreach
- iterations, and nested success hooks. A delivered agent prompt resumes observation;
- an unconfirmed delivery still requires its existing explicit recovery decision.
- These checkpoints bind both the authored and materialized step definitions,
- ordered hook identities, results, and output bindings. Missing or altered
- consumption evidence stops resume before downstream work. Completed hook outputs
- can be rebuilt from the saved evidence even when the variable cache is missing.
- Explicit whole-run reset and valid forced-iteration scopes clear the matching
- hook progress; restarting a consumed failed hook alone refuses a replay that
- would leave its containing work inconsistent. Background commands retain their
- existing supervised relaunch behavior. This records orchestration progress; it
- does not make a remote side effect and its local checkpoint one atomic operation.
- An older checkpoint may already report `completed` while retaining an unfinished
- foreground command or selector receipt. If that step's scheduler result is
- failed or cancelled, recovery inspection can offer the same explicit acceptance
- procedure. Acceptance retains all existing identity, ownership, and
- enclosing-work checks, then saves the observed outcome and changes the
- contradictory workflow status to `failed` in one checkpoint, with a recovery
- diagnostic. Ordinary resume then applies the accepted outcome. Completed work
- and any other unresolved receipts retain their evidence; repeating an accepted
- decision after successful resume does not reopen the run.
- A failed or cancelled scheduler result from an older checkpoint is not evidence
- that a command group stopped. Without an execution receipt, ordinary resume also
- refuses these steps and background rerun markers; an intentional replay requires
- `--mode=restart-failed` or an explicit reset. Proven-settled failures retain normal
- retry behavior. Newly cancelled parallel children that never entered their executor
- carry separate scheduler evidence, so they can resume without being mistaken for
- previously launched work.
- During cancellation, NTM saves the cancelled state before waiting for background
- command supervision to return and persist its receipts. Only then does it start
- authored `on_cancel` cleanup, so graceful sidecar shutdown can finish before
- cleanup releases its resources. Each cleanup step receives its full configured
- timeout after this wait. Returned uncertainty still leaves an unresolved receipt;
- it does not suppress authored cleanup or prove that every process has exited.
- Background commands started by cleanup are also joined before the run returns.
- Shell branch predicates, external foreach sources, and bead queries also persist
- launch intent before starting their command. Their output is usable only after
- the owned group settles and both captured streams reach EOF. A returned cleanup
- failure leaves an `unresolved` entry in `command_evaluations`; automatic retries
- and ordinary resume refuse it even when a failure handler completed the enclosing
- step. If the original source and its descendants finished and its final outcome
- can be independently verified, `pipeline recover --accept-selector` can record
- that outcome without repeating its effects. Inspect the original work before
- deliberately authorizing `restart-failed`, a containing `force-iter` scope, or a
- whole-run reset. Unfinished external selectors
- from older checkpoints without sufficient source or decision evidence require the
- same explicit decision.
- Successful evaluations retain their complete bounded output in the checkpoint
- before it can choose a branch or admit iterations. Ordinary resume reuses that
- output, including after a crash between command completion and decision storage,
- instead of repeating source effects. Reuse requires the same step definition,
- expanded executable and arguments, working directory, effective environment, and
- capture limits. Changed inputs require restoring the original inputs or an
- explicit replay of the affected scope. A failed child does not discard an already
- admitted branch choice or foreach item list. A normal nonzero source exit with
- proven cleanup still clears its receipt and retains configured retry behavior.
- External branch, foreach, and bead-query sources use `step.timeout`, or the
- executor's default timeout when no step override is set, and the workflow's
- `max_command_stdout_bytes` and `max_command_stderr_bytes` limits. A source deadline
- applies to source evaluation; branch and foreach bodies keep their own lifetimes.
- The run also limits retained selector stdout and outstanding stdout reservations
- with `settings.limits.max_selector_output_bytes_total` (default **32 MiB**).
- Before a new source starts, it reserves its entire `max_command_stdout_bytes`
- allowance. Successful completion replaces that reservation with the exact saved
- bytes; uncertain completion keeps the full reservation and its replay barrier.
- Parallel sources wait within their existing deadlines when active captures can
- free enough capacity. If saved output or unresolved receipts leave insufficient
- capacity, the next source fails before launch, without creating a receipt or
- performing its command's effects. Already saved outcomes remain reusable even
- when an older checkpoint exceeds the current budget.
- For sources that return small records, a smaller `max_command_stdout_bytes`
- allows more concurrent reservations. To raise capacity for an existing frozen
- run without resetting its evidence, use
- `ntm pipeline resume <run-id> --max-selector-output-bytes-total 67108864`.
- This positive byte override applies only to that resume attempt; it preserves
- the frozen workflow, original capture limits, and cached output identities.
- The REST resume endpoint and `pipeline_resume` jobs accept the corresponding
- `max_selector_output_bytes_total` field. This budget covers selector stdout and
- reservations; other checkpoint fields, parsed items, and temporary serialization
- buffers have separate memory and storage costs.
- Dynamic step expansion is bounded separately by
- `settings.limits.max_step_count_total` and `max_materialized_step_nodes`, both
- defaulting to **100,000**. The first limits distinct concrete runtime IDs across
- the run; retries, ordinary resume, and explicit scope resets reuse the existing
- admission ledger. The second limits literal definitions and active planner
- copies, checked before eager foreach expansion, branch decoding, and parallel
- body allocation. Nested planners refuse insufficient capacity promptly.
- Neither limit is a byte cap for all pipeline memory or checkpoint data.
- Main work stops on admission exhaustion even under continue or retry policies.
- Authored cancellation and post-pipeline roots reserve a separate bounded ID
- allowance before main execution, so an earlier dynamic cleanup cannot consume
- a later release root's slot. Existing process cleanup and uncertain-execution
- replay barriers remain authoritative; an admission is never proof of execution
- or termination. A successful command whose success hook exceeds capacity keeps
- its receipt, allowing the hook to finish on resume without repeating the command.
- For a frozen run, raise either limit for the current attempt with
- `ntm pipeline resume <run-id> --max-step-count-total 200000
- --max-materialized-step-nodes 200000`. The REST resume endpoint and
- `pipeline_resume` jobs accept the corresponding snake_case fields. Positive
- overrides preserve the frozen workflow and native receipts; zero uses the
- frozen policy, and negative values are rejected before checkpoint mutation.
- See [step admission limits](docs/WORKFLOW_SCHEMA.md#step-admission-and-materialization-limits)
- for accounting and cleanup details.
- Dry runs preview dynamic foreach sources without executing their shell commands
- or `br` queries; static item and model lists can still be expanded for preview.
- Foreach item bindings also apply to command `stdin`, native `bead_query` fields,
- Agent Mail send and inbox requests, and reservation acquisition and release
- requests. For example, a loop with `as: assignment` can send mail to
- `${assignment.agent}`, reserve `${assignment.path}`, and query beads labelled
- `${assignment.label}`. Each iteration receives its own request values, including
- inside selected branches, success hooks, and failure recovery handlers. Nested
- loops retain their own item bindings; round variables and downstream step
- outputs resolve when the corresponding operation executes.
- For a foreground command receipt:
- ```bash
- ntm pipeline recover run-20241230-123456-abcd --json
- ntm pipeline recover run-20241230-123456-abcd --step-id migrate \
- --receipt <command-receipt-from-inspection> --accept-command \
- --exit-code 0 --output-file migration-output.txt \
- --reason "Verified the migration and all child processes finished successfully"
- ntm pipeline resume run-20241230-123456-abcd --mode=continue
- ```
- Both `--exit-code` and `--output-file` must be supplied explicitly; an empty
- regular file records an observed empty output. Use complete UTF-8 stdout for a
- step with `output_parse`, or captured combined stdout and stderr otherwise.
- Recovery enforces a 16 MiB bound and the frozen workflow's stdout limit.
- Inspection and acceptance responses contain identities and output fingerprints,
- without command text, environment values, or captured output.
- Command acceptance records an immutable observation without starting a process,
- parsing output, or executing dependent work. Ordinary resume checks the exact
- materialized command definition and applies the existing output parser and
- failure policy, including parsed output and named variables used by dependents.
- A nonzero exit code does not authorize an automatic rerun. Repeating the same
- receipt, reason, exit code, and exact output returns the saved decision, including
- after completion; a conflicting observation is refused. A live run owner,
- background command, cleanup or post-pipeline command, or command whose enclosing
- work already completed prevents acceptance. Recorded PIDs are diagnostic only: recovery neither infers completion
- from PID disappearance nor signals a saved process ID.
- For an interrupted selector receipt, inspection includes a `selectors` array
- with its exact receipt token, acceptance eligibility, and refusal reason:
- ```bash
- ntm pipeline recover run-20241230-123456-abcd --json
- ntm pipeline recover run-20241230-123456-abcd --step-id choose \
- --receipt <selector-receipt-from-inspection> --accept-selector \
- --exit-code 0 --output-file selector-stdout.bin \
- --reason "Verified the original selector and all descendants finished"
- ntm pipeline resume run-20241230-123456-abcd --mode=continue
- ```
- First independently verify that the original selector **and all its descendants
- have finished**. Supply its observed exit code and complete stdout, including an
- empty regular file when it emitted no stdout. Selector output is retained as
- exact bytes, including non-UTF-8 data, and is bounded by the original capture
- limit, the frozen workflow's limit, and the 16 MiB recovery limit. Recovery
- responses expose only identity, decision metadata, byte counts, and hashes.
- Acceptance writes a distinct `accepted` receipt with an immutable decision hash.
- It preserves the original intent or cleanup status, timestamps, diagnostic error,
- and recorded PID. An intent whose PID was never checkpointed stays without a PID;
- the operator's observation does not invent native process-settlement evidence.
- No command, signal, branch selection, or item admission occurs during acceptance.
- Ordinary resume checks the exact selector definition and expanded invocation
- before consuming successful output. A nonzero accepted exit follows normal
- failure handling without relaunching the source, even when retry is configured.
- The exact receipt, reason, exit code, and stdout replay the same saved decision;
- changing any part is refused. Recovery also refuses a live run owner, a stale or
- corrupt receipt, legacy evidence without an invocation identity, changed frozen
- definitions, already-admitted output, completed enclosing work, and selectors in
- cleanup or post-pipeline phases. An intentional reevaluation requires the normal
- explicit replay scope. Older executors that do not understand `accepted` refuse
- that receipt rather than interpreting it as native settlement.
- Pipeline `mail_send` steps also checkpoint their send intent and delivery receipt.
- If a response is lost or the run stops while a send is unresolved, automatic
- retries and ordinary resume refuse to send the message again: the recipient may
- already have received it. Inspect the recipient's inbox and original thread
- before deliberately choosing `--mode=restart-failed` to resend. A saved successful
- receipt restores the original output and parsed variables without another send,
- even if the scheduler's final step checkpoint was lost. A local output-parsing
- failure does not authorize resending delivered mail. Explicit server refusals
- remain eligible for the step's normal retry policy. Interrupted sends from older
- checkpoints without a receipt require the same deliberate replay decision.
- Pipeline file reservations retain their resolved request, exact lease identities,
- and partial grant evidence. A lost acquisition response or unverified grant never
- triggers automatic reacquisition. Resume checks that retained protection still
- has the original IDs, owner, paths, mode, and creation identity, with live expiry,
- before dispatching further work. A same-ID renewal is accepted; a replacement
- lease on the same path is not adopted. Release steps for this run's acquisitions
- select only the recorded IDs and verify their disappearance, so another run's
- same-path reservations remain intact. Standalone release steps without acquisition
- evidence retain their explicit path behavior.
- Verified partial grants remain available for exact-ID cleanup. Unverified handles
- are inspection evidence, not authority to release somebody else's leases. Finish
- releasing known active leases before resetting acquisition history. If an authored
- cancellation or finalization hook already released protection, resuming unfinished
- protected work requires a whole-workflow reset to acquire it again; iteration
- replay cannot retain those released locks. Cleanup-only resume can finish when the
- original IDs have already expired or disappeared.
- While a pipeline is running, a heartbeat renews its verified reservation IDs
- before expiry, including during long commands, agent waits, and post-pipeline
- work. Independent readback must confirm the original lease identities and an
- extended expiry; a lost renewal reply is accepted only when that readback proves
- protection. Dispatch also checks ownership immediately before sending more work.
- Lost, replaced, expired, or unverifiable protection fails the run and cancels
- active waits and commands. Input already delivered to an external agent cannot
- be recalled. Authored `on_cancel` cleanup still runs; reservations are never
- automatically reacquired or released. Use explicit workflow release steps.
- If you instead intend to repeat failed or interrupted agent work, inspect the
- original pane before using `--mode=restart-failed`; that mode still preserves
- completed delivery receipts. Use
- `--keep-state=false` or `--mode=force-iter --step-id=<id> --iteration=<n>` for an
- intentional reset or iteration replay. Commands with a normally settled outcome
- retain ordinary retry behavior; operator-accepted outcomes require an explicit
- reset before repeating them. An unresolved command is never automatically
- repeated. Before deliberately restarting one, inspect its side effects and stop
- any surviving command processes. These restart choices can repeat side effects.
- ### 7. Durable State, Audit, and Recovery
- NTM treats recoverability as a core feature. Sessions can be checkpointed, timelines can
- be replayed, audit records can be exported, and prompt/session history remains available
- for analysis or resumption.
- ```bash
- ntm checkpoint save payments -m "pre-migration"
- ntm checkpoint list payments
- ntm checkpoint restore payments
- ntm checkpoint restore payments last --as payments-recovered --directory /path/to/recovery-worktree
- ntm sessions save payments
- ntm sessions restore payments --name payments-restored --launch
- ntm sessions resume payments --name payments-resumed
- ntm timeline list
- ntm timeline show <session-id>
- ntm history search "authentication error"
- ntm audit show payments
- ntm conflicts payments
- ntm resume payments
- ```
- Ordinary `ntm spawn payments --cc=2` also restores the latest readable local handoff for
- that session from the resolved project directory. The previous goal, immediate
- task, decisions, and next steps are delivered before the new user prompt through
- the same readiness and submission checks as other spawn prompts. This works
- without Beads, Agent Mail, or CM being installed. The handoff uses a bounded
- recovery budget, and JSON output reports its source as `recovery.handoff_path`.
- `--no-recovery`, `recovery.enabled = false`, or
- `recovery.auto_inject_on_spawn = false` disables this injection. The shared
- handoff reader can fall back to an older readable file if the newest is corrupt;
- the reported source identifies the file actually used. If no handoff can be read,
- or its session or project does not match, spawn reports partial recovery and can
- proceed with its other available context.
- Remote tmux sessions skip local handoffs and report that source as unavailable;
- NTM does not treat a matching local path as proof of the remote project's identity.
- To continue a specific Agent Mail conversation in newly spawned agents, use
- `--thread`:
- ```bash
- ntm spawn payments --cc=2 --thread=FEAT-123
- ntm spawn payments --label=follow-up --cc=2 --thread=FEAT-123 --prompt="Finish the agreed tests"
- # For servers requiring an authenticated thread reader:
- ntm spawn payments --cc=1 --thread=FEAT-123 --thread-agent=BlueLake
- ```
- NTM reads the thread summary once from the resolved project's Agent Mail scope,
- then includes its key points and action items in each agent's initial prompt.
- Per-agent defaults, `--prompt`, and pane-specific marching orders follow that
- context. Delivery uses the existing readiness checks and configured secret
- redaction. The new agents keep their own assigned identities; the read does not
- create an extra identity. `--thread-agent` uses an existing registration token
- cached by NTM for that project when the server requires authenticated reads.
- Thread continuation requires `agent_mail.enabled = true` and the server's
- `summarize_thread` tool. It requests a deterministic summary with LLM refinement
- and raw message examples disabled. A missing, unavailable, mismatched, empty,
- or oversized summary stops the command before project-directory creation,
- hooks, or tmux changes; the prepared context is limited to 32 KiB. The flag
- accepts one thread ID and is unavailable with remote tmux sessions. It remains
- active with `--no-recovery` and `--no-cass-context`, since it is an explicit
- request. Successful JSON output identifies the context with `thread_id` without
- echoing the conversation contents.
- Checkpoint restoration accepts `--as` to recover into a different tmux session
- without replacing the source session or rewriting its checkpoint. The REST
- restore endpoint accepts the same option as `target_session`. A separate session
- still uses the checkpoint's working directory unless `--directory` (REST:
- `custom_directory`) selects another working tree. Restores honor cancellation;
- JSON responses retain the last restore stage, pane count, warnings, and
- interruption status so partially restored sessions can be inspected before retrying.
- Newly spawned agents also record their rendered launch command independently of
- the pane title. Checkpoints preserve that command and its model, persona,
- reasoning effort, and account-profile reference. Restore validates these inputs
- before replacing an existing session, then recreates any configured Claude
- credential isolation for the destination pane. Prepared persona prompt files
- remain external references: a missing file or changed contents stops automatic
- replay. Explicit pane or plugin environment values are not copied into this
- record; recovery reports missing inputs instead of silently substituting the
- current environment. Older panes without a launch record retain the existing
- command-reconstruction path.
- Saved sessions preserve each pane's working directory and the same recorded
- launch settings, so panes in separate worktrees return to their own directories.
- `sessions restore --launch` replays those settings; `sessions resume` also
- replaces the native conversation selector when the save contains a fresh
- provider binding. Recorded commands keep their model, reasoning, persona, and
- account settings instead of taking current defaults. Native resume refuses
- ambiguous shell commands or conflicting conversation selectors before `--force`
- replaces a live session. Older saves without a recorded command retain the
- existing CASR preference. Missing worktrees, changed persona files, unavailable
- profiles, and omitted environment inputs prevent automatic relaunch. Agent
- counts report successful command dispatch; they do not assert that an agent has
- finished starting.
- ### 8. Multi-Project Swarm Execution
- `ntm swarm --json` launches the requested swarm and returns an execution receipt.
- Use `swarm plan` or `--dry-run` to preview allocations without creating sessions.
- ```bash
- ntm swarm plan --scan-dir=/projects --json
- ntm swarm --scan-dir=/projects --json --wait-ready
- ntm swarm --scan-dir=/projects --json --prompt="Run the tests and report failures"
- ```
- The receipt distinguishes planned allocations, created sessions and physical
- panes, agent launches, initial prompt delivery, and optional readiness results.
- Partial failures and cancellation return a nonzero exit status while retaining
- the actual outcomes. Prompts go only to successfully launched agents that pass
- readiness and identity checks; surviving sessions remain available for inspection.
- `--auto-rotate-accounts` starts an acknowledged resident monitor for eligible
- local Claude and Codex panes. It checks CAAM account availability and the actual
- configured launch commands before creating sessions. JSON receipts identify
- eligible panes, declined providers, and each monitor's PID and generation;
- `swarm status --json` checks the resident's live process and heartbeat.
- If monitor startup partially fails, the command returns a nonzero exit status
- and preserves launched agents, successful monitors, and their startup receipts.
- ```bash
- ntm swarm --scan-dir=/projects --auto-rotate-accounts --json
- ntm swarm --scan-dir=/projects --auto-rotate-accounts --force-global-auth-clobber --json
- ```
- This recovery lane requires Linux, default global credentials, and a live
- provider process with a verifiable open main conversation transcript. Codex
- also requires consent through the global-auth flag above or
- `swarm.force_global_auth_clobber = true` in the configuration. Scoped profiles,
- isolated credentials, custom credential homes or providers, and ambiguous
- commands for otherwise eligible panes fail preflight before session creation.
- Unsupported or excluded providers and Codex without global-auth consent can
- launch unmonitored, provided at least one eligible pane remains. A temporary
- lack of transcript evidence defers recovery until another observation; NTM does
- not infer a conversation from the newest file in a worktree. Configured provider
- restrictions and reset horizons still apply.
- Recovery preserves the recorded command and native conversation, verifies the
- replacement process and conversation, and reports account activation separately
- from successful conversation recovery. A provider lock and durable activation
- receipt coordinate multiple sessions: stalled sibling panes can resume using
- the already activated account without repeatedly switching the global account.
- Local session kill and forced checkpoint or saved-session replacement wait for
- their resident to finish any in-flight recovery before destroying the session.
- Remote tmux operations leave local monitors and processes untouched.
- ## Robot Mode and Local API
- NTM has two automation layers:
- - `--robot-*` for local, machine-readable CLI interactions
- - `ntm serve` for REST, SSE, WebSocket, and OpenAPI-backed integrations
- ### Canonical Robot Surfaces
- 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 surfaces:
- ```bash
- ntm --robot-send=payments --msg="Summarize current blockers." --type=claude
- ntm --robot-ack=payments --timeout=30s
- ntm --robot-tail=payments --lines=50
- ntm --robot-mail-check --mail-project=payments --urgent-only
- ntm --robot-cass-search="authentication error"
- ```
- Optional CM memory injection (`--with-memory` or `memory.send_injection`) uses
- the selected panes' verified project directory and the target session's daemon.
- Running the command from another checkout cannot select that checkout's memory,
- including when both projects have the same directory name. The JSON memory
- receipt identifies the queried workspace or explains why injection was skipped.
- Remote sessions and unresolved or mixed project scopes skip local CM retrieval
- and continue ordinary prompt delivery. Context-pack builds use the same explicit
- workspace scope.
- With `--track`, successful acknowledgment reports memory feedback to the daemon
- that supplied the rules. Changing daemon PID records while the send is pending
- does not redirect that feedback. Canceling the command stops pending memory
- retrieval and acknowledgment tracking.
- ### REST, SSE, WebSocket, and OpenAPI
- Run the local server:
- ```bash
- ntm serve
- ```
- Set the default project with `ntm serve --project-dir /absolute/project/path`.
- `PATCH /api/v1/config` changes it at runtime for every caller:
- `{"project_dir": "/absolute/other/project"}` selects another project, and
- `{"project_dir": ""}` or `{"project_dir": null}` resets it to the
- `--project-dir` value (no project if the server started without one). Omitting
- `project_dir` leaves it unchanged. `GET /api/v1/config` reports the current
- `project_dir` and the reset target as `startup_project_dir`.
- The selection scopes later requests on every project-scoped route, including
- mail, beads, jobs, and pipelines. Jobs and pipeline runs already admitted, and
- mail requests already in flight, keep the project they started with. The
- target must be an existing directory, so a reset returns 400 and changes
- nothing if the startup directory has since been removed.
- Agent Mail operations under `/api/v1/mail/` and file reservation operations under
- `/api/v1/reservations` also accept a `project` query parameter, so agents in
- multiple projects can share one server:
- ```bash
- curl --get http://localhost:7337/api/v1/mail/inbox \
- --data-urlencode 'project=/absolute/other/project' \
- --data-urlencode 'agent_name=BlueLake'
- curl --get http://localhost:7337/api/v1/reservations \
- --data-urlencode 'project=/absolute/other/project' \
- --data-urlencode 'agent_name=BlueLake'
- ```
- The override must name an existing absolute directory on the server host.
- It applies to that request's mail agents, messages, inbox, search, threads, and
- contacts, and to reservation creation, listing, lookup, conflict inspection,
- release, renewal, and force-release. Omit it to use the server's configured
- project. Each request keeps its chosen project throughout execution, including
- retries with an `Idempotency-Key`; selecting a project does not change the server
- configuration. Changing the default project separates subsequent retries from
- the previous project's cached results. Force-release approvals remain bound to
- the project and reservation the operator reviewed.
- Mail read and acknowledgement events, reservation events, and reservation
- approval-request events include `project_key` so subscribers can distinguish
- identically named agents and reservation IDs in different projects. The mail
- health endpoint checks the shared service and takes no project selector. Other
- API groups continue to use the configured server project.
- Important surfaces:
- - REST API under `/api/v1`
- - server-sent events at `/events`
- - WebSocket subscriptions at `/api/v1/ws`
- - health check at `/health`
- - generated OpenAPI spec at [`docs/openapi.json`](docs/openapi.json)
- Generate or refresh the OpenAPI document:
- ```bash
- ntm openapi generate
- ntm openapi generate --stdout
- ```
- ### Embedded Web Dashboard (`ntm web`)
- Launch the embedded Next.js operator dashboard together with the REST and WebSocket control plane:
- ```bash
- # Local loopback mode (binds 127.0.0.1:7337)
- ntm web
- # Remote / LAN deployment with API-key authentication
- ntm web --host 0.0.0.0 --port 7337 --auth-mode api_key --api-key "$NTM_API_KEY"
- # OIDC JWT authentication
- ntm web --host 0.0.0.0 --port 7337 --auth-mode oidc --oidc-issuer https://idp.example.com --oidc-audience ntm-web --oidc-jwks-url https://idp.example.com/.well-known/jwks.json
- # Mutual TLS (mTLS) client-certificate authentication
- ntm web --host 0.0.0.0 --port 7337 --auth-mode mtls --mtls-cert server.pem --mtls-key server-key.pem --mtls-ca ca.pem
- ```
- When `--auth-mode` is set to `api_key`, `oidc`, or `mtls`:
- - Static dashboard HTML/JS/CSS assets (`/`, `/connect`, `/_next/*`) load without credentials so the browser can render `/connect` and prompt for an API key or bearer token.
- - Every `/api/*`, `/ws/*`, and `/events` endpoint enforces authentication and RBAC.
- - Real-time WebSocket connections exchange the credential via `POST /api/v1/auth/ws-ticket` for a 30-second single-use upgrade ticket (`GET /api/v1/ws?ticket=...`) so bearer tokens and API keys never appear in URLs or request logs.
- ## Command Map
- | Command group | Commands | What it covers |
- | --- | --- | --- |
- | **Bootstrap & Setup** | `quick`, `init`, `setup`, `deps`, `doctor`, `shell`, `bind`, `completion`, `level`, `tutorial`, `version`, `upgrade` | Project initialization, environment diagnostics, shell/tmux integration, and CLI lifecycle |
- | **Session Lifecycle & Navigation** | `create`, `spawn`, `add`, `adopt`, `scale`, `respawn`, `list`, `sessions`, `status`, `attach`, `view`, `zoom`, `switch`, `overlay`, `dashboard`, `palette`, `kill`, `cleanup` | Creating, scaling, adopting, inspecting, focusing, and tearing down tmux agent sessions |
- | **Prompting & Operator Loop** | `send`, `preflight`, `replay`, `interrupt`, `wait`, `watch`, `codex`, `controller`, `rotate`, `quota` | Prompt validation/delivery, state waits, live pane control, controller agents, and seat/quota rotation |
- | **Output Inspection & Analytics** | `activity`, `attention`, `summary`, `health`, `logs`, `errors`, `extract`, `copy`, `save`, `get-all-session-text`, `diff`, `grep`, `analytics`, `metrics` | Pane output capture, operator attention state (`ack`/`snooze`/`pin`/`dismiss`), error/code extraction, cross-pane diffs, regex search, and telemetry |
- | **Work Triage & Swarm Orchestration** | `work`, `work-snapshot`, `beads`, `claim`, `assign`, `rebalance`, `review-queue`, `coordinator`, `swarm` | Graph-aware Beads prioritization, restart-safe snapshots, assignment, load balancing, and multi-project swarms |
- | **Agent Mail, Git & File Locks** | `mail`, `message`, `mapping`, `lock`, `locks`, `unlock`, `conflicts`, `git`, `repo`, `worktrees` | Agent Mail messaging, pane-to-agent identity mapping, advisory file reservations, and Git worktree isolation |
- | **Context, Memory & Search** | `context`, `cass`, `search`, `memory`, `handoff`, `resume` | Token-budgeted context packs, CASS cross-agent search, procedural memory (`cm`), and session handoffs |
- | **Safety, Policy & Redaction** | `safety`, `policy`, `approve`, `guards`, `hooks`, `scan`, `bugs`, `redact`, `scrub` | Destructive command protection, SLB approvals, pre-commit guards, UBS bug scanning, and secret redaction |
- | **Durable State & Forensics** | `checkpoint`, `rollback`, `timeline`, `history`, `audit`, `changes`, `support-bundle`, `webhook-outbox` | Session checkpoints/rollbacks, cryptographic audit trails, file attribution, support bundles, and webhook recovery |
- | **Ensembles, Pipelines & Templates** | `ensemble`, `modes`, `pipeline`, `workflows`, `recipes`, `template`, `session-templates`, `agents`, `personas`, `profiles`, `profile`, `models`, `plugins` | Multi-agent reasoning ensembles, DAG pipelines, reusable recipes/personas, local models, and plugins |
- | **Control Plane & Web Surfaces** | `serve`, `web`, `openapi`, `kernel`, `config`, `help` | HTTP/REST/SSE/WebSocket daemon, embedded Next.js dashboard, OpenAPI schema generation, kernel registry, and strict TOML config |
- `ntm --help` remains the canonical full command reference.
- ## Configuration and Project Assets
- NTM supports user-level and project-level assets.
- ### User-Level
- - main config: `~/.config/ntm/config.toml`
- - recipes: `~/.config/ntm/recipes.toml`
- - workflows: `~/.config/ntm/workflows/`
- - personas/profiles: `~/.config/ntm/personas.toml`
- - policy: `~/.ntm/policy.yaml`
- ### Project-Level
- Project-local assets live under `.ntm/` and override built-ins and user defaults where appropriate.
- - `.ntm/workflows/`
- - `.ntm/pipelines/`
- - `.ntm/personas.toml`
- - `.ntm/recipes.toml`
- - `.ntm/config.toml` for project-scoped settings such as additional assignment approval labels
- Checkpoints are per user, not per project: they live under
- `~/.local/share/ntm/checkpoints/<session>/`.
- Useful config commands:
- ```bash
- ntm config init
- ntm config show
- ntm config diff
- ntm config get projects_base
- ntm config edit
- ntm config reset
- ```
- Configuration loading is strict: unknown fields are errors. The unused TOML
- `[health]` section has been removed; migrate restart and monitoring settings to
- `[resilience]` (`auto_restart`, `max_restarts`, `restart_delay_seconds`,
- `health_check_seconds`, and `crash_threshold`). The `ntm health` command remains
- available and is unrelated to that removed config section.
- ### CAAM Seat Selection (opt-in, default off)
- If you run several interchangeable subscription seats through
- [CAAM](https://github.com/Dicklesworthstone/caam) — three Codex Pro logins, say
- — NTM can choose which one a new pane launches on instead of leaving that to
- whatever your agent command template pins:
- ```toml
- [integrations.caam]
- seat_selection = true
- ```
- With the key on, a `spawn`/`add` pane that carries **no** persona asks
- `caam limits <provider> --rank earliest-reset-headroom` and launches under the
- matching `codex-<profile>` / `claude-<profile>` persona. The rank spends the
- included allowance that refreshes **soonest while it still has headroom** and
- preserves the later-resetting reserve seat. (It is deliberately not
- `caam precheck --best`, which ranks lowest utilization and would pick the idle
- reserve — the opposite of the policy.)
- The semantics, exactly:
- - **A pin always wins.** `--persona=codex-acme`, `--profile-set`, and recipe
- personas are never re-ranked and never overridden. Only a pane with no
- persona at all is placed.
- - **One query per provider per command.** `ntm add --cod=4` shells out to caam
- once, not four times; the ranked seat is a property of the pool.
- - **Later `ntm add`s re-rank.** A pane added to a running swarm is a new pane
- and gets the seat that is right now, not the one that was right at spawn.
- (Answers are memoized for 20 seconds, so two adds in quick succession share
- one ranking — provider windows do not move on that timescale.) Credentials
- inside an already-running pane are never rotated.
- - **An unreadable pool skips those panes, loudly.** If caam is missing, times
- out, or ranks the pool and finds nothing with included headroom, no agent is
- launched into the affected panes and the reason is printed (and reported in
- `seat_skips` under `--json`). In `ntm add` the pane is never created at all;
- in `ntm spawn` the panes were already split before seats were resolved, so a
- refused one is left as a plain shell and named in the warning. Siblings on a
- provider that answered still come up: `ntm add --cod=2 --cc=2` with an
- exhausted Codex pool brings up the two Claude panes. A skipped pane never
- falls through to a static profile pin — that fallthrough is the failure this
- exists to prevent.
- - **`ntm scale` honors it too.** Scale-up reports the number of panes that
- actually launched, not the number requested, and surfaces each refusal.
- - **Only Claude and Codex are affected.** `caam limits` answers for no other
- provider, so gemini/grok/ollama/plugin panes are untouched.
- `seat_selection` is unrelated to `auto_failover` in the same table, despite
- sitting next to it: `auto_failover` swaps the **host** credential mid-session
- for a pane that hit a rate limit; `seat_selection` only chooses which account a
- **new** pane launches under. Enabling one does not enable the other, and
- `seat_selection` starts no caam subprocess when it is off.
- Requires caam >= v0.1.19 (the release that added the
- `earliest-reset-headroom` rank mode).
- ### Rano Network Activity
- [rano](https://github.com/Dicklesworthstone/rano)'s monitor records each agent
- process's connect/close events into an SQLite database. ntm reads that history
- (`rano export`) for `--robot-rano-stats`, the dashboard's Network Activity panel
- and the process-triage monitor's network signal; it never starts the monitor.
- Point ntm at the database the monitor writes (rano's default is
- `observer.sqlite` in the monitor's working directory):
- ```toml
- [integrations.rano]
- sqlite_path = "/path/to/observer.sqlite" # what you pass as `rano --sqlite`
- ```
- The counts are connections, not requests or bytes. With no database at that
- path, `--robot-rano-stats` fails with `DEPENDENCY_MISSING` and the panel shows
- why, instead of reporting zero traffic. Details: `docs/rano-stats.md`.
- ### Agent Plugins
- Custom agent types load from the `agents/` directory that sits next to the
- selected config file: `~/.config/ntm/agents/*.toml` by default,
- `$XDG_CONFIG_HOME/ntm/agents/` under an XDG override, or
- `<dir-of-config>/agents/` with an explicit `--config`. Each TOML declares a
- name/alias (which become `--<name>`/`--<alias>` spawn, `resume --spawn`, and `send` selectors), a
- command template, and optional `[agent.readiness]` regexes that drive
- idle/working/error classification for `status`, `activity`, `--robot-tail`,
- `--robot-activity`, `--robot-is-working`, `--robot-health`, and `--verify-boot`
- exactly like the built-in agents. NTM never modifies files in
- `agents/` — an existing preset you have customised is yours.
- Oh My Pi is now a built-in agent type (see [Oh My Pi](#oh-my-pi-omp)), so the
- former `examples/agents/omp.toml` plugin preset is no longer needed. A leftover
- `~/.config/ntm/agents/omp.toml` is harmless: built-in flags and the built-in
- omp detectors take precedence over a plugin of the same name.
- #### Pi coding agent (`pi`)
- Install the [pi preset](examples/agents/pi.toml) as `agents/pi.toml` beside
- your selected NTM configuration. Authenticate pi and configure its project
- trust before automated launches. The preset preserves pi's own defaults;
- model, thinking level, and persona system prompts are supplied when requested.
- ```bash
- ntm spawn swarm --pi=2
- ntm spawn swarm --pi=1:MODEL:high
- ntm --robot-spawn=automated --spawn-pi=2:MODEL:high --spawn-wait
- ntm send swarm --pi "Review the changes and run the tests"
- ntm sessions save swarm
- ntm sessions resume swarm --name recovered --native
- ntm resume next-session --from path/to/handoff --spawn --pi=2 --omp=1
- ```
- Pi has its own session provider and terminal parser. Its JSONL header supplies
- the session ID and working directory, including when a transcript was renamed.
- Discovery honors `--session-dir`, `PI_CODING_AGENT_SESSION_DIR`, and
- `PI_CODING_AGENT_DIR`, with `~/.pi/agent/sessions/<encoded-cwd>/` as the default.
- Files in a shared store are matched by their header's working directory;
- malformed headers and ambiguous ID prefixes are not promoted to exact bindings.
- Explicit `--session` and `--session-id` selectors are recognized during
- discovery. Saved-session resume resolves the exact saved ID to an existing
- transcript before launching `pi --session <path>`, retaining the original
- model, thinking, prompt, and environment settings. A missing or ambiguous
- transcript stops resume before an existing tmux session can be replaced.
- Saved sessions retain the exact discovered pi transcript path in their private
- save file, so resume still selects the original transcript when the caller's
- session directory, agent directory, or home environment changes. A missing or
- changed original transcript is an error even if another store contains the same
- session ID. This additional stored reference is omitted from public state
- fields; native resume commands still contain the selected transcript path.
- Managed `spawn` and `add` launches assign each fresh pi pane a distinct
- `--session-id` and record it with the launch command. Simultaneous panes in the
- same working directory can therefore be saved and resumed without guessing
- from transcript timestamps. Explicit pi session selectors remain authoritative.
- Workflow template profiles named `pi` also retain their plugin type and count.
- Robot spawning loads registered agents from the selected configuration and
- accepts the same count, model, and thinking-level grammar through
- `--spawn-<agent>` flags, including registered aliases. Recipes can mix pi with
- built-in agents and retain each instance's model and thinking level. Plugin
- readiness is shared by initial startup and pane restart, and the detached
- monitor retains the selected configuration. Plugin environment values travel
- through the private launch transport; saved launch metadata records their
- names rather than their values.
- For pipelines and workflows, pi's standard composer, unsent draft, cwd, and
- usage rows are excluded from response evidence. Blank redraws retain the last
- trusted boundary. A complete repaint can recover through a unique echo of the
- current delivered prompt; an idle pane alone cannot establish that a
- replacement screen answers the current turn. Unknown custom chrome, lost
- prompt boundaries, and unrelated replacement screens remain conservative
- refusals. Oh My Pi continues to use its separate `omp` session and terminal
- behavior.
- Response detection also accounts for pi rendering submitted Markdown. A
- waiting pipeline step requires a unique echo of its current delivered prompt
- and response text after that echo; workflow verdict matches must start after
- the echo without changing the original regular-expression anchors. Supported
- headings, emphasis, lists, and code retain their expected visible identity.
- Bare URLs, angle-delimited URLs and email addresses also work, as do Markdown
- links whose plain label exactly matches the destination. Named or formatted
- links remain unsupported when their visible text depends on terminal hyperlink
- support.
- Prompts with unsupported or terminal-dependent rendering are refused before
- automated response-waiting delivery; use plain text for those prompts. Explicit
- pipeline `wait: none` remains fire-and-forget. Operator acceptance of an
- uncertain pi delivery uses the same repaint checks, and normal resume collects
- the response without sending the prompt again. Old in-flight pi receipts that
- lack the rendered prompt identity require inspection and a deliberate restart.
- ## Design Principles
- ### No Silent Data Loss
- Stateful operations are designed to leave artifacts behind: checkpoints, timelines, audit
- records, pipeline state, and serialized robot/API responses.
- ### Graceful Degradation
- Optional integrations such as Agent Mail, `bv`, `cass`, or worktree helpers make NTM stronger,
- but the system is designed to remain locally useful without pretending missing tools are present.
- ### Idempotent Orchestration
- Robot mode, durable stores, and resumable workflows are designed so operators and agents can
- re-issue state queries and recover from interruptions without inventing undocumented side channels.
- ### Recoverable State
- Sessions, pipelines, attention feeds, approvals, and history all have explicit recovery paths.
- ### Auditable Actions
- NTM favors explicit logs, status surfaces, and durable state over invisible orchestration magic.
- ### Safe by Default
- Destructive operations, guard rails, and approval workflows are treated as core product behavior,
- not bolt-on scripts.
- ## Architecture
- ```text
- +---------------------------+
- | Human Operator / Agent |
- | CLI, TUI, Robot, REST |
- +-------------+-------------+
- |
- v
- +---------------------------+
- | NTM |
- |---------------------------|
- | session orchestration |
- | dashboard + palette |
- | work triage + assignment |
- | safety + policy + approve |
- | pipelines + checkpoints |
- | serve + robot surfaces |
- +------+------+-------------+
- | |
- | +--------------------------+
- | |
- v v
- +---------------------------+ +---------------------------+
- | Durable state + event bus | | Optional integrations |
- | checkpoints, history, | | br, bv, Agent Mail, cass, |
- | timelines, audit, alerts | | dcg, pt, worktrees |
- +-------------+-------------+ +---------------------------+
- |
- v
- +------------------------------+
- | tmux sessions and panes |
- | Claude / Codex / AGY / Grok |
- | labeled multi-agent work |
- +------------------------------+
- ```
- ## Installation
- ### Install Script
- ```bash
- curl -fsSL "https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh?$(date +%s)" | bash -s -- --easy-mode
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 1,891 on GitHub
- ```
- ### Homebrew
- ```bash
- brew install dicklesworthstone/tap/ntm
- ```
- ### Docker
- Multi-arch images (`linux/amd64`, `linux/arm64`) are published to GitHub
- Container Registry via DSR (`ghcr.io/dicklesworthstone/ntm`), tagged by semver
- (`1`, `1.38`, `1.38.0`) and commit SHA:
- ```bash
- docker pull ghcr.io/dicklesworthstone/ntm:1
- docker run --rm -it ghcr.io/dicklesworthstone/ntm:1
- ```
- Or build locally:
- ```bash
- docker build -t ntm .
- docker run --rm -it ntm
- ```
- ### From Source
- ```bash
- git clone https://github.com/Dicklesworthstone/ntm.git
- cd ntm
- go install ./cmd/ntm # or: make build
- ```
- ## Troubleshooting
- ### `tmux not found`
- Install `tmux` first, then re-run:
- ```bash
- ntm deps -v
- ```
- ### Agent panes start empty or an agent CLI fails immediately
- NTM can only launch tools that are installed and discoverable in `PATH`.
- Use `ntm deps -v` to check what it sees.
- ### `claude`, `codex`, `agy`, `grok`, or `gemini` not detected over SSH / tmux / non-login shells
- NTM discovers agent CLIs via the `PATH` of the **runtime environment it is launched in** —
- not the `PATH` of your interactive login shell. Tools installed under npm-global or
- `~/.local/bin` are often added to `PATH` by your `~/.bashrc` / `~/.zshrc` / `~/.profile`,
- which a non-interactive or non-login shell (a bare SSH command, a detached tmux server, a
- systemd unit, a CI runner) does not source. In that case `ntm deps -v` reports the agents as
- missing even though they work fine in your normal terminal.
- First, confirm what *NTM's* environment actually resolves, under the same shell/SSH/tmux
- context where you run NTM:
- ```bash
- command -v claude
- command -v codex
- command -v agy
- command -v grok
- command -v gemini
- ntm deps -v
- ```
- If those `command -v` checks come up empty here but succeed in your interactive shell, the
- fix is to put the missing directories on `PATH` before launching NTM. The most robust option
- is a small wrapper that exports the right `PATH` and then `exec`s NTM (paths vary by host):
- ```bash
- #!/usr/bin/env bash
- # ~/bin/ntm-wrapper — ensure agent CLIs are on PATH, then hand off to ntm.
- export PATH="$HOME/.npm-global/bin:$HOME/.local/bin:$PATH"
- exec ntm "$@"
- ```
- Make it executable (`chmod +x ~/bin/ntm-wrapper`) and invoke that instead of `ntm`. Re-run
- `ntm deps -v` through the wrapper to confirm all listed CLIs are now detected.
- ### A work command has nothing useful to say
- `ntm work ...` depends on running inside a repo with Beads/BV data available.
- If you are outside the project root, change directories or bootstrap the repo first.
- ### Mail, locks, or overseer commands say the server is unavailable
- Those surfaces depend on Agent Mail being configured and reachable. NTM will still work for
- session orchestration without it.
- ### Pipeline resume or cleanup does not see the state you expect
- Make sure the relevant session/project is using the intended project directory. Project-scoped
- state lives under that directory's `.ntm/` tree.
- ## FAQ
- ### Does NTM replace tmux?
- No. NTM is a structured orchestration layer on top of `tmux`.
- ### Can I use it with one agent instead of a swarm?
- Yes. It is perfectly fine to start with one Claude or Codex pane and only scale up when needed.
Lines 2,001–2,050 are not shown. The link to the file on GitHub has every line.
install.sh · Bundled script · 998 lines · 5 findings marked
- #!/usr/bin/env bash
- #
- # NTM Install Script
- # https://github.com/Dicklesworthstone/ntm
- #
- # Usage:
- # curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 7 on GitHub
- #
- # Options:
- # --version=TAG Install specific version (default: latest)
- # --dir=PATH Install to custom directory (default: /usr/local/bin or ~/.local/bin)
- # --no-shell Skip shell integration prompt
- # --easy-mode Non-interactive: auto-configure shell integration and PATH
- #
- # The script will:
- # 1. Detect your platform (OS and architecture)
- # 2. Download the pre-compiled binary from GitHub releases
- # 3. Install to a directory in your PATH
- # 4. Optionally set up shell integration
- set -euo pipefail
- REPO_OWNER="Dicklesworthstone"
- REPO_NAME="ntm"
- BIN_NAME="ntm"
- # Temp directory management
- TMP_DIRS=()
- cleanup_tmp_dirs() {
- local dir
- for dir in "${TMP_DIRS[@]:-}"; do
- # Use if statement to avoid set -e triggering on empty dir check
- if [ -n "$dir" ]; then
- rm -rf "$dir"
- fi
- done
- }
- trap cleanup_tmp_dirs EXIT
- # Defaults
- VERSION=""
- INSTALL_DIR=""
- NO_SHELL=false
- EASY_MODE=false
- # Parse arguments
- for arg in "$@"; do
- case $arg in
- --version=*)
- VERSION="${arg#*=}"
- ;;
- --dir=*)
- INSTALL_DIR="${arg#*=}"
- ;;
- --no-shell)
- NO_SHELL=true
- ;;
- --easy-mode)
- EASY_MODE=true
- ;;
- --help|-h)
- cat << 'EOF'
- NTM Install Script
- Usage: curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 67 on GitHub
- Options:
- --version=TAG Install specific version (default: latest)
- --dir=PATH Install to custom directory
- --no-shell Skip shell integration prompt
- --easy-mode Non-interactive: auto-configure shell integration and PATH
- --help Show this help
- Examples:
- # Install latest version
- curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh | bash
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 78 on GitHub
- # Install specific version
- curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh | bash -s -- --version=v1.0.0
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 81 on GitHub
- # Install to custom directory
- curl -fsSL https://raw.githubusercontent.com/Dicklesworthstone/ntm/main/install.sh | bash -s -- --dir=/opt/bin
- Note: Pipes a downloaded script directly into a shell (curl | sh / wget | bash)
- Line 84 on GitHub
- EOF
- exit 0
- ;;
- *)
- echo "Unknown option: $arg"
- exit 1
- ;;
- esac
- done
- # Output helpers
- print_info() { printf "\033[1;34m==>\033[0m %s\n" "$1"; }
- print_success() { printf "\033[1;32m==>\033[0m %s\n" "$1"; }
- print_error() { printf "\033[1;31mError:\033[0m %s\n" "$1" >&2; }
- print_warn() { printf "\033[1;33mWarning:\033[0m %s\n" "$1"; }
- # Detect OS and architecture
- detect_platform() {
- local os arch
- os="$(uname -s | tr '[:upper:]' '[:lower:]')"
- arch="$(uname -m)"
- case "$os" in
- linux) os="linux" ;;
- darwin) os="darwin" ;;
- mingw*|msys*|cygwin*) os="windows" ;;
- freebsd) os="freebsd" ;;
- *) print_error "Unsupported OS: $os"; return 1 ;;
- esac
- case "$arch" in
- x86_64|amd64) arch="amd64" ;;
- arm64|aarch64) arch="arm64" ;;
- armv7*|armhf) arch="armv7" ;;
- *) print_error "Unsupported architecture: $arch"; return 1 ;;
- esac
- echo "${os}_${arch}"
- }
- # Get the best install directory
- default_install_dir() {
- if [ -n "${INSTALL_DIR:-}" ]; then
- echo "$INSTALL_DIR"
- return
- fi
- # Prefer writable standard prefixes
- for dir in /usr/local/bin /opt/homebrew/bin /opt/local/bin; do
- if [ -d "$dir" ] && [ -w "$dir" ]; then
- echo "$dir"
- return
- fi
- done
- # Fall back to the first writable entry in PATH
- IFS=: read -r -a path_entries <<<"${PATH:-}"
- for dir in "${path_entries[@]}"; do
- if [ -d "$dir" ] && [ -w "$dir" ]; then
- echo "$dir"
- return
- fi
- done
- # Last resort: ~/.local/bin
- echo "${HOME}/.local/bin"
- }
- # Check if a command exists
- has_cmd() {
- command -v "$1" >/dev/null 2>&1
- }
- # Print the platform-appropriate tmux install command
- tmux_install_hint() {
- local os
- os="$(uname -s | tr '[:upper:]' '[:lower:]')"
- if [ "$os" = "darwin" ]; then
- echo "brew install tmux"
- return
- fi
- if has_cmd apt-get || has_cmd apt; then
- echo "sudo apt install tmux"
- elif has_cmd dnf; then
- echo "sudo dnf install tmux"
- elif has_cmd pacman; then
- echo "sudo pacman -S tmux"
- elif has_cmd brew; then
- echo "brew install tmux"
- else
- echo "install tmux with your system package manager"
- fi
- }
- # tmux is NTM's one hard runtime dependency. Check for it and print the exact
- # install command for this platform. Deliberately warn-and-continue: the
- # binary install itself does not need tmux, and package-manager side effects
- # are not an installer's call — so we do NOT auto-install.
- check_tmux() {
- if has_cmd tmux; then
- print_info "Found tmux: $(command -v tmux)"
- return 0
- fi
- print_warn "tmux not found — NTM requires tmux to run (it is the one hard dependency)."
- echo ""
- echo " Install it with:"
- echo " $(tmux_install_hint)"
- echo ""
- echo " Then re-run 'ntm doctor' to verify your setup."
- echo ""
- print_warn "Continuing the install; ntm will not work until tmux is installed."
- return 0
- }
- is_release_version() {
- local version="${1#v}"
- [[ "$version" =~ ^[0-9]+[.][0-9]+[.][0-9]+(-[0-9A-Za-z][0-9A-Za-z.-]*)?([+][0-9A-Za-z][0-9A-Za-z.-]*)?$ ]]
- }
- normalize_release_version() {
- local version="$1"
- if ! is_release_version "$version"; then
- print_error "Invalid version: $version (expected vX.Y.Z or X.Y.Z)"
- return 1
- fi
- printf 'v%s\n' "${version#v}"
- }
- # Download a file
- download_file() {
- local url="$1"
- local dest="$2"
- if has_cmd curl; then
- curl -fsSL "$url" -o "$dest" || return 1
- elif has_cmd wget; then
- wget -q "$url" -O "$dest" || return 1
- else
- print_error "Neither curl nor wget found. Please install one."
- return 1
- fi
- }
- # Probe-download a file that is allowed to be missing. Identical to
- # download_file except the transport tool's own stderr is suppressed, so an
- # expected 404 on one candidate does not print a scary error while a later
- # candidate goes on to succeed. Real failures are still reported via the
- # non-zero return code, which callers must handle.
- try_download_file() {
- local url="$1"
- local dest="$2"
- if has_cmd curl; then
- curl -fsSL "$url" -o "$dest" 2>/dev/null || return 1
- elif has_cmd wget; then
- wget -q "$url" -O "$dest" 2>/dev/null || return 1
- else
- print_error "Neither curl nor wget found. Please install one."
- return 1
- fi
- }
- # Get the latest release info from GitHub
- get_latest_release() {
- local url="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/latest"
- if has_cmd curl; then
- curl -fsSL "$url" 2>/dev/null || return 1
- elif has_cmd wget; then
- wget -qO- "$url" 2>/dev/null || return 1
- else
- return 1
- fi
- }
- resolve_latest_version_from_redirect() {
- local url="https://github.com/${REPO_OWNER}/${REPO_NAME}/releases/latest"
- local effective_url tag
- if has_cmd curl; then
- effective_url=$(curl -fsSL -o /dev/null -w '%{url_effective}' "$url" 2>/dev/null) || return 1
- elif has_cmd wget; then
- effective_url=$(
- wget -S --spider "$url" 2>&1 |
- awk 'tolower($1) == "location:" { loc = $2 } END { sub(/\r$/, "", loc); print loc }'
- ) || return 1
- [[ -n "$effective_url" ]] || return 1
- else
- return 1
- fi
- tag="${effective_url##*/}"
- if is_release_version "$tag"; then
- normalize_release_version "$tag"
- return 0
- fi
- return 1
- }
- # Get a specific tagged release info from GitHub
- get_release_by_tag() {
- local version="$1"
- local url="https://api.github.com/repos/${REPO_OWNER}/${REPO_NAME}/releases/tags/${version}"
- if has_cmd curl; then
- curl -fsSL "$url" 2>/dev/null || return 1
- elif has_cmd wget; then
- wget -qO- "$url" 2>/dev/null || return 1
- else
- return 1
- fi
- }
- # Extract version from release JSON
- extract_version() {
- # GitHub emits one release object with a unique, unescaped top-level
- # tag_name. Track strings and nesting so compact JSON, nested metadata,
- # and quoted release prose cannot change which field supplies the tag.
- # This is a bounded field scanner, not a general JSON decoder: escapes
- # are retained, and normalize_release_version still validates the result.
- # Drain the input after finding the tag to avoid SIGPIPE under pipefail.
- LC_ALL=C awk '
- found || finished || invalid { next }
- {
- for (i = 1; i <= length($0); i++) {
- ch = substr($0, i, 1)
- if (quoted) {
- if (escaped) {
- if (collect) token = token "\\" ch
- escaped = 0
- } else if (ch == "\\") {
- escaped = 1
- } else if (ch == "\"") {
- quoted = 0
- if (depth == 1 && state == "key") {
- key = token
- state = "colon"
- } else if (depth == 1 && state == "value") {
- if (key == "tag_name") {
- version = token
- found = 1
- next
- }
- state = "done"
- }
- } else if (collect) {
- token = token ch
- }
- continue
- }
- if (ch ~ /^[[:space:]]$/) {
- continue
- }
- if (!started) {
- if (ch != "{") {
- invalid = 1
- next
- }
- started = 1
- depth = 1
- state = "key"
- } else if (ch == "\"") {
- quoted = 1
- token = ""
- collect = depth == 1 && (state == "key" || (state == "value" && key == "tag_name"))
- } else if (ch == "{" || ch == "[") {
- depth++
- } else if (ch == "}" || ch == "]") {
- depth--
- if (depth == 0) {
- finished = 1
- next
- }
- } else if (depth == 1 && ch == ":" && state == "colon") {
- state = "value"
- } else if (depth == 1 && ch == ",") {
- state = "key"
- } else if (depth == 1 && state == "value") {
- state = "done"
- }
- }
- # JSON strings cannot contain literal newlines.
- if (quoted) {
- invalid = 1
- }
- }
- END { if (found && !invalid) print version }
- '
- }
- # Find the best asset name for a platform from release JSON
- find_asset_name() {
- local platform="$1"
- local release_json="$2"
- local asset_name
- if [[ "$platform" == windows_* ]]; then
- asset_name=$(printf '%s\n' "$release_json" | grep -o "\"name\":[[:space:]]*\"${BIN_NAME}_${platform}\\.zip\"" | \
- sed -E 's/.*"name":[[:space:]]*"([^"]+)".*/\1/' | head -1 || true)
- if [ -n "$asset_name" ]; then
- printf '%s\n' "$asset_name"
- return 0
- fi
- fi
- asset_name=$(printf '%s\n' "$release_json" | grep -o "\"name\":[[:space:]]*\"${BIN_NAME}_[^\"]*_${platform}\\.tar\\.gz\"" | \
- sed -E 's/.*"name":[[:space:]]*"([^"]+)".*/\1/' | head -1 || true)
- if [ -n "$asset_name" ]; then
- printf '%s\n' "$asset_name"
- return 0
- fi
- asset_name=$(printf '%s\n' "$release_json" | grep -o "\"name\":[[:space:]]*\"${BIN_NAME}_${platform}\\.tar\\.gz\"" | \
- sed -E 's/.*"name":[[:space:]]*"([^"]+)".*/\1/' | head -1 || true)
- if [ -n "$asset_name" ]; then
- printf '%s\n' "$asset_name"
- return 0
- fi
- asset_name=$(printf '%s\n' "$release_json" | grep -o "\"name\":[[:space:]]*\"${BIN_NAME}_[^\"]*_${platform}\\.zip\"" | \
- sed -E 's/.*"name":[[:space:]]*"([^"]+)".*/\1/' | head -1 || true)
- if [ -n "$asset_name" ]; then
- printf '%s\n' "$asset_name"
- return 0
- fi
- asset_name=$(printf '%s\n' "$release_json" | grep -o "\"name\":[[:space:]]*\"${BIN_NAME}_${platform}\\.zip\"" | \
- sed -E 's/.*"name":[[:space:]]*"([^"]+)".*/\1/' | head -1 || true)
- if [ -n "$asset_name" ]; then
- printf '%s\n' "$asset_name"
- return 0
- fi
- asset_name=$(printf '%s\n' "$release_json" | grep -o "\"name\":[[:space:]]*\"${BIN_NAME}_${platform}\"" | \
- sed -E 's/.*"name":[[:space:]]*"([^"]+)".*/\1/' | head -1 || true)
- printf '%s\n' "$asset_name"
- }
- build_download_url() {
- local version="$1"
- local asset_name="$2"
- printf 'https://github.com/%s/%s/releases/download/%s/%s\n' "$REPO_OWNER" "$REPO_NAME" "$version" "$asset_name"
- }
- download_release_checksums() {
- local version="$1"
- local asset_name="$2"
- local dest_dir="$3"
- local candidate checksum_url checksum_path
- # SHA256SUMS is what current releases actually publish, so probe it first;
- # the other names are legacy/per-asset fallbacks that usually 404.
- local -a candidates=(
- "SHA256SUMS"
- "checksums.txt"
- "${asset_name}.sha256"
- )
- # Only transport failures fall through to the next release asset. Once a
- # checksum document downloads, verification treats it as authoritative and
- # fails closed rather than accepting a different checksum source.
- for candidate in "${candidates[@]}"; do
- checksum_url=$(build_download_url "$version" "$candidate")
- checksum_path="${dest_dir}/${candidate}"
- if try_download_file "$checksum_url" "$checksum_path"; then
- printf '%s\n' "$checksum_path"
- return 0
- fi
- done
- return 1
- }
- verify_downloaded_asset() {
- local asset_path="$1"
- local checksum_path="$2"
- local asset_name="$3"
- local expected actual
- if [ ! -f "$checksum_path" ]; then
- print_error "Checksums file not found: $checksum_path"
- return 1
- fi
- expected=$(
- awk -v name="$asset_name" '
- {
- filename = $NF
- sub(/\r$/, "", filename)
- if (filename == name) {
- print $1
- exit
- }
- }
- ' "$checksum_path"
- )
- if ! printf '%s\n' "$expected" | grep -Eq '^[0-9A-Fa-f]{64}$'; then
- print_error "No SHA256 checksum found for $asset_name"
- return 1
- fi
- if has_cmd sha256sum; then
- actual=$(sha256sum "$asset_path" | awk '{print $1}')
- elif has_cmd shasum; then
- actual=$(shasum -a 256 "$asset_path" | awk '{print $1}')
- else
- print_error "Need sha256sum or shasum to verify downloaded asset"
- return 1
- fi
- expected=$(printf '%s' "$expected" | tr '[:upper:]' '[:lower:]')
- actual=$(printf '%s' "$actual" | tr '[:upper:]' '[:lower:]')
- if [ "$expected" != "$actual" ]; then
- print_error "Checksum mismatch for $asset_name"
- return 1
- fi
- }
- asset_url_exists() {
- local url="$1"
- if has_cmd curl; then
- curl -fsIL -o /dev/null "$url" 2>/dev/null
- return $?
- elif has_cmd wget; then
- wget -q --spider "$url" 2>/dev/null
- return $?
- fi
- return 1
- }
- find_downloadable_asset_name() {
- local platform="$1"
- local version="$2"
- local clean_version="${version#v}"
- local alt_platform="${platform//_/-}"
- local candidate url
- local -a candidates=(
- "${BIN_NAME}_${clean_version}_${platform}.tar.gz"
- "${BIN_NAME}_${version}_${platform}.tar.gz"
- "${BIN_NAME}_${platform}.tar.gz"
- "${BIN_NAME}-${clean_version}-${alt_platform}.tar.gz"
- "${BIN_NAME}_${clean_version}_${platform}.zip"
- "${BIN_NAME}_${version}_${platform}.zip"
- "${BIN_NAME}_${platform}.zip"
- )
- for candidate in "${candidates[@]}"; do
- url=$(build_download_url "$version" "$candidate")
- if asset_url_exists "$url"; then
- printf '%s\n' "$candidate"
- return 0
- fi
- done
- return 1
- }
- extract_downloaded_asset() {
- local asset_name="$1"
- local downloaded_path="$2"
- local tmp_dir="$3"
- case "$asset_name" in
- *.tar.gz)
- tar -xzf "$downloaded_path" -C "$tmp_dir"
- ;;
- *.zip)
- if has_cmd unzip; then
- unzip -q "$downloaded_path" -d "$tmp_dir"
- elif has_cmd bsdtar; then
- bsdtar -xf "$downloaded_path" -C "$tmp_dir"
- else
- print_error "Need unzip or bsdtar to extract $asset_name"
- return 1
- fi
- ;;
- *)
- return 0
- ;;
- esac
- return 0
- }
- # Ensure install directory exists
- ensure_install_dir() {
- local dir="$1"
- if [ -d "$dir" ]; then
- return 0
- fi
- if mkdir -p "$dir" 2>/dev/null; then
- return 0
- fi
- print_info "Creating $dir requires sudo..."
- sudo mkdir -p "$dir"
- }
- # Easy-mode PATH setup: append the install dir to existing shell rc files.
- # When NO writable rc file exists this must never silently no-op — it prints
- # the exact export line the user has to add by hand.
- easy_mode_path_setup() {
- local install_dir="$1"
- local path_updated=0
- local rc
- for rc in "$HOME/.zshrc" "$HOME/.bashrc"; do
- if [ -e "$rc" ] && [ -w "$rc" ]; then
- if ! grep -F "$install_dir" "$rc" >/dev/null 2>&1; then
- {
- echo ""
- echo "# Added by ntm installer"
- echo "export PATH=\"\$PATH:${install_dir}\""
- } >> "$rc"
- path_updated=1
- fi
- fi
- done
- if [ "$path_updated" -eq 1 ]; then
- print_info "PATH updated in shell rc files; restart shell to use ntm"
- elif ! grep -F "$install_dir" "$HOME/.zshrc" >/dev/null 2>&1 \
- && ! grep -F "$install_dir" "$HOME/.bashrc" >/dev/null 2>&1; then
- print_warn "Could not update PATH automatically: no writable ~/.zshrc or ~/.bashrc found."
- echo ""
- echo " ${install_dir} is not in your PATH."
- echo " Add this line to your shell rc file (create it if needed):"
- echo " export PATH=\"\$PATH:${install_dir}\""
- echo ""
- fi
- }
- # Main installation function
- install_ntm() {
- local platform version install_dir tmp_dir asset_name download_url download_path binary_path checksum_path
- print_info "Installing ${BIN_NAME}..."
- # Detect platform
- platform=$(detect_platform) || exit 1
- print_info "Detected platform: $platform"
- # Check the one hard runtime dependency up front (warn-and-continue)
- check_tmux
- # Determine install directory
- install_dir=$(default_install_dir)
- print_info "Install directory: $install_dir"
- # Get version
- if [ -z "$VERSION" ]; then
- print_info "Fetching latest version..."
- local release_json
- version=$(resolve_latest_version_from_redirect || true)
- if [ -n "$version" ]; then
- release_json=""
- else
- release_json=$(get_latest_release) || {
- print_error "Could not fetch release info from GitHub"
- exit 1
- }
- version=$(printf '%s\n' "$release_json" | extract_version)
- fi
- if [ -z "$version" ]; then
- print_error "Could not determine latest version"
- exit 1
- fi
- else
- version="$VERSION"
- fi
- if ! version=$(normalize_release_version "$version"); then
- exit 1
- fi
- if [ -n "$VERSION" ]; then
- # Fetch release info for this version
- local release_json
- release_json=$(get_release_by_tag "$version" || true)
- if [ -z "$release_json" ]; then
- print_warn "Could not fetch release info for ${version} from GitHub; trying known asset names"
- fi
- fi
- print_info "Installing ${BIN_NAME} ${version} for ${platform}"
- # Fetch release info if we don't have it. If the API is rate-limited, fall
- # back to probing the deterministic release asset names below.
- if [ -z "${release_json:-}" ]; then
- release_json=$(get_release_by_tag "$version" || true)
- fi
- # Find download asset
- asset_name=$(find_asset_name "$platform" "$release_json")
- if [ -z "$asset_name" ]; then
- # Try alternate naming conventions
- # Some releases use dashes instead of underscores
- local alt_platform="${platform//_/-}"
- asset_name=$(find_asset_name "$alt_platform" "$release_json")
- fi
- if [ -z "$asset_name" ]; then
- # macOS uses universal binary (darwin_all) instead of arch-specific
- case "$platform" in
- darwin_amd64|darwin_arm64)
- asset_name=$(find_asset_name "darwin_all" "$release_json")
- if [ -z "$asset_name" ]; then
- asset_name=$(find_downloadable_asset_name "darwin_all" "$version" || true)
- fi
- ;;
- esac
- fi
- if [ -z "$asset_name" ]; then
- asset_name=$(find_downloadable_asset_name "$platform" "$version" || true)
- fi
- if [ -z "$asset_name" ]; then
- print_error "No pre-built binary found for $platform"
- print_info "You can build this version from source with: git clone --branch ${version} --depth 1 https://github.com/${REPO_OWNER}/${REPO_NAME}.git && cd ${REPO_NAME} && go install ./cmd/${BIN_NAME}"
- exit 1
- fi
- download_url=$(build_download_url "$version" "$asset_name")
- print_info "Downloading from $download_url..."
- # Create temp directory
- tmp_dir=$(mktemp -d)
- TMP_DIRS+=("$tmp_dir")
- download_path="${tmp_dir}/${asset_name}"
- binary_path="${tmp_dir}/${BIN_NAME}"
- # Download
- if ! download_file "$download_url" "$download_path"; then
- print_error "Download failed"
- exit 1
- fi
- print_info "Verifying checksum..."
- if ! checksum_path=$(download_release_checksums "$version" "$asset_name" "$tmp_dir"); then
- print_error "Could not download release checksums"
- exit 1
- fi
- if ! verify_downloaded_asset "$download_path" "$checksum_path" "$asset_name"; then
- exit 1
- fi
- if ! extract_downloaded_asset "$asset_name" "$download_path" "$tmp_dir"; then
- print_error "Could not extract downloaded archive"
- exit 1
- fi
- if [ ! -f "$binary_path" ] && [ -f "${tmp_dir}/${BIN_NAME}.exe" ]; then
- binary_path="${tmp_dir}/${BIN_NAME}.exe"
- fi
- if [ ! -f "$binary_path" ]; then
- print_error "Could not find ${BIN_NAME} in downloaded asset"
- exit 1
- fi
- # Make executable
- chmod +x "$binary_path"
- # Verify it runs
- if ! "$binary_path" version >/dev/null 2>&1; then
- print_error "Downloaded binary failed verification"
- exit 1
- fi
- # Install
- ensure_install_dir "$install_dir"
- local dest_path="${install_dir}/${BIN_NAME}"
- if [ -w "$install_dir" ]; then
- mv "$binary_path" "$dest_path"
- else
- print_info "Installing to $install_dir requires sudo..."
- sudo mv "$binary_path" "$dest_path"
- fi
- print_success "Installed ${BIN_NAME} ${version} to ${dest_path}"
- # Check PATH
- if ! echo "$PATH" | grep -q "$install_dir"; then
- if [ "$EASY_MODE" = true ]; then
- easy_mode_path_setup "$install_dir"
- else
- print_warn "${install_dir} is not in your PATH"
- echo ""
- echo "Add to your shell rc file:"
- echo " export PATH=\"\$PATH:${install_dir}\""
- echo ""
- fi
- fi
- # Shell integration
- if [ "$NO_SHELL" != true ]; then
- setup_shell_integration
- fi
- echo ""
- print_success "Installation complete!"
- echo ""
- echo "Quick start:"
- echo " ntm spawn myproject --cc=2 --cod=2 # Create session with agents"
- echo " ntm attach myproject # Attach to session"
- echo " ntm palette # Open command palette"
- echo " ntm tutorial # Interactive tutorial"
- echo ""
- echo "Tip: You can also install via Homebrew:"
- echo " brew install dicklesworthstone/tap/ntm"
- echo ""
- echo "Run 'ntm --help' for full documentation."
- }
- # Get the shell integration command for the installed version
- # v1.5.0 and earlier use "ntm init <shell>", v1.6.0+ use "ntm shell <shell>"
- get_shell_cmd() {
- local shell_name="$1"
- local installed_version="$2"
- # Determine which command to use based on version
- # v1.5.0 and earlier use "ntm init", v1.6.0+ use "ntm shell"
- local use_init=false
- if [ -n "$installed_version" ]; then
- # Strip 'v' prefix for comparison
- local ver="${installed_version#v}"
- local major minor
- major=$(echo "$ver" | cut -d. -f1)
- minor=$(echo "$ver" | cut -d. -f2)
- # Use "ntm init" for v1.5.x and earlier
- if [ "$major" -eq 1 ] && [ "$minor" -le 5 ] 2>/dev/null; then
- use_init=true
- fi
- fi
- local cmd_name="shell"
- if [ "$use_init" = true ]; then
- cmd_name="init"
- fi
- case "$shell_name" in
- fish)
- echo "ntm $cmd_name fish | source"
- ;;
- *)
- echo "eval \"\$(ntm $cmd_name $shell_name)\""
- ;;
- esac
- }
- # Update legacy "ntm init" entries to "ntm shell" in a shell rc file
- upgrade_shell_integration() {
- local rc_file="$1"
- if [ ! -f "$rc_file" ]; then
- return 1
- fi
- # Check if the file has legacy "ntm init" entries
- if ! grep -q 'ntm init' "$rc_file"; then
- return 1
- fi
- # Create a backup
- local backup_file="${rc_file}.ntm-backup"
- cp "$rc_file" "$backup_file"
- # Replace "ntm init" with "ntm shell" in the file
- # Handle both eval "$(ntm init bash)" and ntm init fish | source patterns
- if sed -i.bak 's/ntm init/ntm shell/g' "$rc_file" 2>/dev/null; then
- rm -f "${rc_file}.bak"
- print_success "Updated shell integration in ${rc_file}"
- print_info "Backup saved to ${backup_file}"
- return 0
- else
- # macOS sed requires different syntax
- if sed -i '' 's/ntm init/ntm shell/g' "$rc_file" 2>/dev/null; then
- print_success "Updated shell integration in ${rc_file}"
- print_info "Backup saved to ${backup_file}"
- return 0
- fi
- fi
- # Restore from backup if sed failed
- mv "$backup_file" "$rc_file"
- return 1
- }
- # Setup shell integration
- setup_shell_integration() {
- local shell_name rc_file init_cmd
- # Detect shell
- shell_name=$(basename "${SHELL:-bash}")
- case "$shell_name" in
- zsh)
- rc_file="${HOME}/.zshrc"
- ;;
- bash)
- rc_file="${HOME}/.bashrc"
- ;;
- fish)
- rc_file="${HOME}/.config/fish/config.fish"
- ;;
- *)
- return
- ;;
- esac
- # Get the appropriate shell command for the installed version
- init_cmd=$(get_shell_cmd "$shell_name" "$VERSION")
- # Check if already configured with current "ntm shell" command
- if [ -f "$rc_file" ] && grep -q "ntm shell" "$rc_file"; then
- print_info "Shell integration already configured in ${rc_file}"
- return
- fi
- # Check for legacy "ntm init" entries that need upgrading
- if [ -f "$rc_file" ] && grep -q "ntm init" "$rc_file"; then
- print_warn "Legacy shell integration detected in ${rc_file}"
- print_info "The 'ntm init' command was renamed to 'ntm shell' in v1.6.0."
- # In easy-mode, auto-upgrade
- if [ "$EASY_MODE" = true ]; then
- if upgrade_shell_integration "$rc_file"; then
- print_info "Restart your shell or run 'source ${rc_file}' to activate."
- else
- print_warn "Could not auto-update. Please manually replace 'ntm init' with 'ntm shell'."
- fi
- return
- fi
- # Only prompt if interactive
- if [ -t 0 ] && [ -t 1 ]; then
- printf "Update to 'ntm shell' automatically? [Y/n]: "
- read -r answer
- case "$answer" in
- n|N|no|NO)
- print_info "Please manually replace 'ntm init' with 'ntm shell' in ${rc_file}"
- ;;
- *)
- if upgrade_shell_integration "$rc_file"; then
- print_info "Restart your shell or run 'source ${rc_file}' to activate."
- else
- print_warn "Could not auto-update. Please manually replace 'ntm init' with 'ntm shell'."
- fi
- ;;
- esac
- else
- print_info "Run installer with --easy-mode to auto-update, or manually replace 'ntm init' with 'ntm shell'."
- fi
- return
- fi
- echo ""
- echo "Shell Integration"
- echo ""
- echo "Add this to ${rc_file}:"
- echo " ${init_cmd}"
- echo ""
- # In easy-mode, auto-add without prompting
- if [ "$EASY_MODE" = true ]; then
- {
- echo ""
- echo "# NTM - Named Tmux Manager"
- echo "$init_cmd"
- } >> "$rc_file"
- print_success "Added shell integration to ${rc_file}"
- print_info "Restart your shell or run 'source ${rc_file}' to activate."
- return
- fi
- # Only prompt if interactive
- if [ -t 0 ] && [ -t 1 ]; then
- printf "Add it now? [y/N]: "
- read -r answer
- case "$answer" in
- y|Y|yes|YES)
- echo "" >> "$rc_file"
- echo "# NTM - Named Tmux Manager" >> "$rc_file"
- echo "$init_cmd" >> "$rc_file"
- print_success "Added to ${rc_file}"
- echo ""
- echo "Run 'source ${rc_file}' or restart your shell to activate."
- ;;
- *)
- echo "Skipped. Add it manually when ready."
- ;;
- esac
- fi
- }
- # Run installation (skipped when sourced under NTM_INSTALL_SH_NO_MAIN=1,
- # which the shell-function test harness uses to exercise the guidance paths)
- if [ "${NTM_INSTALL_SH_NO_MAIN:-0}" != "1" ]; then
- install_ntm
- fi
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.