Nura in your coding agent

Start

Two commands.

nura login                       # sign in (opens your browser)
nura --project Atlas sync         # link the repo to a project (name or id); reconcile, render, stamp

nura sync is one command. It reads what changed since the last sync and closes plans on evidence, writes the block, and stamps the lines that name a record. The first run in a terminal also sets up the repo. If the repo has no agent file, it asks which agent you use and creates that file. When it finishes, it offers to install the hooks.

The repo remembers its project, so later syncs and the hooks need no --project. A repo that isn't linked to a project refuses and says how to link it. It never falls back to your personal memory on its own. To sync your personal memory on purpose, run nura sync --personal; that block goes to .nura/personal.md, never to a tracked file. These need nura 0.3.2 or later; see the nura CLI to install or upgrade.

The managed block

One block, generated, stamped.

nura sync writes the block into the agent files the repo already has. It does not create one outside the first-run prompt. To write to a file the repo doesn't have yet, name it with --files, for example nura sync --render --files AGENTS.md.

The block sits between two markers. Text outside the markers belongs to you:

<!-- nura:begin v1 scope=project:harbor rendered=2026-09-30T14:02Z sig=65359b267778 -->
## Nura — project:harbor (generated; do not edit inside this block)
…
### Open plans
- [ ] Rotate the Stripe keys · owner: priya · due 2026-10-03 · nura:pl_8f3a1c2e
- [ ] Ship the pricing page · owner: marco · blocked on the copy · nura:pl_51d0b7aa
### Pending decisions
- Auth provider for the mobile app — options on record, no decision · nura:dc_0c44e9f1
### Decisions (current)
- Postgres over Mongo (2026-09-12) · nura:dc_7a91bbbb
<!-- nura:end -->

• Four sections: open plans, pending decisions, current decisions, and, for a project, Since you were last here (teammates), which lists what other members saved since you last opened the project.
• Every line is stamped with a short id, nura:<bucket>_<8hex>. For example, nura:pl_… is a plan and nura:dc_… is a decision. The stamp is how a change in the file finds its record.
• Open plans come in the order your brief uses: dated plans first, earliest first (so overdue ones lead), then undated plans by most recently changed. When the block runs out of room, the pressing ones are still in it. Current decisions are listed newest first.
• Owners appear as plain words (owner: priya), never as @-handles. Gemini CLI treats an @ word in GEMINI.md as a file to import. Work you assigned to Nura reads owner: assistant.
• The block stays small. Each section gets its own share of a fixed budget, and anything left over goes to the next section. When a section runs out of room, its last line tells the agent how to find the rest: N more — nura search --scope ….
• Personal memory stays out of git. It goes to .nura/personal.md, never to a tracked file. The .nura/ folder is excluded through .git/info/exclude.
• Your own lines get stamped too. A line outside the block whose text exactly matches a record's title gets that record's id. A close match is stamped only after you confirm it in a terminal.
• Rendering is deterministic. A second render with nothing new changes nothing.

Closing a plan

Evidence, never prose.

A plan closes in Nura in one of three ways:

• An agent calls the Nura tool.
• Someone ticks the checkbox on a stamped line inside the block.
• A commit message carries a trailer:

Rotate Stripe keys

Nura-Closes: nura:pl_8f3a1c2e

• Nura-Closes: <id> closes the plan. Nura records the commit as the evidence and credits the person who committed it.
• Nura-Ref: <id> links the commit to the plan without closing it.
• Nura-Reopens: <id> reopens a closed plan.
• Nura reads the trailer on its server. An id it doesn't know is refused and listed in the receipt.
• Deleting a line or editing one inside the block is not evidence. Nothing changes in Nura, and the block is rewritten at the next render.
• A line like “done X” written outside the block is shown as a candidate but never applied.

nura sync · advanced

One step at a time.

nura sync --render               # only write the block; no reconcile, no stamps
nura sync --reconcile            # only read the files' edits and the commits since the last sync
nura sync --dry-run              # show what would change; write nothing
nura sync --audit                # match every line in the agent files to Nura; writes nothing
nura sync --files CLAUDE.md      # only these files (globs work)
nura sync --undo                 # remove the block and every id sync added; Nura is not changed

--reconcile prints a receipt with one line per change. For example:

nura sync --reconcile
  close Rotate the Stripe keys — via commit 13c88498 · avery.lin@example.com
  already done: Ship the pricing page
  refused nura:pl_deadbeef: unknown
  candidate (not applied): done with the copy review

Use --dry-run to see the same receipt as would close … lines with nothing written. For scripts and CI, put --json before the command: nura --json sync --reconcile. --quiet prints nothing, which is what the hooks use.

nura hooks

No command to remember.

nura hooks install               # add the hooks to this repo
nura hooks doctor                # list what's installed and when the last sync ran
nura hooks uninstall             # remove them

• Git — post-commit, post-merge and post-checkout run nura sync --quiet. prepare-commit-msg suggests a Nura-Closes: trailer when the files you've staged share words with an open plan's title. The suggestion is a comment, so git drops it unless you uncomment it. Nothing is added to your message on its own.
• Claude Code — SessionStart renders the block and Stop reconciles. Both are set in .claude/settings.json. Session hooks exist for Claude Code only. The git hooks work with every agent.
• Installing twice changes nothing. If you already have a hook, Nura adds its call to the end of it. Every hook exits 0, so a sync can never block a commit.

Teams

Shared repos, shared projects.

• The collaborator check. A project block goes into tracked files only when everyone in the repo's git history is a project member, is mapped to one, or is you. If not, Nura writes the block to .nura/agent-block.md and the output names who isn't on the project. With --commit, it refuses instead (exit 3).
• Who gets credit. A trailer closure is credited to the member whose git identity made the commit. Map identities Nura can't match:

nura sync --map-author priya@example.com=@priya

Mappings are kept in the repo, in .nura/authors.json. A commit from an author Nura can't match is credited to whoever ran the sync, and the git author is kept alongside.

Moving an existing file over

Audit first.

If your CLAUDE.md already tracks plans by hand, run the audit before the first render. It matches every open, done and pending line in your agent files (plus docs/memory/*.md) to the project's records. It writes nothing:

nura --project Atlas sync --audit

It prints a table with one row per file and record, then a summary that counts those same rows. For example:

rows: agree 18 · disagree 0 · weak 345 (from 478 matched segments) · unmatched items 527

Agree means the file and Nura say the same thing. Disagree means they don't, for example the file says done and Nura says open. Weak means the match is uncertain, so it's yours to judge. Unmatched counts the lines Nura has no record for. A long note line is read in pieces (segments), and the pieces that match the same record share one row. Lines in the block are stamped, so they always agree.

• Done and dropped both count as closed.
• A lesson or a decision in force has no open or closed state, so a line calling it open or parked doesn't disagree with it.
• ⏳ means pending. A marker at the start of a line (⏳, ✅, [x], [ ]) covers the whole line.
• A name in quotes is a name: 'Open the beta' doesn't make a line open.