Niro is a ground truth layer. Ground truth means facts read from the code itself, not from memory or guesses. Before a person or an agent changes code, reviews it, tests it or debugs it, they can check it against a map built from the code as it is now. The map says who calls what, which routes exist, which services talk to each other, and which tables and events are touched.

An everyday comparison: a builder checks the plans of the building before knocking down a wall, to see which pipes run through it. Niro is the plan of your code, and it is redrawn as the code changes.

Why it matters for an agent: an agent that builds a list of callers from a text search is usually close and sometimes wrong (measured: in one of our Keycloak A/B sets, every fact the shell-only agent missed was a class reached through an interface). That a wrong list then leads to a wrong edit and a second round of work is reasoning, not measured. Niro's lists say whether they are complete, and why not when they are not. How that pays off over a session is in Tokens, speed and accuracy.

What people actually ask

These shares come from 794 recorded Niro calls in agent sessions over 14 days, each labelled by task. Three limits: the sessions are mostly Niro's own development (so debugging is under-represented), hosted and local Niro calls are counted together, and the labels were made by hand by one agent, so treat each share as about plus or minus 10%.

Task Share of calls Playbook
Understand how existing code works 41% Playbook: learn a new codebase
Change code safely: map callers before an edit 18% Playbook: change code safely
Add a feature: find what exists, follow its shape 9% Playbook: add a feature
Debug a wrong value, a slow path or an exception 6% the debugging playbooks below
Find where something is 4% Playbook: learn a new codebase
Calls between services 3% Playbook: debug a failing call between services
Data stores and events 3% Playbook: data stores and events
Config and environment 3% Playbook: debug config and environment
Testing and review 2% Playbook: test a change, Playbook: review a change

The playbooks

Each playbook starts from a question in a user's own words and runs real tool calls on public code: Keycloak, and a synthetic multi-service corpus. It shows the real answers, says why each answer is complete or where it is not, and compares it with grep and file reads.

Debugging:

Building and checking:

The stages

Stage Who How they reach Niro What Niro gives them Page
Plan and design A developer, or a planning agent A coding agent, or niro ask in the terminal What a planned change reaches, in both directions Plan and design with Niro
Write code The coding agent; the developer 14 coding agents over MCP (the Model Context Protocol, the standard way coding agents call outside tools); niro ask Call chains, callers before an edit, the source of one method Write code with Niro
Review A reviewer; a review bot The reviewer's own agent, or niro ask, on the branch What the change reaches. Pull request review as a product is hosted Niro only. Review changes with Niro
Test A developer, QA, a test-writing agent MCP or niro ask Which callers a change reaches, and which of them are tests Choose what to test
Debug A developer, a debugging agent MCP or niro ask Exceptions, writers of a table, handlers of a route or event, what a method calls. Root cause analysis from alerts is hosted Niro only. Debug with Niro
Onboarding A new team member; an agent in a new repository niro ui, niro ask, MCP Services and how they connect, endpoints, data stores, events Learn a codebase with Niro
Security and privacy A security reviewer, an admin Any of the above What Niro reads, keeps and sends; every route and every outbound call, for an attack-surface list Security and privacy across the lifecycle

Four habits that make answers smaller and better

  1. Ask for the shortest form that answers you. answer=count for "how many", answer=locations for "where", answer=names for "which". See Get shorter answers.
  2. Use the graph tool for structure, and code_grep for text. Callers, routes, tables and events come from the graph; error messages, setting names and comments come from code_grep.
  3. Ask the name the callers use. For a method declared on an interface, ask the interface name the calls are written against. See FAQ: wrong or missing answers.
  4. Read the confidence line. "complete" means use it as it is. "PARTIAL" says what was cut and how to get the rest.

See what it did for you

The line at the end of each task, the record of what was asked, and a do-it-yourself A/B: Check what Niro did.

What this version does not do

This version of niro-cli answers everything from the graph on your computer. Pull request review and root cause analysis are features of hosted Niro, because the local graph does not answer them. See Features of hosted Niro.