About Nauro
Nauro records approved software-project decisions, their reasons, and rejected alternatives for teams working with agents across sessions. It brings that context into later work; decisions require explicit human approval, and the local record is plain Markdown.
Key features
- 01Records approved decisions and reasoning
- 02Preserves rejected alternatives
- 03Retrieves context in later agent sessions
- 04Stores the local record as Markdown
- 05Optional cloud sync
Use cases
- 01Carry project rationale across agent sessions
- 02Review earlier decisions before changing direction
- 03Keep long-running work consistent across tools and handoffs
MCP support
Nauro documents a local stdio MCP contract and agent setup. Its MCP integration makes project decision records available to agents in later sessions.
Configuration
Local server config is the same for every client. Copy it into your client’s MCP config file.
Tools
12Saved tool list · updated 2w ago
| Parameter | Type | Required | Description |
|---|---|---|---|
| cwd | any | No | Optional. Absolute working directory used to resolve the project when project_id is omitted. |
| level | any | No | Detail level: L0 (concise), L1 (working set), L2 (full dump). |
| project_id | any | No | Optional; auto-resolved for one project. With several, list ids via list_projects (hosted) or `nauro projects` (local). |
Details
From the project README
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.
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
Report bugs and request features in GitHub Issues.
Apache 2.0. Named for Peter Naur's Programming as Theory Building (1985).
Comments
New to MCP?
From what the protocol is to installing your first server, these answers cover most first questions.
An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.