Prerequisites

• macOS, Linux, or Windows 11
• One supported runtime to run the launcher: node, bun, or deno. The Windows installer can bootstrap Node.js automatically if none is already available.
• One configured model provider (API Key or local Ollama)
• Go 1.26+ (Required only for Source Build)

Installation

Downloads prebuilt binaries automatically. Current releases ship a launcher shim, a portable nami.js bundle, and the Go engine binary.

Manual Installation

sudo install -m 755 nami /usr/local/bin/nami
sudo install -m 755 nami.js /usr/local/bin/nami.js
sudo install -m 755 nami-engine /usr/local/bin/nami-engine

mkdir -p "$HOME/.local/bin"
install -m 755 nami "$HOME/.local/bin/nami"
install -m 755 nami.js "$HOME/.local/bin/nami.js"
install -m 755 nami-engine "$HOME/.local/bin/nami-engine"

Setup [BYOK]

GitHub Copilot

First-Class Outputs

Artifacts in Nami are durable, structured outputs that stay reviewable in the main TUI instead of disappearing into the transcript.

• Implementation Plans: Proposals before execution.
• Task Lists: Real-time progress trackers.
• Walkthroughs: Post-completion summaries.
• Durable Returns: Large fetch/diff results.

Agent Swarms

Nami can run project-local agent swarms for planning, implementation, and review inside one repo. There is no separate launcher. Add a swarm file to your project, start Nami in that repo, and delegate child agents with a role. This workflow is also based on ideas from Uncle Bob's SwarmForge.

1. Add a Swarm File

Create .nami/swarm.json in your repository. This is the file Nami uses to understand which roles your swarm should have.

{
  "version": 1,
  "roles": [
    {
      "name": "architect",
      "purpose": "Plan the work",
      "subagent_type": "Explore",
      "model": "github-copilot/gpt-5.4",
      "workspace": "shared",
      "queue_policy": "fifo",
      "permission_profile": "read-only",
      "allow_tools": [
        "think",
        "read_file",
        "file_search",
        "grep_search",
        "swarm_submit_handoff",
        "swarm_list_inbox"
      ],
      "deny_tools": [],
      "handoff": {
        "required": false,
        "targets": ["coder"],
        "required_fields": ["summary", "verification"]
      },
      "metadata": {
        "owner": "planning"
      }
    },
    {
      "name": "coder",
      "purpose": "Implement the changes",
      "subagent_type": "general-purpose",
      "workspace": "worktree",
      "queue_policy": "latest-wins",
      "permission_profile": "write",
      "handoff": {
        "required": true,
        "targets": ["reviewer"],
        "required_fields": [
          "summary",
          "changed_files",
          "verification",
          "next_action"
        ]
      }
    },
    {
      "name": "reviewer",
      "purpose": "Review the result",
      "subagent_type": "verification",
      "workspace": "shared",
      "queue_policy": "batch-review",
      "permission_profile": "execute"
    }
  ]
}

• version: optional. Omit it or set it to 1.
• roles: required array with at least one role.
• name: required. Lowercase letters, numbers, _, and - are supported.
• purpose: required short description of what the role is for.
• subagent_type: optional. Supported values are Explore, general-purpose, and verification. Default: Explore.
• model: optional. Set a specific model such as github-copilot/gpt-5.4 or openai/gpt-4o.
• workspace: optional. Supported values are shared, worktree, and snapshot. Default: shared.
• queue_policy: optional. Supported values are fifo, batch-review, and latest-wins. Default: fifo.
• permission_profile: optional. Supported values are inherit, read-only, execute, and write. Default: inherit.
• allow_tools / deny_tools: optional. Use tool names to narrow what a role may use.
• handoff.required: optional boolean. Set to true if the role must submit a structured handoff before it can finish.
• handoff.targets: optional array of role names this role may hand work to.
• handoff.required_fields: optional array using summary, changed_files, commands_run, verification, risks, and next_action. If handoff is required and you omit this list, Nami defaults to summary and verification.
• metadata.owner: optional freeform label for your own organization.

If you want extra guidance for the whole swarm or for specific roles, add markdown files under .nami/swarm/, for example .nami/swarm/constitution.md or .nami/swarm/roles/coder.md.

2. Start Nami in the Project

Open Nami from the repository root. If the swarm file is valid, Nami loads it automatically and shows a Swarm Spec artifact. If there is a problem, check that artifact first.

3. Delegate Work by Role

Swarm mode becomes useful when you launch child agents with a role. Use whatever role names you defined in .nami/swarm.json.

4. Pass Work with Handoffs

In normal swarm use, the role-aware child agent submits the handoff for you when one role finishes work for another. You only need to call the handoff tools yourself if you want to steer the workflow manually. In practice, that usually means asking Nami in plain language rather than typing a raw tool payload yourself. For a manual overview of queued swarm work, open /tasks.

5. Check the Inbox

When you want to see what is waiting for a role, use swarm_list_inbox. If you want the next piece of work for a role, use it with dequeue: true. This is also the mechanism a receiving agent can use to pull its next queued handoff.

• List work: see everything waiting for a role
• Pull next work: ask for the next handoff with dequeue: true

6. Watch the Dashboard

Open the background tasks dialog with /tasks to see active roles, recent handoffs, and running background work in one place.

Tips

• Start simple with three roles: architect, coder, and reviewer.
• If a role is not behaving as expected, check the Swarm Spec artifact first.
• Use handoffs to move work forward instead of relying on long freeform summaries.
• Use the dashboard when you have multiple background roles active at once.

CLI Options

MCP Management

Nami includes a small MCP management CLI for adding, inspecting, listing, and removing configured MCP servers without editing JSON by hand.

• Supported transports: stdio, http, sse, and ws
• Stdio flags: --env KEY=value and --startup-timeout-ms
• Network flags: --header 'Key: Value' for http, sse, and ws
• Runtime checks: list and get attempt a real MCP connection, so repo-scoped stdio servers are briefly spawned to inspect health and capabilities

Slash Commands

Permissions

Use the --auto-mode flag at startup to automatically enable "Allow Safe" for the entire session.

Destructive commands (rm -rf, push --force) always require 'y' approval.

Tools Reference

Child Agent Modes

The agent tool exposes three bounded modes. Explore is the default read-only search agent, general-purpose handles broader delegated work, and verification validates builds and tests without file edits.

Edit Tool Selection

• • replace_string_in_file: One exact snippet replacement in one existing file.
• • multi_replace_string_in_file: Several exact replacements grouped into one call when you already know the target strings.
• • apply_patch: Structural, multi-hunk, create/delete, or multi-file edits.
• • file_write: Full overwrite of one existing file.
• • create_file: Create one brand-new file.

Configuration Reference

File: ~/.config/nami/config.json

{
  "model": "anthropic/claude-sonnet-4-20250514",
  "mcp": {
    "servers": {
      "chrome-devtools": {
        "transport": "stdio",
        "command": "npx",
        "args": ["-y", "chrome-devtools-mcp@latest"],
        "enabled": true,
        "trust": false
      }
    }
  }
}

{
  "servers": {
    "chrome-devtools": {
      "transport": "stdio",
      "command": "npx",
      "args": ["-y", "chrome-devtools-mcp@latest"],
      "enabled": true,
      "trust": false
    }
  }
}

{
  "servers": {
    "chrome-devtools": {
      "transport": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "chrome-devtools-mcp@latest",
        "--no-usage-statistics"
      ],
      "env": {
        "CHROME_DEVTOOLS_MCP_NO_UPDATE_CHECKS": "1"
      },
      "enabled": true,
      "trust": false
    }
  }
}

Skills

Skills are task-specific instruction bundles that Nami can inject automatically when they match the current request. They are not always-on policy files. Use skills for reusable workflows, domain-specific guidance, and lightweight task playbooks that should only appear when relevant.

• • Nami loads built-in skills first, then user-global skills, then project-local skills.
• • If two skills share the same name, the later source wins, so project-local skills can override a global one.
• • Nami auto-selects up to three relevant skills for a turn based on the user prompt.
• • Skills are markdown files with optional frontmatter such as name, description, keywords, allowed-tools, and argument-hint.

---
name: go-review
description: Review Go changes for correctness, error handling, and package boundaries
keywords: go, golang, review, refactor
allowed-tools: read_file, grep_search, go_definition
argument-hint: repo path or changed files
---

Focus on obvious code, explicit error handling, and small package responsibilities.

AGENTS.md

AGENTS.md is Nami's project-instructions file. It is loaded automatically and treated as always-on guidance for the current workspace. Use it for coding standards, repository workflow rules, architecture constraints, and other durable team instructions that should apply across tasks.

• • Nami walks upward from the current working directory and loads AGENTS.md files it finds along the path.
• • Files closer to the current directory have higher priority and are loaded later.
• • These project instructions override default behavior when applicable.
• • Use AGENTS.md for broad workspace policy. Use skills for task-specific workflows that should only be injected when relevant.

## Go Coding Philosophy

- Write obvious code, not clever code.
- Always check errors explicitly.
- Keep packages focused and composable.

## Workflow Rules

- Run formatting after each completed task.
- Build before proposing a commit.
- Prefer repo-local conventions over generic defaults.

Diagnostics

Nami now supports both startup debug capture and live session capture. The canonical log format is structured JSONL so you can tail it directly or pipe it into external monitoring tools.

NAMI_DEBUG=1 nami

/debug
/debug status
/debug path
/debug off

nami debug-view --file ~/.config/nami/sessions/<session-id>/debug.log
tail -F ~/.config/nami/sessions/<session-id>/debug.log | jq .

• • On macOS, /debug opens a new Terminal window with the live monitor attached to the current session log.
• • Each line in debug.log is a structured event envelope with fields like schema_version, ts, session_id, component, event, level, metrics, data, and error.
• • Sensitive raw payloads are redacted and truncated before they are written to the log.

Architecture

Nami uses a split-process architecture. A Silvery-powered terminal UI communicates with a Go engine over NDJSON. Every turn, the engine assembles context from four cooperating layers: live retrieval, durable preference memory, session memory, and compaction. Retrieval stays repo-first — no cached code summaries.

See the implementation write-up in docs/lean-retrieval-architecture.md for the retrieval layer, session graph, session-memory/compaction interplay, invalidation rules, and telemetry details behind this diagram.

This diagram is intentionally retrieval-scoped. It shows how Nami selects fresh repo context per turn. Continuity under context pressure is handled by separate layers: session memory preserves structured working state, and compaction trims or summarizes older transcript state without replacing live retrieval.

Building from Source

bun run setup       # Build TS & compile Go
bun run start       # Run dev Silvery TUI
make release-local  # Package launcher shim + nami.js + engine
make install        # Install to /usr/local/bin