Nauro

The decision system for building software with AI.

Nauro gives connected agents human-approved project judgment and current state before they plan or change work.

Before work, Nauro surfaces the relevant part of that record. Approved judgment and reported progress carry into later sessions and connected tools.

Status: Stable (1.x). Semantic versioning covers the CLI, local stdio MCP contract, on-disk store format, and curated nauro-core import API. Cloud sync and hosted MCP are versioned separately.

See it in practice

https://github.com/user-attachments/assets/f75ede99-db11-4460-bc09-801c86df1e19

A real Codex session, then a Claude session in Pareto, Nauro's development mock project.

Install

uv tool install nauro

Install uv with curl -LsSf https://astral.sh/uv/install.sh | sh on macOS or Linux, or use the Windows instructions. With Python 3.10 or newer, pipx install nauro also works.

Try the demo

Pennykeep, the bundled demo, needs no account or agent setup:

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

The top result is D001, Amounts stored in integer cents, never floating point. Its rationale explains why floating point makes money totals drift.

Use it on your repo

cd your-repo
nauro adopt --with-skills --with-subagents

Restart your agent, then invoke /nauro-adopt in Claude Code or $nauro-adopt in Codex. The skill reads the repo, asks about missing rationale, and seeds the project record. The optional flags also install the gated nauro-ship-task workflow and its four workflow agents.

Run nauro status to check MCP, skills, and workflow agents. Run nauro doctor to check the project store.

Nauro surfaces prior judgment for the agent to assess. Retrieval is advisory. New or revised judgment requires your explicit approval. Local use needs no account, and the record is plain Markdown on your machine. Cloud sync and remote MCP access are optional. Nauro sends no product analytics.

Nauro preserves an existing AGENTS.md unless you explicitly run nauro sync. A # Manual section survives replacement.

Desktop app (macOS)

A free, read-only viewer for the project record: timeline, map, list, activity, and docs. First launch installs the CLI, connects your agents, and adopts or attaches a project.

https://github.com/user-attachments/assets/e23d3d7f-2d5b-4ce4-be18-fcaff74e7973

Download for macOS (Apple silicon), signed and notarized.

Fit

If a small repo plus a reliable AGENTS.md or CLAUDE.md keeps agents oriented, Nauro may be more than you need.

Nauro is intended for longer-lived work where context can decay across sessions, tools, repositories, machines, or repeated handoffs.

Read the documentation for setup variants, concepts, command references, storage, and cloud access.

Development

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

Report bugs and request features in GitHub Issues.

Apache 2.0. Named for Peter Naur's Programming as Theory Building (1985).