Nauro

Nauro is a decision system for agentic engineering. It keeps your project's decisions, rationale, and rejected paths in plain markdown files, then surfaces the relevant ones before an AI agent plans or changes code.

It works across Claude, Cursor, Codex, Perplexity, and any MCP client. The result is persistent project judgment that travels with the work, not with a single tool or session.

https://github.com/user-attachments/assets/9e6c475b-c584-470b-84c2-12f01b3a425a

A coding agent checks the project's prior decisions before it plans, then records the approved decision and makes the change. Captured in Codex.

Status: Beta (pre-1.0). The local CLI and stdio MCP server are stable; cloud sync is stabilizing.

More at nauro.ai.

How it works

Nauro stores your project's decisions as plain markdown files, each with the alternatives you ruled out and the reasoning behind them. When an agent proposes an approach, check_decision runs deterministic keyword retrieval (BM25) over those files and surfaces the related ones before the agent plans or writes code.

No model judges your decisions. The check is advisory and never blocks a change. A decision is recorded only by an explicit write call, and the approval gate lives in the conversation. The store is a folder you own; remove Nauro and the markdown stays.

Install

uv tool install nauro     # uv fetches its own Python — nothing else needed

No uv? Install it with curl -LsSf https://astral.sh/uv/install.sh | sh (macOS/Linux) or the PowerShell line on Windows. Already on Python 3.10+? pipx install nauro (or pip install nauro) works too.

Quickstart

No account, no MCP wiring, no restart:

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

The demo store holds seven example decisions. One of them ruled out WebSocket in favor of SSE, and check-decision surfaces it as the top match before your agent can re-propose it:

{
  "store": "local",
  "related_decisions": [
    {
      "id": "decision-004",
      "title": "SSE over WebSocket for live task updates",
      "score": 5.015,
      "status": "active",
      "date": "2026-03-15",
      "rationale_preview": "Server-Sent Events (SSE) for pushing live task updates to the frontend. SSE uses standard HTTP, reconnects automatically on disconnect, and works through every proxy and load balancer..."
    }
  ],
  "assessment": "Found 5 related decisions. Top match: D004 \"SSE over WebSocket for live task updates\" (status active, decided 2026-03-15, BM25 5.0). Call get_decision on each related decision before proposing.",
  "project": { "id": "01K...", "name": "demo-project" }
}

Output abbreviated to the top match; the live call returns all five related decisions, ranked by score. The same result reaches your agent through the MCP check_decision tool, so it sees the prior decision in the flow rather than after the fact.

Why not ADRs, grep, or CLAUDE.md?

A decision log in your repo is a good record. The gap is on the read side: a file is read when a person opens it, and a fresh agent session starts with no knowledge that it exists. Nauro closes that gap. The relevant decision reaches your agent automatically, through MCP, at the moment it proposes a change. The store lives outside any single agent's memory, so the same project record is available across tools and sessions instead of being trapped in one prompt file, repo note, or chat history.

When Nauro helps, and when it doesn't

Nauro pays off when an agent needs project judgment before acting: architecture choices, rejected approaches, migration plans, operational constraints, and decisions that recur across sessions or tools.

The limits are worth knowing. It surfaces only what has been recorded as a decision. It adds an MCP round-trip to the agent's flow. Retrieval is keyword-based, which is fast, offline, and auditable, and can miss a decision phrased in different words than the proposal; an optional embeddings index is available for closer synonym matching.

Adopt Nauro in your project

New project:

nauro init my-project
nauro setup claude-code   # or: nauro setup all

nauro init writes .nauro/config.json into the repo; commit it. For cloud sync from the start, run nauro auth login first, then nauro init --cloud my-project.

One project across several repos: the store lives outside any repo, so multiple repos can share it. Associate another repo with an existing project from inside that repo:

cd ../my-other-repo
nauro init my-project --add-repo .

Re-running plain nauro init my-project in a second repo creates a separate project that shares no decisions — use --add-repo to link them instead.

Existing repo with docs to seed from:

nauro adopt

nauro adopt registers the project, wires MCP across Claude Code, Cursor, and Codex, and installs a /nauro-adopt skill. Restart your agent and invoke /nauro-adopt.

Add --with-subagents on nauro adopt or nauro setup to install Nauro's bundled Claude Code subagents into ~/.claude/agents/. The typical workflow:

• @nauro-planner before non-trivial work. Drafts a plan and classifies doctrine risk (GREEN/AMBER/RED) against your decision log.
• @nauro-executor after a plan is agreed. Implements it, runs tests, opens a PR.
• @nauro-reviewer before merging. Audits the diff for real bugs and for missing decision references.
• @nauro-tech-lead to set or correct direction. Reads the decision log, audits PRs against doctrine, files decisions when direction is established.

Chat surfaces (Claude.ai, Perplexity): run nauro adopt from a terminal first, then point the chat agent at docs/adopt-prompt.md.

Cross-surface sync (optional)

The steps above work fully on your machine with no account. To sync a project to the cloud and reach it from surfaces without a local copy (claude.ai web) or from another machine:

nauro auth login
nauro link --cloud   # one-time: promote the local project to cloud
nauro sync

Then add https://mcp.nauro.ai/mcp as an MCP connector in your tool's settings.

Codex (remote connector)

Add it under a name distinct from the local nauro stdio server:

codex mcp add nauro-cloud --url https://mcp.nauro.ai/mcp

Then pin the OAuth callback port at the top of ~/.codex/config.toml. Codex's callback uses a fixed, pre-registered port; without it Codex picks a random port and login fails:

mcp_oauth_callback_port = 8765

Requires Codex 0.131.0 or newer. Enter the URL exactly as shown, with no trailing slash. If login reports a callback-port error, free port 8765.

MCP tools

11 tools total (8 read, 3 write). The local stdio server registers 10 (7 read, 3 write); list_projects is remote-only.

Read: check_decision, get_context, list_decisions, get_decision, search_decisions, get_raw_file, diff_since_last_session, list_projects (remote-only).

Write: propose_decision, flag_question, update_state.

nauro check-decision "<approach>" runs check_decision from the shell. The write tools surface the same way:

nauro propose-decision "Adopt Redis" "In-memory cache for hot read paths" \
    --files-affected src/cache.py --files-affected src/api.py \
    --rejected '[{"alternative": "Memcached", "reason": "Less feature-rich"}]'

Repeat --files-affected for each entry. --rejected accepts inline JSON, @file.json, or - to read from stdin.

Packages

nauro-core is the parsing, validation, and context assembly shared between the CLI and the hosted MCP server. Minimal dependencies; usable by third-party tools that read or write the Nauro decision format.

The hosted MCP server (mcp.nauro.ai) lives in a private repository.

Development

See CLAUDE.md for architecture. Bugs and feature requests: GitHub Issues.

uv sync --all-packages --all-extras
uv run pytest packages/nauro-core/tests/ -x -q
uv run pytest packages/nauro/tests/ -x -q

Apache 2.0.

Named for Peter Naur, whose 1985 paper Programming as Theory Building argued the real program is the theory in the programmer's mind, not the code. Every fresh agent session is the equivalent of losing that programmer.