Nauro

Decision system for software built with AI

Keep your project's direction in human hands as agents do more of the work.

Nauro records the project decisions you approve, including their reasons and rejected alternatives. It brings those reasons into later agent sessions.

Status: Stable (1.x).

See it in practice

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

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

Is Nauro a fit?

Nauro supports longer-lived work across sessions, tools, and handoffs. If a small repo plus a reliable AGENTS.md or CLAUDE.md keeps agents oriented, Nauro may be more than you need.

Retrieval is advisory. New or revised decisions require your explicit approval. Local use needs no account; the record is plain Markdown on your machine. Cloud sync is optional. Nauro sends no product analytics.

Get started

Desktop app (macOS)

The free app installs the CLI, connects agents, and sets up a project. Its read-only viewer shows the project record.

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

Watch the desktop app tour

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

CLI

uv tool install nauro

Install uv, or use pipx install nauro with Python 3.10 or newer.

Try the demo (optional)

Pennykeep is the bundled fictional budgeting app.

• Request: Replace envelope budgeting with spending charts to simplify onboarding.
• Prior decision: In the fictional tester history, passive tracking did not help users control spending. The team accepted extra setup so users assign income before spending.
• Possible plan: Simplify envelope setup, or ask whether to revisit the budgeting model.

No account or agent setup required. On macOS or Linux:

mkdir -p /tmp/nauro-demo && cd /tmp/nauro-demo

nauro init --demo nauro check-decision "Replace envelope budgeting with a passive spending tracker and charts"

Look for Envelope budgeting method in the related decisions. This retrieves prior reasoning; it does not run an agent or change decisions. PowerShell and demo guide.

Use it on your repo

For CLI setup:

cd your-repo

nauro adopt --with-skills --with-subagents

Skip this command if the desktop wizard already adopted your repository. Restart your agent, then run /nauro-adopt in Claude Code, $nauro-adopt in Codex, or @nauro-adopt in Cursor. Review the proposed project record.

Approve one existing decision you want future sessions to remember. Start a fresh session and ask about a task where it matters. Check how the agent uses the reason.

Adopt wires Cursor only when ~/.cursor or a repository .cursor/ exists; otherwise run nauro setup cursor. Cursor requires a working durable absolute Nauro executable for global MCP wiring. Claude/Codex retain their existing fallback behavior. Follow Cursor migration before changing legacy wiring.

Run nauro status to inspect configuration and executable availability. See agent workflows and setup details.

The bundled nauro-investigator studies Claude and Codex logs for supported findings about Nauro use and development work. See the investigator guide for a bounded first run and a research notebook that later runs can resume.

An existing AGENTS.md is preserved unless you run nauro sync. Its # Manual section survives replacement.

Documentation

Documentation covers commands, storage, and cloud access. Semantic versioning covers the CLI, local stdio MCP contract, store format, and curated nauro-core API. Cloud sync and hosted MCP are versioned separately.

Website: nauro.ai.

Development

uv sync --all-packages --all-extras

uv run pytest packages/nauro-core/tests/ -x -q uv run pytest packages/nauro/tests/ -x -q

Bugs and feature requests: GitHub Issues. Contributing: CONTRIBUTING.md.

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