> ## Documentation Index
> Fetch the complete documentation index at: https://help.nops.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent commands and troubleshooting

> Check, pause, update and remove the AI ROI Agent, and fix common problems.

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

| Command | What it does |
| - | - |
| `clara` or `clara install` | Sign in with your nOps login and install. On a machine that's already signed in, prints `Already running as <email>`. |
| `clara status` | Who is signed in, whether recording is on, and what is sent. |
| `clara doctor` | Checks every part of the install and says how to fix what's wrong. |
| `clara pause` | Stops recording on this machine. |
| `clara resume` | Starts recording again. |
| `clara update` | Installs the newest version now. `--check` only looks; `--auto off` / `--auto on` stops or restarts automatic updates on this machine. |
| `clara version` | Shows the installed version. `--json` for scripts. |
| `clara uninstall` | Removes everything the agent added and revokes the machine. |

## 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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
clara update --check     # look, change nothing
clara update             # install the newest version now
clara update --auto off  # this machine stops updating itself
clara update --auto on   # turn it back on
```

`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.

> [!NOTE]
>
> 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

> [accordion] 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](https://help.nops.io/ai-roi/agent/admin.md#allowed-organizations). Machines pick up the change within five minutes.

> [accordion] 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 `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.

> [accordion] 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:
>
> ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
> git config hook.nops-clara-post-commit.enabled false
> git config hook.nops-clara-post-merge.enabled false
> git config hook.nops-clara-post-checkout.enabled false
> ```

> [accordion] 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`.

> [accordion] 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.

> [accordion] 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.

> [accordion] Node.js is too old
>
> The agent needs Node.js 22 or newer. Update Node, then run `npx @nops-io/clara` again.

## Related

* [Install the AI ROI Agent](https://help.nops.io/ai-roi/agent/install.md)
* [What the agent sends and keeps](https://help.nops.io/ai-roi/agent/privacy.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.