Skip to main content
Run these in a terminal on the developer’s machine. If 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 doctor from.
  • 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.
It exits with code 1 when something needs fixing, and sends nothing to nOps.

Pause, resume and uninstall

  • clara pause stops recording on this machine until you run clara resume. Use it when you don’t want a stretch of work recorded.
  • clara uninstall removes 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 place npx installs from. It checks each time its background service starts and about every six hours. Before switching to a new version it:
  1. checks the download’s checksum against the one the registry publishes,
  2. unpacks it safely and checks it is the expected package and version,
  3. runs it once to make sure it starts,
  4. and only then switches over, keeping the previous version.
If a new version fails to start later, the agent goes back to the previous one and won’t install that version again. To control updates:
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

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.
  • Check you’re working in a repository whose remote belongs to an allowed organization. Forks count only when their upstream remote 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.
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:
Windows’ default PowerShell execution policy skips profiles. Where your IT team allows it, run Set-ExecutionPolicy -Scope CurrentUser RemoteSigned.
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 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.
The agent needs Node.js 22 or newer. Update Node, then run npx @nops-io/clara again.