Quickstart

Install with pipx (isolated, recommended) or with pip. Nauro requires Python 3.10+.

• The package is nauro. It lives in the public monorepo Nauro-AI/nauro under packages/nauro and is Apache 2.0 licensed.
• After install, the nauro binary exposes the CLI. The MCP server is the same binary invoked as nauro serve --stdio. That is exactly the command setup writes into your MCP client config: {"command": "nauro", "args": ["serve", "--stdio"]}.

Whether nauro is immediately on your PATH after a pipx install depends on your environment; if the command is not found, you may need to run pipx ensurepath and restart your shell.

pipx install nauro   # or: pip install nauro

No account, no MCP wiring, no agent restart. The whole demo runs against a local store from your shell.

• nauro init --demo creates a sample project (the default name is demo-project) and writes its store plus a .nauro/config.json into the current directory. Re-running reuses the existing demo entry rather than duplicating it.
• The --demo flag means “Create a sample project with pre-written decisions.” It seeds decisions directly to disk, with no network. Combining --demo with --cloud is rejected at command entry, because the demo fixture seeds locally only.
• The fixture is a fictional “TaskFlow” task-management API. --demo seeds project.md, state_current.md, stack.md, open-questions.md, 7 pre-written decisions under decisions/, and one snapshot at snapshots/v001.json.
• The init output reports it literally: “Includes: 7 decisions, project state, open questions, and a snapshot” and “Wrote .nauro/config.json into <cwd>”. Its closing line is “Next: run 'nauro check-decision "<approach>"' to try a conflict check”.

mkdir -p /tmp/nauro-demo && cd /tmp/nauro-demo
nauro init --demo
nauro check-decision "Add a WebSocket endpoint for live task updates"

nauro check-decision "<approach>" runs deterministic BM25 retrieval over the store and prints a JSON envelope with the keys store, related_decisions (each entry carries id, title, score, status, date, and a rationale preview), a deterministic assessment string, and a project identifier (id and name).

It does not judge the conflict. The tool description states verbatim “This tool does NOT judge conflicts.” It surfaces the related decision so you (or your agent) can reason about it.

For the WebSocket query, the surfaced decision is decision #4 “SSE over WebSocket for live task updates” in the demo fixture (status active, dated 2026-03-15).

Per its rationale, TaskFlow chose Server-Sent Events because during ECS rolling deploys WebSocket connections were not released cleanly: new tasks routed to draining containers, causing 30-second stalls until timeout, while SSE clients reconnect to healthy targets within 3 seconds.

WebSocket was rejected because persistent connections were not released during rolling deploys (connection storms as containers drained), it required custom connection-tracking middleware to debug, and its bidirectional channel is unnecessary since clients never push through the stream.

{
  "store": "local",
  "related_decisions": [
    {
      "id": "decision-004",
      "title": "SSE over WebSocket for live task updates",
      "score": 5.0,
      "status": "active",
      "date": "2026-03-15",
      "rationale_preview": "Server-Sent Events (SSE) for pushing live task updates..."
    }
  ],
  "assessment": "Found 5 related decisions. Top match: D004 \"SSE over WebSocket for live task updates\"...",
  "project": { "id": "01K...", "name": "demo-project" }
}

The envelope above is illustrative; the exact score and the related-decision count you see when you run it locally are not pinned in source, so treat the numbers as a representative sample rather than a fixed contract.

Guard: do not run nauro setup (MCP wiring) from the throwaway demo directory. Doing so would wire the demo into your real MCP client.

The demo warns against running nauro setup from /tmp/nauro-demo. If the demo cwd happens to be a git repo, init --demo warns that the demo config will steer that repo's resolution to the demo doctrine.

nauro adopt bootstraps a project from an existing repo in one shot. Run it from the repo root, or pass --repo <path>.

It must run inside a git repository. Adopt runs git rev-parse --show-toplevel and otherwise refuses: “Error: nauro adopt must be run inside a git repository. Run `git init` first, or pass --repo <path> to point at one.”

In order, adopt:

1. Resolves the repo root.
2. Refuses if the repo is already adopted (an existing .nauro/config.json).
3. Runs a same-name collision pre-check against the local registry.
4. Mints a project, writes .nauro/config.json, and scaffolds the store.
5. Wires MCP and materializes skills across Claude Code, Cursor, and Codex.
6. Smoke-tests the wired binary by briefly booting nauro serve --stdio (about a 1.5s timeout) and warns if it crashes on import or the binary is not found.
7. Prints a closing message to restart the agent and invoke /nauro-adopt.

The default project name is the repo directory basename; override it with --name <project>.

cd my-existing-repo
nauro adopt
# then restart your agent and run /nauro-adopt

The MCP entry written for every surface is {"command": "<nauro>", "args": ["serve", "--stdio"]}, placed where each tool expects it:

The /nauro-adopt skill is always installed. After restart, you invoke it and the skill walks the agent through reading docs (README, manifests, ADRs, Memory-Bank) for rationale and inspecting code, config, tests, lockfiles, and recent git history for evidence, then triages candidates and seeds the store via MCP tools.

Its write loop calls check_decision (a read tool, to surface overlaps) then propose_decision; update_state and flag_question are the other calls. The skill passes the project id as project_id on every call.

On Claude Code, the bundled subagents reference cloud tools by the fixed name mcp__claude_ai_Nauro__*; that prefix only resolves when the remote MCP connector is named exactly Nauro. Subagents are Claude Code only.

If a repo is already adopted and you pass --with-subagents, --with-skills, or --force-overwrite, adopt materializes the requested artifacts onto the existing adoption rather than dead-ending.

The closing message reads: “Next: restart your agent and invoke /nauro-adopt to seed context from this repo.” (the full line also adds a Cursor note about git add .cursor/rules/nauro-adopt.mdc).

The exact multi-line success transcript is assembled at runtime from per-surface status lines, so it varies with what got wired.

nauro adopt --with-subagents   # installs @nauro-planner/executor/reviewer/tech-lead into ~/.claude/agents/

nauro init <name> mints a local-only project: the CLI generates a 26-character Crockford-base32 ULID, writes .nauro/config.json in the cwd, scaffolds the store, and registers the project in the local registry. No network calls. The default name argument is demo-project.

• The config is resolved by walking up from the cwd (like git locating .git), so it identifies which project applies in that directory tree.
• init refuses to overwrite a .nauro/config.json that points at a different project, and refuses to mint a second project for a repo another project already claims. --force overrides the config-overwrite refusal for the cwd only.
• The store scaffold writes project.md, state_current.md, stack.md, open-questions.md, a decisions/ dir containing a teaching example 001-initial-setup.md, and an empty snapshots/ dir. The bracketed [prompts] to fill in appear in project.md, stack.md, and open-questions.md; state_current.md is the fixed placeholder _(No state recorded yet.)_.
• Local init output ends with “Next: run 'nauro setup claude-code' to connect your agent” and “Then: run 'nauro sync' to capture the first snapshot”.

nauro init my-project
nauro setup claude-code   # writes nauro into .mcp.json
nauro sync                # capture the first snapshot

The local-mode .nauro/config.json has the shape below; schema_version defaults to 1, and the loader rejects unknown versions. Cloud mode adds a "server_url" field.

{
  "mode": "local",
  "id": "01JABCD...",
  "name": "my-project",
  "schema_version": 1
}

• --add-repo <path> (repeatable, defaults to cwd) associates an existing local project with additional repo paths.
• --cloud mints a server-side project and writes a cloud-mode config with server_url. Adding repos to a cloud project is rejected; use nauro attach <project_id> instead.

Distinction from adopt: nauro init scaffolds an empty store with placeholder prompts (greenfield or manual); nauro adopt is the one-shot path for an existing repo that also wires MCP and installs the seeding skill.

After init, run nauro setup claude-code (or nauro setup cursor / nauro setup codex, or nauro setup all) to register the MCP server.

setup claude-code writes mcpServers.nauro = {"command": "nauro", "args": ["serve", "--stdio"]} into the repo's project-scope .mcp.json.

• MCP config is read at agent session start, so start a fresh session in a wired repo for it to take effect. The setup output says so: “Next: start a Claude Code session in one of the repos. The MCP server will start automatically.”
• Every setup-add path prints a discoverability hint so you can confirm Nauro works without restarting: Try it now from this shell: nauro check-decision "<approach>".
• setup claude-code also regenerates AGENTS.md so the cross-tool context file is fresh, and removes any legacy Nauro block from CLAUDE.md (behavioral guidance is now delivered via MCP server instructions). On the add path it also prunes a redundant user-scope HTTP nauro entry from ~/.claude.json.
• Optional: nauro setup claude-code --with-hooks wires an advisory UserPromptSubmit hook (nauro hook user-prompt-submit, 10s timeout) into the repo's .claude/settings.json. It surfaces related decisions as context each turn via BM25 retrieval and never blocks.

nauro setup all
nauro check-decision "Swap Postgres for DynamoDB"

• The free tier covers unlimited local usage, unlimited projects, and 5,000 remote MCP calls per month.
• Local usage (init, adopt, check-decision against a local store, and the demo) is entirely offline and uncapped. The demo requires no account, and the local init and adopt paths make no network calls.
• Hosted plan details live on the pricing page. How paid plans relate to the 5,000-per-month cap is covered there, not in these docs.

• Install: pipx install nauro or pip install nauro; requires Python 3.10+.
• Demo: exactly three commands. Run mkdir -p /tmp/nauro-demo && cd /tmp/nauro-demo, then nauro init --demo, then nauro check-decision "Add a WebSocket endpoint for live task updates".
• nauro init --demo seeds 7 decisions, project state, open questions, and a snapshot; the demo's default name is demo-project and its decisions are dated 2026-03-15.
• The WebSocket-surfacing seeded decision is #4 “SSE over WebSocket for live task updates” (rejected WebSocket due to ECS rolling-deploy connection drain: 30s stalls versus SSE's 3s reconnect).
• check-decision is an autogenerated CLI command; its required positional argument is proposed_approach, and its output is a JSON envelope with keys store, related_decisions, and assessment. It does not judge conflicts; it returns related decisions via BM25 retrieval over the store plus a deterministic assessment string.
• Local .nauro/config.json shape: {"mode": "local", "id": <ulid>, "name": <str>, "schema_version": 1}; cloud mode adds "server_url". Project IDs are 26-character Crockford-base32 ULIDs minted CLI-side for local projects; cloud IDs are server-minted.
• MCP entry written by setup for every surface: {"command": "<nauro>", "args": ["serve", "--stdio"]}. Claude Code uses .mcp.json, Cursor .cursor/mcp.json, Codex ~/.codex/config.toml under [mcp_servers.nauro].
• Always-installed skill: nauro-adopt. Opt-in via --with-skills: nauro-ship-task, nauro-handoff, and nauro-context. Cursor skills ship as <repo>/.cursor/rules/<name>.mdc.
• nauro adopt requires a git repo and refuses an already-adopted repo, unless --with-subagents, --with-skills, or --force-overwrite is passed (then it materializes onto the existing adoption).
• Bundled subagents (via --with-subagents, into ~/.claude/agents/): @nauro-planner, @nauro-executor, @nauro-reviewer, @nauro-tech-lead; off by default; a differing bundled file is refreshed with a <name>.md.bak, and --force-overwrite skips the .bak.
• nauro init scaffold writes project.md, state_current.md, stack.md, open-questions.md, decisions/001-initial-setup.md, and snapshots/. init refuses to overwrite a config pointing at a different project unless --force is passed (cwd only).
• Setup discoverability hint printed on every add path: Try it now from this shell: nauro check-decision "<approach>".
• Free tier: unlimited local usage, unlimited projects, 5,000 remote MCP calls per month. Hosted-tier specifics live on the pricing page.
• --demo cannot be combined with --cloud (rejected at command entry); --cloud projects cannot take --add-repo (use nauro attach).
• Optional advisory hook: nauro setup claude-code --with-hooks wires UserPromptSubmit to nauro hook user-prompt-submit (10s timeout) into .claude/settings.json; BM25 retrieval, never blocks.