Niro keeps its files in two folders in your home folder. ~/.niro belongs to the niro command. ~/.niro-local belongs to the local engine, which holds the graph. Both are readable by your user account only.

~/.niro

File or folder What it holds
credentials.json Your sign-in. Readable by you only
config.json Settings: the service addresses and the console address you signed in through. See Settings files
bin/<version>/ The downloaded local engine. Set NIRO_ENGINE_HOME to keep it elsewhere
local-worktrees.json The worktrees the watcher has seen, and its build retries
onboarding.json How long each step of niro start took, and how it ended. Kept on this computer only
periodic.json When each regular job last ran
audit-repos.json Folders sent with niro audit-push-repo or shared in the background, and the workspace each went to
shared-code.json For code sharing: per folder, a fingerprint (SHA-256), size and time of each file last sent, so only changed files are sent again. No file contents. Readable by you only
share-excluded.json The folders kept out of code sharing (niro share exclude). Readable by you only
journal-refused/ Tool-usage records the service refused, kept for you to look at
receipts/ Used by older versions only. Removed when you remove Niro from Claude Code, or by niro uninstall
impact/ The recent-edits log the impact check uses
receipts-off, impact-gate-off Empty files whose presence turns the end-of-task line or the impact check off
projects.json Used by hosted Niro only

~/.niro-local

Set NIRO_LOCAL_HOME to keep this folder elsewhere.

File What it holds
graph.db The graph, for every project on this computer
build-state.db What each build needs to be quick next time: a fingerprint (hash), size and time of each file, and what reading each file found
registry.db Your projects, their folders and branches, and your settings for them
journal.db The record of which tools your agent used, waiting to be sent
audit-queue.db Coverage audit findings, waiting to be sent
docs.db For LLM documentation, which this release does not include
indexed-folders, locks/ The list of indexed folders, and lock files that stop two builds from clashing

There is one graph.db and one build-state.db for all projects. To check the graph file, run niro db status. To check that it opens, run niro db check.

Is your source code stored? The graph does not keep your source. It keeps names, places and links. The build state keeps fingerprints of files, and what reading them found. That can include short values written in the code, such as a default value. All of it stays on this computer.

Files written into your coding agents

niro mcp install writes into each agent's own settings. The files are listed on each agent's page, for example Connect Cursor to Niro.

The background watcher

The watcher is run by PM2, which keeps its list of programs in ~/.pm2/dump.pm2. Niro makes that file readable by you only. On macOS, starting the watcher at login uses a file in ~/Library/LaunchAgents.

What niro uninstall removes

It removes ~/.niro, ~/.niro-local, the watcher and the agent settings. See Uninstall.