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

# Set up AI ROI

> Connect an AI coding tool and a code host, then sharpen the numbers with teams, tickets and the AI ROI Agent.

AI ROI needs two connections: **an AI coding tool** and **a code host**. Everything else makes the numbers sharper. The **Setup** tab on the AI ROI page checks each one for you and says what to do next.

> [!NOTE]
>
> The Setup tab is shown to executives (organization admins, or a role with the `ai-roi:executive` permission). Connecting integrations needs permission to manage integrations in **Settings → Integrations**.

## Before you start

* AI ROI is turned on for your organization. It is in preview; contact your nOps account team.
* You can open **Settings → Integrations** in nOps.
* You know which GitHub organizations, GitLab groups or Bitbucket workspaces hold your company's code.

## The checklist

The Setup tab lists six steps. Until both **required** steps have data arriving, Setup is the only tab you see: the scores would mean nothing yet. After that, Setup moves to the last tab and shows a badge such as **4/6**.

Each step shows one of four states:

| State | Meaning |
| - | - |
| **Done** | Connected, and data is arriving. |
| **Waiting for data** | Connected. The first data usually arrives within a day. |
| **Needs action** | Something is wrong. The step says what. |
| **Not set up** | Optional, and not connected yet. |

### 1. Connect an AI coding tool (required)

**Unlocks:** AI spend per person.

Connect at least one of:

* [Cursor](https://help.nops.io/integrations/cursor-admin-api.md)
* [Claude Enterprise](https://help.nops.io/integrations/claude-enterprise.md) (Claude Code spend counts; chat use does not)
* GitHub Copilot, which needs no separate connection: its spend comes in through the [GitHub](https://help.nops.io/integrations/github.md) integration, matched by GitHub login.

The step is done once spend arrives. A connection with an error shows **Needs action**: open it and fix the key.

### 2. Connect your code host (required)

**Unlocks:** merged PRs, AI cost per PR, time to merge.

Connect one or more of:

* [GitHub](https://help.nops.io/integrations/github.md)
* [GitLab](https://help.nops.io/integrations/gitlab.md) (gitlab.com)
* [Bitbucket Cloud](https://help.nops.io/integrations/bitbucket)

Use a **read-only** token. nOps checks each connection daily, and the step tells you exactly what is missing:

| Message | Fix |
| - | - |
| GitHub is connected without an organization slug | Edit the GitHub connection and add the slug from `github.com/your-org`. |
| The GitHub token can't read pull requests or commits | Grant **Pull requests: read** and **Contents: read**. |
| GitLab is connected without a usable token or top-level group | Re-enter the token and the top-level group. |
| The GitLab token can't read merge requests | Give the token the `read_api` scope. |
| Bitbucket is connected without a usable token or workspace | Re-enter the token and the workspace. |
| The Bitbucket token can't read pull requests | Add the `read:pullrequest:bitbucket` and `read:repository:bitbucket` scopes. |

Self-hosted servers (GitHub Enterprise Server, GitLab self-managed, Bitbucket Data Center) and Azure DevOps are not supported yet.

### 3. Match people to their code host accounts

**Unlocks:** each person's PRs and their AI cost per PR.

nOps matches each person who has AI spend to their code host login, mostly from the email on their commits. The step reads, for example, "18 of 20 people with AI spend are matched to their pull requests". It is done at 80% or more.

If people are missing, the usual cause is that they commit with a personal or no-reply email. Either:

* Ask them to commit with their work email (on GitHub, or make the work email their public profile email), or
* Link their login by hand in **Manage teams**. See [Link a login to a person](https://help.nops.io/ai-roi/teams.md#link-a-login-to-a-person).

### 4. Group people into teams

**Unlocks:** the Engineering Overview, team scores, team comparisons and the team focus on the Executive Summary.

Create your engineering teams in **Manage teams**. Until you do, AI ROI uses the groups from your AI seat tracking project's [Wallets](https://help.nops.io/ai/wallets.md), if you have one. See [Teams and people](https://help.nops.io/ai-roi/teams.md).

### 5. Connect Linear or Jira

**Unlocks:** a work type for PRs whose title or branch doesn't name one.

A PR that names a ticket in its branch (like `ENG-123`) takes its work type from that ticket's type and labels, and its project from the Linear project or Jira epic. nOps reads only ticket types, labels, parents and project names, never ticket titles or descriptions.

Connect Linear or Jira in **Settings → Integrations → Notifications**. See [Issue creation from recommendations](https://help.nops.io/platform/issue-tracker-notifications.md); the same connection serves both.

### 6. Install the AI ROI Agent

**Unlocks:** exact AI cost per PR, and a work type for AI spend that never reached a merged PR.

Each developer runs one command and signs in with their nOps login:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
npx @nops-io/clara
```

Before anyone installs, an admin sets which organizations the agent may record in. See [Install the agent](https://help.nops.io/ai-roi/agent/install.md) and [Manage the agent](https://help.nops.io/ai-roi/agent/admin.md).

## How long until data shows

| Data | First arrival |
| - | - |
| Cursor spend | Within a day of connecting. The current day is final once it is over. |
| Claude Code spend | Within a day. Claude adjusts the last three days, so the newest days can change. |
| Pull requests | After the next daily refresh of your code host. |
| Agent sessions | About a minute after a session or commit on the developer's machine. |

Cost per PR only counts days whose spend is final. Until then, recent PRs show **Arriving**. See [Settled spend](https://help.nops.io/ai-roi/how-the-numbers-work.md#settled-spend).

## Next steps

* [Executive Summary](https://help.nops.io/ai-roi/executive-summary.md)
* [Teams and people](https://help.nops.io/ai-roi/teams.md)
* [AI ROI Agent](https://help.nops.io/ai-roi/agent/overview.md)


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