### Install NTM from Source

Source: https://github.com/dicklesworthstone/ntm/blob/main/README.md

Installs NTM by cloning the repository and using `go install`.

```bash
git clone https://github.com/Dicklesworthstone/ntm.git
cd ntm
go install ./cmd/ntm
```

--------------------------------

### Install VHS on Linux

Source: https://github.com/dicklesworthstone/ntm/blob/main/testdata/vhs/README.md

Install VHS on Linux using Go.

```bash
# Linux (via Go)
go install github.com/charmbracelet/vhs@latest
```

--------------------------------

### System Endpoint: Capabilities

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /capabilities endpoint to list available features and tools.

```plaintext
GET /capabilities
```

--------------------------------

### Environment Variable Key Detection Examples

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/REDACTION_SPEC.md

Examples demonstrating how different formats of API keys are detected in environment variables.

```bash
# Key in environment export (should detect)
export OPENAI_API_KEY=<<OPENAI_LEGACY_KEY>>
```

```bash
# Multiple keys in one line (should detect all)
OPENAI_KEY=<<OPENAI_LEGACY_KEY>> ANTHROPIC_KEY=<<ANTHROPIC_KEY>>
```

```bash
# Key with surrounding whitespace (should detect)
   <<OPENAI_LEGACY_KEY>>
```

```bash
# Key in code-like text (should detect)
export API_KEY=<<OPENAI_LEGACY_KEY>>
```

--------------------------------

### Start daemon

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Starts the beads daemon.

```APIDOC
## POST /beads/daemon/start

### Description
Start daemon

### Method
POST

### Endpoint
/api/v1/beads/daemon/start
```

--------------------------------

### Generated Zsh Shell Integration Script

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_MAKE_NTM.md

Example output of 'ntm init zsh', including agent aliases, NTM subcommand aliases, and completion setup.

```zsh
# Generated by ntm init zsh

# Agent aliases (customizable via config)
alias cc='NODE_OPTIONS="--max-old-space-size=32768" claude --dangerously-skip-permissions'
alias cod='codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.1-codex-max'
alias gmi='gemini --yolo'

# Short aliases for ntm subcommands
alias cnt='ntm create'
alias sat='ntm spawn'
alias rnt='ntm attach'
alias lnt='ntm list'
alias bp='ntm send'
alias knt='ntm kill'

# Completions
_ntm_completions() {
    local completions
    completions=(${(f)"$(ntm completion zsh --complete "$words")"})
    _describe 'command' completions
}
compdef _ntm_completions ntm

# F6 binding for palette (if in tmux)
if [[ -n "$TMUX" ]]; then
    bindkey -s '^[[17~' 'ntm palette\n'
fi
```

--------------------------------

### Start Session Macro for Agent Bootstrap

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_IMPROVE_NTM_PROJECT.md

Initiates a new agent session, registering the agent, reserving files, and setting up an inbox. Use this when starting a new agent from scratch.

```go
// internal/agentmail/macros.go - NEW FILE

type MacroStartSessionOptions struct {
    HumanKey              string   `json:"human_key"`
    Program               string   `json:"program"`
    Model                 string   `json:"model"`
    AgentName             string   `json:"agent_name,omitempty"` // Auto-generated if empty
    TaskDescription       string   `json:"task_description"`
    FileReservationPaths  []string `json:"file_reservation_paths,omitempty"`
    FileReservationTTL    int      `json:"file_reservation_ttl_seconds"`
    FileReservationReason string   `json:"file_reservation_reason"`
    InboxLimit            int      `json:"inbox_limit"`
}

type MacroStartSessionResult struct {
    Project      ProjectInfo      `json:"project"`
    Agent        AgentInfo        `json:"agent"`
    Reservations ReservationInfo  `json:"file_reservations"`
    Inbox        []InboxMessage   `json:"inbox"`
}

// StartSession uses the macro_start_session MCP tool
func (c *Client) StartSession(ctx context.Context, opts MacroStartSessionOptions) (*MacroStartSessionResult, error) {
    args := map[string]interface{}{
        "human_key":                  opts.HumanKey,
        "program":                    opts.Program,
        "model":                      opts.Model,
        "task_description":           opts.TaskDescription,
        "inbox_limit":                opts.InboxLimit,
    }

    if opts.AgentName != "" {
        args["agent_name"] = opts.AgentName
    }

    if len(opts.FileReservationPaths) > 0 {
        args["file_reservation_paths"] = opts.FileReservationPaths
        args["file_reservation_ttl_seconds"] = opts.FileReservationTTL
        args["file_reservation_reason"] = opts.FileReservationReason
    }

    result, err := c.callToolWithTimeout(ctx, "macro_start_session", args, LongTimeout)
    if err != nil {
        return nil, fmt.Errorf("macro_start_session failed: %w", err)
    }

    var startResult MacroStartSessionResult
    if err := json.Unmarshal(result, &startResult); err != nil {
        return nil, err
    }
    return &startResult, nil
}
```

--------------------------------

### Install VHS on Arch Linux

Source: https://github.com/dicklesworthstone/ntm/blob/main/testdata/vhs/README.md

Install VHS on Arch Linux using yay.

```bash
# Arch Linux
yay -S vhs
```

--------------------------------

### System Endpoint: Version Info

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /version endpoint to retrieve version information.

```plaintext
GET /version
```

--------------------------------

### Install NTM and Check Dependencies

Source: https://github.com/dicklesworthstone/ntm/blob/main/SKILL.md

Installs NTM using a curl script and checks its dependencies. The `--easy-mode` flag is used for a simplified installation.

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

--------------------------------

### NTM Installation Instructions

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_MAKE_NTM.md

Provides commands for installing NTM on macOS using Homebrew, Debian/Ubuntu Linux via a script, or from source using Cargo.

```shell
# macOS
brew install dicklesworthstone/tap/ntm

# Linux (Debian/Ubuntu)
curl -fsSL https://ntm.dev/install.sh | bash

# Or with cargo (if Rust)
cargo install ntm

# Then add to .zshrc:
echo 'eval "$(ntm init zsh)"' >> ~/.zshrc
```

--------------------------------

### Idempotency Key Format Examples

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-request-identity.md

Provides examples of the recommended format for idempotency keys, including scope, user ID, and specific task identifiers.

```text
idem_<scope>_<user_id>

Examples:
  idem_session_abc123
  idem_persistent_task456_v2
  idem_workflow_bd-xyz_step3
```

--------------------------------

### CLI Audit Query Examples

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-auditability.md

Command-line interface examples for querying the audit trail. Demonstrates querying by target, actor, and event type with specified time ranges.

```bash
# Query audit trail for target
ntm audit --robot --target alert:agent_stuck:pane-abc123 --last 24h

# Query by actor
ntm audit --robot --actor PeachPond --last 24h

# Query by event type
ntm audit --robot --type incident_opened --last 7d
```

--------------------------------

### Action Targeting Examples

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-resource-references.md

JSON examples for sending an action with a target and the corresponding action response, including status and result.

```json
// Send action request
{
  "action": "send",
  "target": "agent:ntm/myproject/0.2",
  "payload": {
    "msg": "Start work on bd-abc123"
  }
}

// Action response
{
  "action_ref": "action:ntm/act-send-20260322-xyz",
  "target": "agent:ntm/myproject/0.2",
  "status": "completed",
  "result": { "sent": true }
}
```

--------------------------------

### Core Robot Actions Examples

Source: https://github.com/dicklesworthstone/ntm/blob/main/references/ROBOT-MODE.md

Provides examples of core robot actions, including sending messages, acknowledging tasks, tailing logs, interrupting processes, and inspecting panes.

```bash
ntm --robot-send=myproject --msg="Fix auth" --type=claude
ntm --robot-ack=myproject --ack-timeout=30s
ntm --robot-tail=myproject --lines=50
ntm --robot-interrupt=myproject
ntm --robot-inspect-pane=myproject --inspect-index=2
```

--------------------------------

### Create Session Response Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__CLAUDE_WEB.md

Example JSON response after successfully creating an NTM session. Details include session name, creation timestamp, agent status, and working directory.

```json
{
  "data": {
    "name": "feature-auth",
    "created_at": "2026-01-07T12:00:00Z",
    "agents": [
      {"index": 0, "type": "claude", "state": "waiting"},
      {"index": 1, "type": "codex", "state": "waiting"}
    ],
    "working_dir": "/home/user/project"
  }
}
```

--------------------------------

### Install and Manage Pre-Commit Guards with Go

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_IMPROVE_NTM_PROJECT.md

Go functions to install and uninstall Agent Mail pre-commit hooks in a repository. Includes an auto-install function for session spawns that finds and installs guards in all Git repositories within a project.

```go
package agentmail

import (
	"context"
	"log"
	"os"
	"path/filepath"
)

// InstallPrecommitGuard installs the Agent Mail pre-commit hook in a repository
func InstallPrecommitGuard(ctx context.Context, projectPath, repoPath string) error {
    return InstallPrecommitGuard(ctx, projectPath, repoPath)
}

// UninstallPrecommitGuard removes the pre-commit hook
func UninstallPrecommitGuard(ctx context.Context, repoPath string) error {
    return UninstallPrecommitGuard(ctx, repoPath)
}

// AutoInstallGuards installs guards during session spawn
func AutoInstallGuards(ctx context.Context, session string) error {
    projectPath, _ := os.Getwd()

    // Find all git repos in project
    repos := findGitRepos(projectPath)

    for _, repo := range repos {
        if err := InstallPrecommitGuard(ctx, projectPath, repo); err != nil {
            log.Printf("Warning: Failed to install guard in %s: %v", repo, err)
        } else {
            log.Printf("Installed pre-commit guard in %s", repo)
        }
    }

    return nil
}

// Helper function to find git repositories (implementation not shown)
func findGitRepos(projectPath string) []string {
    var repos []string
    filepath.Walk(projectPath, func(path string, info os.FileInfo, err error) error {
        if err != nil {
            return err
        }
        if info.IsDir() && info.Name() == ".git" {
            // Add the parent directory of .git as a repository path
            repos = append(repos, filepath.Dir(path))
        }
        return nil
    })
    return repos
}
```

--------------------------------

### Policy Metadata Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-sensitivity-redaction.md

Provides an example of policy metadata, including version, source, update timestamp, and counts of rules and custom rules. It also shows an empty list for overrides.

```json
{
  "policy": {
    "version": "v2.1",
    "source": "builtin",
    "updated_at": "2026-03-01T00:00:00Z",
    "rules_count": 45,
    "custom_rules_count": 0,
    "overrides": []
  }
}
```

--------------------------------

### Create Session Request Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__CLAUDE_WEB.md

Example HTTP request to create a new NTM session. Includes session name, agents, working directory, and configuration options.

```http
POST /api/v1/sessions
Content-Type: application/json
Authorization: Bearer <token>

{
  "name": "feature-auth",
  "agents": ["cc", "cod"],
  "working_dir": "/home/user/project",
  "config": {
    "auto_compact": true,
    "checkpoint_interval": "5m"
  }
}
```

--------------------------------

### Install NTM with Easy Mode

Source: https://github.com/dicklesworthstone/ntm/blob/main/README.md

Installs NTM using a curl script with the --easy-mode flag. The date is appended to the URL to ensure the latest version is fetched.

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

--------------------------------

### Target Agent Setup: Single macro_start_session Call

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_IMPROVE_NTM_PROJECT.md

Demonstrates the improved agent setup using the Agent Mail 'macro_start_session' macro. This single call handles project setup, agent registration, file reservations, and inbox fetching, significantly improving efficiency and reducing errors. Includes options for task description, file reservations with TTL, and inbox limits.

```go
// NEW: Single call does everything
result, err := macroStartSession(ctx, MacroStartSessionOptions{
    HumanKey:              projectKey,  // Absolute path to project
    Program:               "claude-code",
    Model:                 "opus-4.5",
    TaskDescription:       "Implementing auth module",
    FileReservationPaths:  []string{"internal/auth/**/*.go"},
    FileReservationTTL:    3600,  // 1 hour
    InboxLimit:            10,
})
// Returns: project + agent + reservations + inbox in one response
```

--------------------------------

### Sessions Endpoint: Get Session Details

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to retrieve details for a specific session by its name.

```plaintext
GET /sessions/{name}
```

--------------------------------

### Panes Endpoint: Get Pane Details

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to retrieve details for a specific pane within a session.

```plaintext
GET /sessions/{name}/panes/{idx}
```

--------------------------------

### Quick Start Project Creation and Swarm Launch

Source: https://github.com/dicklesworthstone/ntm/blob/main/SKILL.md

Creates a new project using a Go template and launches a mixed swarm of agents. This is a foundational step for using NTM.

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

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

--------------------------------

### REST API Audit Query Examples

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-auditability.md

HTTP GET requests for querying the audit trail via the REST API. Shows examples for filtering by target and by actor/event type.

```http
GET /api/robot/audit?target=alert:agent_stuck:pane-abc123&last=24h HTTP/1.1

GET /api/robot/audit?actor=PeachPond&type=acknowledge HTTP/1.1
```

--------------------------------

### NTM API Example (Run Workflow)

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/ORCHESTRATION_FEATURES.md

Shows how to initiate a workflow run using the NTM CLI, specifying the workflow file and runtime variables.

```bash
# Run workflow
ntm pipeline run workflow.yaml --var feature_name="user auth"

```

--------------------------------

### Panes Endpoint: Tail Pane Output

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to tail the output of a specific pane.

```plaintext
GET /sessions/{name}/panes/{idx}/output
```

--------------------------------

### Sessions Endpoint: List All Sessions

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /sessions endpoint to list all available sessions.

```plaintext
GET /sessions
```

--------------------------------

### NTM API Example (List Pipelines)

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/ORCHESTRATION_FEATURES.md

Provides the command to list all available pipelines within the NTM system.

```bash
# List pipelines
ntm pipeline list

```

--------------------------------

### System Endpoint: Effective Configuration

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /config endpoint to retrieve the effective configuration.

```plaintext
GET /config
```

--------------------------------

### System Endpoint: Dependencies Status

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /deps endpoint to check the status of dependencies.

```plaintext
GET /deps
```

--------------------------------

### Current Agent Setup: Multiple API Calls

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_IMPROVE_NTM_PROJECT.md

Illustrates the current NTM process which requires multiple, separate API calls to register an agent and set up its environment. This approach is error-prone and less efficient.

```go
// CURRENT: Multiple error-prone calls
err := ensureProject(ctx, projectKey)
if err != nil { return err }

agent, err := registerAgent(ctx, projectKey, program, model)
if err != nil { return err }

reservations, err := reservePaths(ctx, projectKey, agent.Name, paths)
if err != nil { return err }

inbox, err := fetchInbox(ctx, projectKey, agent.Name)
if err != nil { return err }
```

--------------------------------

### Build and Test Go Project

Source: https://github.com/dicklesworthstone/ntm/blob/main/AGENTS.md

Commands to build the Go binary, run unit tests, and check formatting. Ensure these are run after substantive code changes.

```bash
# Build the binary
go build ./cmd/ntm

# Run tests (fast, skips E2E)
go test -short ./...

# Run linter (if available)
golangci-lint run

# Verify formatting
gofmt -l .
goimports -l .
```

--------------------------------

### System Endpoint: Health Check

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /health endpoint for system health checks.

```plaintext
GET /health
```

--------------------------------

### NTM Command-Line Interface Examples

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_IMPROVE_NTM_PROJECT.md

Provides examples of common NTM commands for spawning agents, managing projects, and configuring the system. Use these commands to interact with the NTM CLI for various development and coordination tasks.

```bash
# Spawn with macro (default)
ntm spawn myproject --cc=2 --reserve="internal/**/*.go"

# Spawn to continue existing thread
ntm spawn myproject --cc=1 --thread=FEAT-123

# Cross-project agent coordination
ntm contact myproject/GreenLake other-project/BlueDog --reason="Need review help"

# Project onboarding & diagnostics
ntm init                 # Sets up .ntm/, policy defaults, wrappers, optional hooks
ntm doctor               # Validates tools, versions, daemons, capabilities, tmux health

# Local API server for dashboard + robot endpoints
ntm serve --port 7337    # Starts HTTP server with WebSocket event streaming

# Config profiles
ntm config show
ntm config set scheduler.preferCriticalPath=true
ntm config set safety.autoInstallWrappers=true

```

--------------------------------

### Panes Endpoint: Capture Pane

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to capture the current state or content of a specific pane.

```plaintext
GET /sessions/{name}/panes/{idx}/capture
```

--------------------------------

### Panes Endpoint: List Panes in Session

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to list all panes within a specific session.

```plaintext
GET /sessions/{name}/panes
```

--------------------------------

### Scaffold a New Project Directory

Source: https://github.com/dicklesworthstone/ntm/blob/main/README.md

Creates a new project directory with a Go API template. This is a setup step before launching agents.

```bash
ntm quick api --template=go
```

--------------------------------

### Bubble Tea Initial Model Setup

Source: https://github.com/dicklesworthstone/ntm/blob/main/third_party/bubbletea/README.md

Initialize the model with a predefined list of choices and an empty map for selected items.

```go
func initialModel() model {
	return model{
		// Our to-do list is a grocery list
		choices:  []string{"Buy carrots", "Buy celery", "Buy kohlrabi"},

		// A map which indicates which choices are selected. We're using
		// the  map like a mathematical set. The keys refer to the indexes
		// of the `choices` slice, above.
		selected: make(map[int]struct{}),
	}
}
```

--------------------------------

### System Endpoint: Doctor Tool Health Check

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /doctor endpoint for a tool health check.

```plaintext
GET /doctor
```

--------------------------------

### Example NTM TOML Configuration File

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_MAKE_NTM.md

Illustrates the structure and content of a typical NTM configuration file.

```toml
# ~/.config/ntm/config.toml

projects_base = "~/Developer"

[agents]
claude = "NODE_OPTIONS='--max-old-space-size=32768' claude --dangerously-skip-permissions"
codex = "codex --dangerously-bypass-approvals-and-sandbox -m gpt-5.1-codex-max"
gemini = "gemini --yolo"

[[palette]]
key = "fresh_review"
label = "Fresh Eyes Review"
prompt = """
Carefully reread the latest code changes and fix any obvious bugs.
"""

[[palette]]
key = "git_commit"
label = "Commit Changes"  
prompt = "Commit all changed files with detailed messages and push."
```

--------------------------------

### Drill-Down Chain Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-explainability-evidence.md

Demonstrates a multi-level drill-down chain for explaining complex issues, starting from a high-level snapshot to root cause diagnosis.

```json
// Level 1: snapshot
{
  "alerts": { "total_active": 3, "has_critical": true },
  "_explain": {
    "short": "3 active alerts (1 critical)",
    "drill_down": {
      "label": "Alert list",
      "command": "ntm --robot-alerts",
      "depth": "status"
    }
  }
}

// Level 2: alerts (status)
{
  "alerts": [
    {
      "id": "alert-xyz",
      "severity": "critical",
      "message": "Agent crashed",
      "_explain": {
        "short": "Process exited 5m ago",
        "drill_down": {
          "label": "Full diagnostics",
          "command": "ntm --robot-diagnose=myproject --panes=2",
          "depth": "diagnose"
        }
      }
    }
  ]
}

// Level 3: diagnose
{
  "diagnosis": {
    "root_cause": "OOM killer terminated process",
    "evidence": {
      "exit_code": 137,
      "dmesg_lines": ["oom-killer: ..."],
      "memory_peak_mb": 8192
    },
    "_explain": {
      "type": "diagnosis",
      "short": "OOM kill detected",
      "code": "EXPLAIN_DIAGNOSIS_OOM",
      "drill_down": {
        "label": "View system logs",
        "command": "journalctl -u ntm --since='5 minutes ago'"
      }
    }
  }
}
```

--------------------------------

### Sessions Endpoint: Full State Capture

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /sessions/{name}/snapshot endpoint for a full state capture of a session.

```plaintext
GET /sessions/{name}/snapshot
```

--------------------------------

### Labeling Projects

Source: https://github.com/dicklesworthstone/ntm/blob/main/references/CONFIG.md

Demonstrates how labels extend session names and provides examples of using labels with ntm commands for project management.

```text
project--frontend
project--backend
```

```bash
ntm quick myproject --label frontend
ntm spawn myproject --label frontend --cc=2
ntm add myproject --label frontend --cc=1
```

--------------------------------

### Build NTM

Source: https://github.com/dicklesworthstone/ntm/blob/main/CONTRIBUTING.md

Build the NTM executable. Ensure you have Go 1.25+ installed.

```bash
go build ./cmd/ntm
```

--------------------------------

### Sessions Endpoint: Watch Mode (WebSocket)

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__OPUS.md

Example of a GET request to the /sessions/{name}/watch endpoint to enable watch mode, typically used with WebSockets.

```plaintext
GET /sessions/{name}/watch
```

--------------------------------

### Spawn Session API Response

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/planning/PLAN_TO_ADD_WEB_UI_AND_REST_AND_WEBSOCKET_API_LAYERS_TO_NTM__GPT_PRO.md

Example JSON response for a successful session spawn request, indicating operation ID, status, session name, and start time.

```json
{
  "operation_id": "op_01H...",
  "status": "running",
  "session": "myproject",
  "started_at": "2026-01-07T00:00:00Z"
}
```

--------------------------------

### Loop Constructs Example (For-Each and While)

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/ORCHESTRATION_FEATURES.md

Illustrates iteration over collections using 'for-each' loops and conditional loops with 'while'. Provides access to loop variables like item, index, and count.

```yaml
# For-each loop
- id: process_files
  loop:
    items: ${vars.files}
    as: file
  steps:
    - id: process
      prompt: Process ${loop.file}

# Access loop variables: ${loop.file}, ${loop.index}, ${loop.count}

# While loop
- id: poll
  loop:
    while: ${vars.status} != "ready"
    max_iterations: 10
    delay: 30s
  steps:
    - id: check
      prompt: Check status
      output_var: status

```

--------------------------------

### List and Show NTM Assets

Source: https://github.com/dicklesworthstone/ntm/blob/main/SKILL.md

Lists and shows available recipes, workflows, and templates within NTM for reusable configurations.

```bash
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
```

--------------------------------

### Get Routing Recommendation API Response

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/ORCHESTRATION_FEATURES.md

Example JSON response for a routing recommendation request. It includes the recommended agent, its score, the strategy used, and details of all candidate agents.

```json
{
  "success": true,
  "recommendation": {
    "pane": "myproject__cc_2",
    "pane_idx": 2,
    "agent_type": "claude",
    "score": 77,
    "reason": "highest_score_available"
  },
  "strategy": "least-loaded",
  "candidates": [
    {"pane": "myproject__cc_1", "score": 26, "context_pct": 72, "state": "GENERATING"},
    {"pane": "myproject__cc_2", "score": 77, "context_pct": 28, "state": "WAITING"},
    {"pane": "myproject__cc_3", "score": 67, "context_pct": 45, "state": "WAITING"}
  ]
}
```

--------------------------------

### CLI Watch Subscription Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-watch-subscription.md

This bash command starts a 'ntm watch' with filters for 'event_class=attention' and 'severity>=warning'. The output format is JSON lines, showing control and attention events.

```bash
# Start watch with subscription
ntm watch --robot --filter "event_class=attention" --filter "severity>=warning"
```

```json
# Output format (JSON lines)
{"event_class":"control","event_type":"control:connected",...}
{"event_class":"control","event_type":"control:replay_start",...}
{"event_class":"attention","event_type":"attention:alert:agent_stuck",...}
{"event_class":"control","event_type":"control:replay_end",...}
{"event_class":"control","event_type":"control:heartbeat",...}
```

--------------------------------

### Source Health and Degraded Data Error Response

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-action-errors.md

An example of a response indicating source health issues, including degraded data availability. It suggests an action to install missing components.

```json
{
  "success": true,
  "source_health": {
    "beads": { "available": false, "reason": "bv not installed" },
    "mail": { "available": true, "degraded": true, "reason": "server slow" }
  },
  "_degraded": true,
  "_degraded_sources": ["beads", "mail"],
  "next_actions": [
    {
      "id": "install_bv",
      "category": "escalate",
      "label": "Install bv for bead support",
      "priority": 1
    }
  ]
}
```

--------------------------------

### Go Migration Function Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/sqlite-runtime-tables.md

Provides a Go function signature for performing database migrations. This function handles creating the migrations table, getting the current version, applying pending migrations, and recording applied migrations.

```go
func Migrate(db *sql.DB) error {
    // 1. Create migrations table if not exists
    // 2. Get current version
    // 3. Apply pending migrations in order
    // 4. Record each applied migration
}
```

--------------------------------

### Parallel Steps Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/ORCHESTRATION_FEATURES.md

Demonstrates running multiple steps concurrently using the 'parallel' keyword. Each sub-step can be assigned to a different agent.

```yaml
- id: research_phase
  parallel:
    - id: market_research
      agent: claude
      prompt: Research market trends
    - id: tech_research
      agent: codex
      prompt: Research technical options
    - id: competitor_analysis
      agent: gemini
      prompt: Analyze competitors
  # All three run simultaneously, next step waits for all

- id: synthesis
  depends_on: [research_phase]
  prompt: |
    Synthesize findings:
    ${steps.market_research.output}
    ${steps.tech_research.output}
    ${steps.competitor_analysis.output}

```

--------------------------------

### Focused Step Design Example

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/WORKFLOW_EXAMPLES.md

Illustrates good practice by separating distinct tasks into individual steps, promoting clarity and maintainability.

```yaml
# Good: Single responsibility
- id: fetch_data
  prompt: Fetch user data from the API

- id: transform_data
  prompt: Transform the user data into report format

# Avoid: Multiple concerns in one step
- id: fetch_and_transform
  prompt: Fetch user data and transform it into a report

```

--------------------------------

### Run Live Bottleneck Profiler Dashboard (Short Gate)

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/verification-matrix-swarm-scale-vnext.md

Tests the live bottleneck profiler, focusing on hotspot grouping, sort determinism, and trends. Use the '-short' flag.

```bash
go test -short ./internal/profiler/...
```

--------------------------------

### Install ImageMagick on Ubuntu/Debian

Source: https://github.com/dicklesworthstone/ntm/blob/main/testdata/vhs/README.md

Install ImageMagick on Ubuntu/Debian for screenshot comparison.

```bash
# Ubuntu/Debian
sudo apt install imagemagick
```

--------------------------------

### Offset-Based Pagination Commands

Source: https://github.com/dicklesworthstone/ntm/blob/main/docs/robot-ordering-pagination.md

Shows command-line examples for fetching paginated results using offset-based pagination. Each command specifies a limit and an offset to retrieve subsequent pages of data.

```bash
# First page
ntm --robot-status --limit=20

# Second page
ntm --robot-status --limit=20 --offset=20

# Third page
ntm --robot-status --limit=20 --offset=40
```

--------------------------------

### Install VHS on macOS

Source: https://github.com/dicklesworthstone/ntm/blob/main/testdata/vhs/README.md

Use Homebrew to install VHS on macOS.

```bash
# macOS
brew install charmbracelet/tap/vhs
```

--------------------------------

### Install NTM with Homebrew

Source: https://github.com/dicklesworthstone/ntm/blob/main/README.md

Installs NTM using the Homebrew package manager.

```bash
brew install dicklesworthstone/tap/ntm
```

--------------------------------

### Build and Test NTM Project

Source: https://github.com/dicklesworthstone/ntm/blob/main/README.md

Builds the NTM executable and runs unit tests. Ensure Go is installed and the project is cloned locally.

```bash
go build ./cmd/ntm
go test -short ./...
golangci-lint run
```

--------------------------------

### Install ImageMagick on macOS

Source: https://github.com/dicklesworthstone/ntm/blob/main/testdata/vhs/README.md

Install ImageMagick on macOS using Homebrew for screenshot comparison.

```bash
# macOS
brew install imagemagick
```