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

# AI Coding Tools

> Send usage telemetry from Claude Code, GitHub Copilot, OpenAI Codex, and LiteLLM into Navigara to measure AI adoption, cost, and impact.

Navigara measures how your organization actually uses AI coding assistants (cost, tokens, models, and which developers are active) by ingesting **usage telemetry** from the tools themselves. Every AI tool emits [OpenTelemetry](https://opentelemetry.io) (OTLP), and Navigara exposes an OTLP endpoint that turns that stream into per-developer, per-model spend on the [Tool Spend](https://app.navigara.com/tool-spend) dashboard.

> [!NOTE]
>
> **Any plan or license works. We support them all.** Ingestion is pure OpenTelemetry, independent of how you pay for the tool. There's nothing to buy or upgrade to be measured.

> [!NOTE]
>
> **You control what leaves the workstation.** Navigara collects **usage metadata**: session and user IDs, model, cost, token counts, durations, tool names and details (shell commands, file paths), repository, and commit SHAs. The settings below also send **prompt text**, which names work items; turn off **Collect prompt text** in **Settings → General** and drop the prompt flag if you don't want it. Assistant responses, tool output, and raw API bodies stay off. Prompts and tool inputs (for example, a file edit) can contain source code; set `OTEL_LOG_USER_PROMPTS` and `OTEL_LOG_TOOL_DETAILS` to `0` if that must not leave the workstation.

## How it works

```mermaid theme={null}
graph LR
    Tool["AI tool<br/>(Claude Code / Copilot / Codex / LiteLLM)"] -->|OTLP/HTTP| OTLP["Navigara OTLP endpoint<br/>/api/otlp"]
    OTLP -->|attributed by email| Spend["Tool Spend dashboard"]
```

1. **You mint an ingest token**: a write-only API token scoped to your organization.
2. **You configure the tool** to export OTLP metrics (and logs, for identity) to Navigara's endpoint with that token as a bearer header.
3. **Navigara attributes usage to contributors** by email and materializes it into cost and token metrics. Usage shows up in **Tool Spend** within a few minutes.

## Set up a connection (recommended)

The fastest path is the built-in wizard: it mints the token and generates the exact config for you:

**1. Open the AI tools group**

Go to **Settings → Connections**. Alongside **Source control** and **Task tracking**, there is an **AI tools** group, "Usage telemetry from AI coding assistants".

**2. Pick a tool and name the connection**

Choose Claude Code, GitHub Copilot, OpenAI Codex, or LiteLLM, then give the connection a name (e.g. by team, region, or backend). You can add more than one connection per tool.

**3. Generate the token and config**

Click **Generate token & config**. Navigara mints a write-only ingest token and drops it into a ready-to-copy config block. The token is shown once, so copy it now. (Use **Preview config** to see the snippet with a `<YOUR_INGEST_TOKEN>` placeholder without minting anything.)

**4. Roll the config out**

Apply the config to your workstations, fleet, or proxy using the per-tool instructions below. Usage appears in **Tool Spend** within a few minutes.

## The ingest endpoint and token

If you'd rather wire it up by hand, everything the wizard produces comes down to two values.

**Endpoint**: Navigara serves OTLP/HTTP at `/api/otlp`. OTLP clients append the signal path (`/v1/metrics`, `/v1/logs`) themselves.

| Deployment | OTLP endpoint |
| - | - |
| Cloud SaaS | `https://app.navigara.com/api/otlp` |
| Full on-premises | `https://<your-navigara-host>/api/otlp` |
| On-prem collector | `http://<collector-host>:<OPS_PORT>/otlp` |

**Ingest token**: create one at **Settings → API Tokens → Create API Token**. Any token works, but a dedicated **Ingest only** token (write-only, cannot read your data) is recommended; the AI-tools wizard mints exactly this. Pass it on every request as:

```
Authorization: Bearer <YOUR_INGEST_TOKEN>
```

> [!NOTE]
>
> **Identity is matched by email.** Navigara joins usage to a contributor using the email the tool reports. Where a tool can't emit an email natively, the snippets below set `enduser.id` (usually from the developer's git email); make sure it matches the email Navigara already knows the contributor by. Usage that can't be matched still counts toward org totals; it just shows as unattributed until an email resolves.

***

## Claude Code

Claude Code has native OpenTelemetry support. It emits cost and token **metrics**, and, on Claude.ai (Team / Enterprise) sign-in, the developer's email, account, and organization IDs on **logs**, which is how usage is attributed. Requires Claude Code v2.1.269 or later.

These are the settings Navigara needs. They match what the Navigara CLI (`curl -fsSL https://navigara.com/cli | sh`) writes:

```json theme={null}
{
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_LOGS_EXPORTER": "otlp",
    "OTEL_TRACES_EXPORTER": "none",
    "OTEL_METRICS_INCLUDE_REPOSITORY": "true",
    "OTEL_METRICS_INCLUDE_SESSION_ID": "true",
    "OTEL_LOG_TOOL_DETAILS": "1",
    "OTEL_LOG_USER_PROMPTS": "1",
    "OTEL_LOG_ASSISTANT_RESPONSES": "0",
    "OTEL_LOG_TOOL_CONTENT": "0",
    "OTEL_LOG_RAW_API_BODIES": "0",
    "CLAUDE_CODE_ENHANCED_TELEMETRY_BETA": "0",
    "OTEL_EXPORTER_OTLP_PROTOCOL": "http/protobuf",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://app.navigara.com/api/otlp",
    "OTEL_EXPORTER_OTLP_HEADERS": "Authorization=Bearer <YOUR_INGEST_TOKEN>"
  }
}
```

| Setting | Why Navigara needs it |
| - | - |
| `OTEL_METRICS_INCLUDE_REPOSITORY` | Adds the repository URL, so spend is attributed to a repository. |
| `OTEL_METRICS_INCLUDE_SESSION_ID` | Adds the session ID to metrics, so cost and tokens join the right session. |
| `OTEL_LOG_TOOL_DETAILS` | Adds tool inputs (shell commands, file paths, edit text) and the commit SHA, so commits link to spend. |
| `OTEL_LOG_USER_PROMPTS` | Sends prompt text, which names work items. Set it to `0` if you turn off **Collect prompt text** in **Settings → General**. |
| `OTEL_LOG_ASSISTANT_RESPONSES`, `OTEL_LOG_TOOL_CONTENT`, `OTEL_LOG_RAW_API_BODIES`, `CLAUDE_CODE_ENHANCED_TELEMETRY_BETA` | Kept off: no assistant responses, tool output, or raw API bodies leave the workstation. Set them to `0` explicitly: `OTEL_LOG_ASSISTANT_RESPONSES` follows `OTEL_LOG_USER_PROMPTS` when unset. |
| `OTEL_TRACES_EXPORTER` | Kept off: Navigara does not use Claude Code traces. |

### Where to put the settings

> [tab] Claude.ai organization (recommended)
>
> If your developers sign in to Claude Code with a Claude for Teams or Claude for Enterprise account, manage the settings once in Claude.ai. Claude Code loads them for every member of the organization, and developers can't override them.
>
> **1. Open the Claude Code admin settings**
>
> Sign in to Claude.ai as an organization **Owner** or **Primary Owner**. Go to **Organization settings → Claude Code → Managed settings** ([claude.ai/admin-settings/claude-code](https://claude.ai/admin-settings/claude-code)).
>
> **2. Add the settings**
>
> Paste the JSON above, with your ingest token in `OTEL_EXPORTER_OTLP_HEADERS`. If you already have managed settings, merge the `env` keys into your existing `env` object.
>
> **3. Save**
>
> Developers get the settings the next time they start Claude Code. Usage appears in **Tool Spend** within a few minutes.
>
> Claude.ai sign-in emits each developer's email natively, so no per-developer `enduser.id` is needed.

> [tab] MDM file
>
> Ship the JSON above via MDM so developers can't override it:
>
> * macOS: `/Library/Application Support/ClaudeCode/managed-settings.json`
> * Linux: `/etc/claude-code/managed-settings.json`
> * Windows: `C:\Program Files\ClaudeCode\managed-settings.json`

> [tab] Shell snippet (per developer)
>
> Add to the shell profile or a `claude` launcher wrapper. Each `env` key above becomes an `export`:
>
> ```bash theme={null}
> export CLAUDE_CODE_ENABLE_TELEMETRY="1"
> export OTEL_METRICS_EXPORTER="otlp"
> export OTEL_LOGS_EXPORTER="otlp"
> export OTEL_TRACES_EXPORTER="none"
> export OTEL_METRICS_INCLUDE_REPOSITORY="true"
> export OTEL_METRICS_INCLUDE_SESSION_ID="true"
> export OTEL_LOG_TOOL_DETAILS="1"
> export OTEL_LOG_USER_PROMPTS="1"
> export OTEL_LOG_ASSISTANT_RESPONSES="0"
> export OTEL_LOG_TOOL_CONTENT="0"
> export OTEL_LOG_RAW_API_BODIES="0"
> export CLAUDE_CODE_ENHANCED_TELEMETRY_BETA="0"
> export OTEL_EXPORTER_OTLP_PROTOCOL="http/protobuf"
> export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp"
> export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <YOUR_INGEST_TOKEN>"
> export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)"
> ```

### Attribution by auth model

* **Claude.ai sign-in (Team / Enterprise)**: Claude Code emits the user's email and account IDs natively. Nothing else to add.
* **API key / Bedrock / Vertex**: only an anonymous installation ID is emitted, so set `enduser.id` to the developer's email. Shared settings (Claude.ai or MDM) are identical for every developer, so set it per developer in the shell profile. The `env` of `~/.claude/settings.json` also works, but JSON does not run commands, so write the email literally there (`"OTEL_RESOURCE_ATTRIBUTES": "enduser.id=dev@example.com"`). In the shell profile:

  ```bash theme={null}
  export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)"
  ```

***

## GitHub Copilot

Copilot CLI telemetry is off by default. Copilot configures OTLP through **environment variables only** (its `~/.copilot/config.json` has no telemetry settings), so for a fleet-wide rollout drop these into a shared profile (e.g. `/etc/profile.d/`) or a `copilot` launcher wrapper.

```bash theme={null}
export COPILOT_OTEL_ENABLED="true"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp"
export OTEL_EXPORTER_OTLP_PROTOCOL="http/json"
export OTEL_EXPORTER_OTLP_HEADERS="Authorization=Bearer <YOUR_INGEST_TOKEN>"

# Copilot emits no developer identity on any stream; enduser.id is the only
# attribution lever, matched to a contributor by email. Defaults to your git
# email; override if that isn't the email Navigara knows you by.
export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)"
```

> [!NOTE]
>
> Copilot CLI does not ship protobuf export yet, so the protocol is pinned to `http/json`, the encoding Navigara accepts for Copilot.

***

## OpenAI Codex

Codex configures OTLP through `~/.codex/config.toml`, not environment variables. Telemetry is off by default; this turns on its OTLP exporters and points them at Navigara. Usage rides **metrics**; identity rides **logs**. Add these tables at the end of the file, after any top-level keys: a key below a table header belongs to that table. TOML does not allow the same table twice, so if the file already has an `[otel]` table, add `log_user_prompt = true` to that table instead, and replace any exporter table it already has. The `log_user_prompt` line sends prompt text; drop it to keep prompts on the workstation.

```toml theme={null}
# ~/.codex/config.toml
[otel]
log_user_prompt = true

[otel.metrics_exporter.otlp-http]
endpoint = "https://app.navigara.com/api/otlp/v1/metrics"
protocol = "binary"
headers = { Authorization = "Bearer <YOUR_INGEST_TOKEN>" }

[otel.exporter.otlp-http]
endpoint = "https://app.navigara.com/api/otlp/v1/logs"
protocol = "binary"
headers = { Authorization = "Bearer <YOUR_INGEST_TOKEN>" }
```

Codex token-usage metrics carry no developer identity, so set `enduser.id` per workstation. It's a per-developer value, so it belongs in the shell profile, not the shared config file:

```bash theme={null}
export OTEL_RESOURCE_ATTRIBUTES="enduser.id=$(git config user.email)"
```

> [!NOTE]
>
> Codex sets `service.name` per surface (`codex_exec`, `codex_tui`); Navigara collapses these to one `codex` source automatically.

***

## LiteLLM

Run one LiteLLM proxy in front of your providers and Navigara captures **proxy-wide** token and cost usage for every tool that routes through it. Requires **LiteLLM 1.89 or newer**; earlier proxies read `OTEL_ENDPOINT` instead and don't append the `/v1/metrics` path, so usage won't arrive.

**1. Enable the OTel callback in config.yaml**

```yaml theme={null}
litellm_settings:
  callbacks: ["otel"]
```

**2. Set these on the proxy deployment**

```bash theme={null}
# The otel callback ships spans by default; metrics (token + cost) are opt-in.
export LITELLM_OTEL_INTEGRATION_ENABLE_METRICS="true"
export OTEL_EXPORTER="otlp_http"
export OTEL_EXPORTER_OTLP_ENDPOINT="https://app.navigara.com/api/otlp"
export OTEL_HEADERS="Authorization=Bearer <YOUR_INGEST_TOKEN>"
```

**3. Attribute usage to developers**

Pick whichever matches how developers authenticate to the proxy. All three land the email in `metadata.user_api_key_*`, which Navigara resolves to a contributor.

> [tab] Per-user virtual keys
>
> Mint a virtual key per developer (`/key/generate` or `/user/new`) and set that user's `user_email` to their git/commit email. LiteLLM exports it as `metadata.user_api_key_user_email`.

> [tab] JWT / OIDC SSO
>
> Developers present their SSO token; LiteLLM extracts the email claim. Add to the same `config.yaml`, pointing at whichever claim holds the email:
>
> ```yaml theme={null}
> general_settings:
>   enable_jwt_auth: true
>   litellm_jwtauth:
>     user_email_jwt_field: "email"
> ```

> [tab] User request parameter
>
> Each client sets the OpenAI-compatible `user` field to the developer's email. LiteLLM exports it as `metadata.user_api_key_end_user_id`. Cheapest option: nothing to manage in LiteLLM, but every calling tool must set `user`:
>
> ```bash theme={null}
> curl $LITELLM_PROXY/v1/chat/completions \
>   -H "Authorization: Bearer $YOUR_LITELLM_KEY" \
>   -d '{
>     "model": "gpt-4o",
>     "messages": [{"role": "user", "content": "..."}],
>     "user": "dev@yourcompany.com"
>   }'
> ```

***

## Troubleshooting

* **Nothing in Tool Spend after a few minutes**: confirm the endpoint ends in `/api/otlp` (no `/v1/...` suffix except where a tool takes a full per-signal path, like Codex), and that the `Authorization` header carries a valid ingest token. Restart the tool/proxy so it re-reads its config.
* **Usage shows up as unattributed**: the tool isn't emitting a resolvable email. For Copilot and Codex, set `OTEL_RESOURCE_ATTRIBUTES="enduser.id=..."`; for Claude Code under API-key auth, add the `enduser.id` launcher; for LiteLLM, wire one of the three identity models. The email must match the contributor's known email.
* **Attribution resolves a day or two late**: Navigara re-attributes a trailing window automatically, so late-arriving emails backfill without action.
* **LiteLLM sends traces but no cost/tokens**: set `LITELLM_OTEL_INTEGRATION_ENABLE_METRICS=true` and upgrade to LiteLLM ≥ 1.89.
* **Copilot export fails on protobuf**: keep `OTEL_EXPORTER_OTLP_PROTOCOL=http/json`; the CLI doesn't ship protobuf export yet.


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