How Niro fits your workflow
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:
- An error message or a stack trace: the thrower, its callers, who catches it.
- A wrong value: who writes the table or field, and which event delivered it.
- A failing call between services: the caller, the handler, the address, two services on one route.
- "It broke after my change": what the change reaches, tests first.
- Config and environment: which settings the code reads, where they are set, calls with no address.
- A slow path: what a slow method calls, and where it goes to the database.
Building and checking:
- Change code safely
- Add a feature
- Review a change
- Test a change
- Learn a new codebase
- Data stores and events
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
- Ask for the shortest form that answers you.
answer=countfor "how many",answer=locationsfor "where",answer=namesfor "which". See Get shorter answers. - Use the graph tool for structure, and
code_grepfor text. Callers, routes, tables and events come from the graph; error messages, setting names and comments come fromcode_grep. - 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.
- 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.