clara isn’t found, put npx @nops-io/ in front, for example npx @nops-io/clara status.
Commands
Check an install with clara doctor
clara doctor prints one line per part of the install, each with a fix when it isn’t right:
- Sign-in, and whether nOps still accepts this machine.
- Recording and the allowed organizations.
- Each AI tool’s hooks, and git’s hooks, including whether git runs them in the repository you run
clara doctorfrom. - Claude Code’s telemetry settings.
- The background service and the local relay.
- When data was last sent, and what is waiting.
- The local labelling model.
- Updates: the version, whether it updates itself, and the last check.
Pause, resume and uninstall
clara pausestops recording on this machine until you runclara resume. Use it when you don’t want a stretch of work recorded.clara uninstallremoves the AI tool hooks, git hooks, shell lines, Claude Code telemetry settings, the Clara MCP entries it added and the background service, deletes the machine’s key, and revokes the machine in nOps. Other MCP servers and your own git hooks are left as they were.
Updates
The agent updates itself from the npm registry, the same placenpx installs from. It checks each time its background service starts and about every six hours. Before switching to a new version it:
- checks the download’s checksum against the one the registry publishes,
- unpacks it safely and checks it is the expected package and version,
- runs it once to make sure it starts,
- and only then switches over, keeping the previous version.
CLARA_AUTO_UPDATE=0 in the service’s environment does the same as --auto off, for device management tools. nOps can also pause updates for your organization, for example while a bad release is pulled.
Machines installed before automatic updates existed can’t update themselves.
clara doctor warns about it. Run npx @nops-io/clara once more to fix it; you stay signed in.Troubleshooting
clara status says recording is paused because the allowlist is empty
clara status says recording is paused because the allowlist is empty
Your admin hasn’t added any allowed organizations yet. Ask them to add your GitHub organization, GitLab group or Bitbucket workspace in Settings → Integrations → AI ROI Agent → Policy. See Manage the agent. Machines pick up the change within five minutes.
My sessions don't show up in nOps
My sessions don't show up in nOps
- Check you’re working in a repository whose remote belongs to an allowed organization. Forks count only when their
upstreamremote does. - Check the tool is turned on in the policy’s AI tools.
- Run
clara doctor. It shows when data was last sent and whether anything is waiting. - Sessions appear about a minute after they happen. A session with no activity for an hour is closed and summarized.
Commits in one repository aren't recorded
Commits in one repository aren't recorded
With git older than 2.54, a repository that sets its own
core.hooksPath (Husky, lefthook, simple-git-hooks) replaces the agent’s hooks. Run clara doctor inside that repository: it warns about this. Update git to 2.54 or newer and run npx @nops-io/clara again.To turn the agent off in one repository on purpose (git 2.54 or newer), run there:Shell commands aren't counted on Windows
Shell commands aren't counted on Windows
Windows’ default PowerShell execution policy skips profiles. Where your IT team allows it, run
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.Prompt labels say the model isn't available
Prompt labels say the model isn't available
The model downloads the first time there’s a prompt to label. If it can’t run on the machine, labelling turns off and everything else keeps working. If your admin turned prompt labels off, no model is downloaded.
The terminal says nOps no longer accepts this machine
The terminal says nOps no longer accepts this machine
The machine was revoked, by an admin or by
clara uninstall, or you left the organization in nOps. Run npx @nops-io/clara to sign in again.Node.js is too old
Node.js is too old
The agent needs Node.js 22 or newer. Update Node, then run
npx @nops-io/clara again.