Quickstart

Install uv first if you do not already have it; Astral provides instructions for macOS, Linux, and Windows. Then install Nauro with the command below. uv acquires a compatible Python automatically. Already on Python 3.10+? pipx or pip work too.

• 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. Setup validates candidates and writes a durable absolute executable path with ["serve", "--stdio"] into your MCP client config whenever one is available.

After uv tool install, the nauro binary is on your PATH; if your shell can't find it, run uv tool update-shell once and restart your shell. (With pipx the equivalent is pipx ensurepath.)

uv tool install nauro   # uv fetches its own Python

nauro adopt bootstraps a project from an existing repo in one shot: it mints the project, scaffolds the store, wires the MCP server into Claude Code, Cursor, and Codex, and installs the seeding skill. Run it from the repo root, or pass --repo <path>.

cd my-existing-repo
nauro adopt --with-skills --with-subagents
nauro status
# Restart, then use /nauro-adopt in Claude Code or $nauro-adopt in Codex

That is the whole adoption. Restarting the agent picks up the new MCP config, and the nauro-adopt skill walks the agent through seeding the store from the repo’s docs, code, and git history. Everything below is detail.

The --with-skills --with-subagents flags install the complete Claude Code and Codex workflow (the four workflow roles plus the opt-in skills). Plain nauro adopt is the minimal path: it wires MCP and installs only the core nauro-adopt skill.

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 installs the core nauro-adopt skill across Claude Code, Cursor, and Codex. The complete-workflow flags also install the opt-in skills and workflow agents for Claude Code 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 in Claude Code or $nauro-adopt in Codex; Cursor uses the installed rule.

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

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

Commit .nauro/config.json: it is the portable project-identity pointer. The repo-local MCP and hook files contain a machine-specific absolute executable path, so setup regenerates them per machine, adds them to a managed .gitignore block, and refuses to write that path into a file already tracked by git.

The nauro-adopt skill is always installed. After restart, invoke /nauro-adopt in Claude Code or $nauro-adopt in Codex. 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.

Claude Code and Codex both receive the four workflow roles from the same bundled instruction bodies. Claude Code writes Markdown definitions under ~/.claude/agents/; Codex writes TOML definitions under ~/.codex/agents/. Cursor is the only unsupported subagent surface. Claude Code's definitions reference cloud tools by the fixed name mcp__claude_ai_Nauro__*, so that remote connector must be named exactly Nauro.

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. --remove likewise runs against an existing adoption: it is the inverse of adopt, and how you undo one.

The closing message names the surface-specific invocation: /nauro-adopt in Claude Code, $nauro-adopt in Codex, or the installed Cursor rule. It also notes that committing .cursor/rules/nauro-adopt.mdc shares the Cursor rule with collaborators.

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-skills --with-subagents
# Installs the complete workflow for Claude Code and Codex

nauro import migrates existing records into the current repo's project store, so an adopted repo keeps its history instead of restating it. Run it after nauro adopt (or nauro init); it resolves the project from the cwd (--project NAME overrides) and captures a snapshot afterward. --adr takes a directory of NNN-title.md Architecture Decision Records; --memory-bank takes a Cline / Roo Code .context/ directory, whose decisionLog.md entries need ## Decision: <title> headings to import.

nauro import --adr docs/adr          # NNN-title.md decision records
nauro import --memory-bank .context  # Cline / Roo Code Memory Bank

No repo handy? 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. Starting the demo from another directory reuses that registered demo project instead of minting a duplicate. Re-running in the same directory exits without writing; pass --force only when you intend to reseed the demo there.
• 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 “Pennykeep” local-first budgeting app. --demo seeds project.md, state_current.md, stack.md, open-questions.md, 13 pre-written decisions under decisions/ (9 active and 4 superseded, including a consolidation where three earlier approaches are retired by one and a two-step chain), and one snapshot at snapshots/v001.json.
• The init output reports it literally: “Includes: 13 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 surface related prior decisions”.

mkdir -p /tmp/nauro-demo && cd /tmp/nauro-demo
nauro init --demo
nauro check-decision "Store dollar amounts as decimal numbers"

New-Item -ItemType Directory -Force "$env:TEMP\nauro-demo" | Out-Null
Set-Location "$env:TEMP\nauro-demo"
nauro init --demo
nauro check-decision "Store dollar amounts as decimal numbers"

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 money-representation query, the surfaced decision is decision #1 “Amounts stored in integer cents, never floating point” in the demo fixture (status active, dated 2026-03-15).

Per its rationale, Pennykeep stores every monetary amount as an integer number of cents and formats to dollars only for display, because binary floating point cannot represent most decimal amounts exactly (0.10 + 0.20 comes out as 0.30000000000000004), so floating-point dollars make sums and budgets drift by a cent.

A floating-point dollar amount field was rejected because binary floating point cannot hold a value like 0.10 exactly, so totals accumulate rounding error and reconciliations fail by a penny; integer cents keep every amount exact with plain integer math.

{
  "store": "local",
  "related_decisions": [
    {
      "id": "decision-001",
      "title": "Amounts stored in integer cents, never floating point",
      "score": 8.462,
      "status": "active",
      "date": "2026-03-15",
      "rationale_preview": "Every monetary amount (transactions, budgets, balances) is stored as an integer number of cents and formatted to dollars only for display..."
    }
  ],
  "assessment": "Found 5 related decisions. Top match: D001 \"Amounts stored in integer cents, never floating point\"...",
  "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.

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.

Still in the demo directory, run nauro graph to render the seeded store to one self-contained HTML file and open it in a browser. The file is self-contained, so you can pan the decision map, walk a supersession thread on the Lineage view, or read the demo decisions on a date axis with no wiring. It writes to the store directory by default, since the page embeds the store's titles and metadata; pass --output ./graph.html to put it somewhere you choose.

nauro graph   # renders the demo store and opens it in your browser

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. When the name is omitted it defaults to the directory name (demo-project is the default only with --demo).

• 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": "<validated absolute path to nauro>", "args": ["serve", "--stdio"]} into the repo's project-scope .mcp.json when a durable install is available.

• 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.”
• Run nauro status before restarting. It probes the recorded executable and reports MCP, Codex hooks, installed skills, workflow agents, and AGENTS.md state. Run nauro doctor separately to check store integrity.
• A shell call such as nauro check-decision "<approach>" proves local project resolution and retrieval, but it does not prove that an agent loaded MCP. The final check is a fresh agent session in the wired repo followed by a Nauro MCP call or the installed nauro-adopt skill.
• Adopt, setup, and incidental regeneration preserve an unmanaged AGENTS.md and warn. nauro sync is the sole explicit overwrite path. A # Manual section survives replacement.
• setup claude-code refreshes a Nauro-managed AGENTS.md, automatically strips Nauro's retired marked block from CLAUDE.md, and writes a Nauro-owned @AGENTS.md bridge only when CLAUDE.md is absent. An existing foreign file is never modified; setup advises when it lacks a live import. It also prunes a redundant user-scope HTTP nauro entry from ~/.claude.json.
• Optional: nauro setup all --with-hooks wires Claude Code's advisory UserPromptSubmit hook in .claude/settings.local.json and Codex's SessionStart / SubagentStart hooks in .codex/hooks.json. Codex skips new or changed hooks until you review them through /hooks. The hooks surface context and never block.

nauro setup all
nauro status
nauro doctor
# Then start a fresh agent session in this repo

• 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.
• Cloud sync and remote MCP access are included within the 5,000-call allowance. Contact support if you need a higher hosted limit.

• Install: install uv if needed, then run uv tool install nauro (or pipx install nauro with Python 3.10+). uv acquires Python for you.
• Demo: macOS and Linux can use mkdir -p /tmp/nauro-demo && cd /tmp/nauro-demo; PowerShell can create and enter $env:TEMP\nauro-demo. Then run nauro init --demo and nauro check-decision "Store dollar amounts as decimal numbers". A same-directory rerun requires --force and reseeds the demo.
• nauro init --demo seeds 13 decisions (9 active, 4 superseded), project state, open questions, and a snapshot; the demo's default name is demo-project. The superseded decisions form a consolidation fan and a short chain, so the store carries lineage to explore.
• The money-representation-surfacing seeded decision is #1 “Amounts stored in integer cents, never floating point” (rejected a floating-point dollar amount field because binary floating point cannot hold 0.10 exactly, so totals drift by a penny).
• 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": "<validated absolute path to nauro>", "args": ["serve", "--stdio"]} when a durable install is available. Claude Code uses .mcp.json, Cursor .cursor/mcp.json, Codex ~/.codex/config.toml under [mcp_servers.nauro]. A working but fragile project-venv path is recorded only with a warning; bare nauro is the terminal fallback and also warns.
• Always-installed skill: nauro-adopt. Opt-in via --with-skills: nauro-ship-task, nauro-context, and nauro-loop. 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), or --remove is passed (then it un-adopts it). Adoption preserves an unmanaged AGENTS.md with a warning.
• Un-adopt: nauro adopt --remove removes the MCP/skill/subagent/hook wiring, strips the generated AGENTS.md (keeping a # Manual section), deletes .nauro/config.json, and deregisters the repo; the store is kept unless --purge-store is passed on the project's last repo, and --yes skips the confirmation prompt.
• Migrate existing records after adopt or init: nauro import --adr <dir> (NNN-title.md files) or nauro import --memory-bank <dir> (Cline / Roo Code .context/; decisionLog.md entries need ## Decision: <title> headings). Each import captures a snapshot.
• Complete workflow: nauro adopt --with-skills --with-subagents. The four roles install into ~/.claude/agents/ for Claude Code and ~/.codex/agents/ for Codex. --force-overwrite applies to Nauro-owned skills and agent definitions and skips their recoverable backups.
• 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>".
• Hosted access includes cloud sync and remote MCP access within the 5,000-call monthly allowance. Contact support if you need a higher hosted limit.
• --demo cannot be combined with --cloud (rejected at command entry); --cloud projects cannot take --add-repo (use nauro attach).
• Verification: nauro status diagnoses MCP and workflow wiring; nauro doctor checks the store. Restart the agent before the final MCP check.
• Optional advisory hooks: nauro setup all --with-hooks wires Claude Code UserPromptSubmit plus Codex SessionStart and SubagentStart. Review new Codex hooks through /hooks.