Docs

naoru — onboarding

naoru runs an autonomous test-and-improve loop against your personal test software: it runs checks you declare ("leaves"), and when one fails it lets an LLM edit the repo in an isolated worktree, re-runs the check, and commits only when the mission gate accepts the candidate. Works on any language (the checks are just commands), using your own LLM access. There is no naoru account and no product telemetry to Unpossible Creations. Naoru stores a local license-acceptance receipt on your machine; your configured host or provider CLI may transmit code, prompts, paths, logs, and other data to third-party LLM providers under their terms.

Naoru is a research preview licensed only for personal, non-commercial U.S. technical evaluation. It is provided AS IS, can modify and commit code, and is not licensed for employer, business, client, production, or commercial use.

This guide is self-contained. A host provider plugs naoru into your machine: which LLM to call, where the runtime lives, and how your tooling is discovered. See Naoru Privacy Notice for the local/no-product-telemetry posture and provider-data warning.

1. Install

uv tool install "naoru[obra-host]"     # naoru + the host that supplies LLM dispatch

Then make sure your LLM provider CLI is logged in (whichever you use), e.g. codex login, claude login, or gemini/agy auth. naoru inherits whatever provider/model the host is configured for — set or change it any time with:

naoru config --accept-license "I ACCEPT"  # first use only; stores a local receipt

That is the one-time command-line license acceptance for first functional use. After a valid local receipt exists, the rest of the examples omit --accept-license until the license changes.

You don't have to pass a provider on every run; naoru config (or your host config) is the default. Flags like --provider/--model/--tier/--reasoning-level are overrides when you want them. To inspect the resolved Naoru role policy without opening the host picker, run:

naoru config --show-resolved

2. Author a leaf set

A leaf is one check: a command to run + a predicate that says when it passed. Author leaves in .toml (human-friendly) or .json (handy when an LLM writes them). Both load identically.

The command is an arbitrary argv — use your personal test repo's own machine-checkable command:

# leaves.toml
[[leaves]]
id = "project-check"
command = ["./scripts/check_project"]
fix_focus = "Make the failing project check pass without weakening assertions."

  [leaves.predicate]
  kind = "exit_code"                 # GREEN when the command exits 0
  expected_exit = 0

Predicate kinds: exit_code (exit status), output_substring (required/forbidden strings), traceback_signature / contract_violation (a failure signature that must be ABSENT once fixed), non_crash (process exits cleanly), metric (parse a number from output — for performance missions). See harness architecture for the full field list.

To skip writing leaves by hand, let naoru propose a starter set from your personal test repo's tooling:

naoru leaves generate --repo . --out leaves.toml   # then refine it

Generated leaves are starter seeds. Before a real fix loop, read the leaf authoring guide at leaf authoring guide or run naoru help leaf-authoring. Refine each command, predicate, fix_focus, timeout, and loop cap until the leaf is a reliable machine-checkable signal.

3. Run a mission

For a new leaf set, start with a no-fix baseline:

naoru run --mission test-and-fix-bugs --leaves leaves.toml --repo . --max-fix-loops 0

Review the baseline output. If a raw command is noisy, broad, or not a trustworthy RED/GREEN signal, put that interpretation in a project-local wrapper command and point the leaf at the wrapper.

Then pick a --mission for what you want naoru to do:

naoru run --mission test-and-fix-bugs --leaves leaves.toml --repo .

After an accepted fix, run the same no-fix command again as final no-fix verification.

Use naoru terms to view the current license summary and receipt status.

Conservative defaults: edits run sandboxed and nothing is committed without passing its gate. --unsafe opts into unsandboxed full-auto; use it only in a personal, isolated test repo you fully control. Subjective missions never auto-commit, even with --unsafe.

4. Read the result

Each leaf reports one of: green (already passed), fixed (gate committed a fix), proposed (subjective patch stored for review), rejected (a fix was produced but the gate refused it), or error. Exit codes: 0 all green/fixed/proposed · 3 something was gate-rejected · 4 error. rejected means the candidate patch was refused and not committed. It is not proof the repo remains red after other accepted fixes; a final no-fix verification pass is the source of truth.

Try it now

examples has a runnable demo with a seeded bug — see examples.

Architecture, leaf schema, mission→gate model, and the host contract: harness architecture.