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

# Codex observability

> Trace every Codex session with a plugin: each prompt becomes a trace with its LLM calls and tool calls, grouped as a Tracevell session.

## Overview

The Codex plugin traces every local [OpenAI Codex CLI](https://github.com/openai/codex) session: each turn becomes a full trace with its LLM calls and tool executions, sent to Tracevell.

## Install

**1. Run the installer**

```bash theme={null}
npx lmnr-cli@latest plugin add codex
```

The CLI logs you in (browser device flow), lets you pick the Tracevell project that should receive your Codex traces, mints a project API key named after the plugin and your machine, writes it to `~/.config/lmnr/codex-plugin.json`, and installs the plugin through Codex's native plugin marketplace.

> [!TIP]
>
> Pick a dedicated project for coding-agent traces so they don't mix with your application's traces. The setup is global and directory-independent: it never touches `.lmnr/project.json` or your `.env`.

**2. Restart Codex**

Codex loads plugins at startup, so restart it to activate the plugin.

**3. Use Codex as usual**

Every turn becomes a trace in the project you picked. Open the Tracevell dashboard to watch them land in realtime.

> [!NOTE]
>
> **Self-hosting Tracevell?** The same command works against your instance: pass your frontend URL (the auth issuer) and your API URL, including the API port:
>
> ```bash theme={null}
> npx lmnr-cli@latest plugin add codex \
>   --frontend-url https://tracevell.example.com \
>   --base-url https://api.tracevell.example.com
> ```

### Manual install

If you'd rather not use `lmnr-cli`, install the plugin with Codex's plugin commands and create the config file yourself:

```bash theme={null}
codex plugin marketplace add lmnr-ai/lmnr-codex-plugin
codex plugin add lmnr@lmnr
```

Then create `~/.config/lmnr/codex-plugin.json` with a project API key. Get one from the Tracevell dashboard under **Settings → Project API Keys** (create a dedicated key so it's clear it belongs to the plugin):

```json ~/.config/lmnr/codex-plugin.json theme={null}
{ "projectApiKey": "your-project-api-key", "baseUrl": "https://api.lmnr.ai" }
```

`projectApiKey` is required. `baseUrl` is optional and defaults to `https://api.lmnr.ai`; self-hosters set it to their instance's API URL (for example `http://localhost:8000`).

## Configure the Codex plugin

The plugin reads its config from `~/.config/lmnr/codex-plugin.json`, written by `lmnr-cli plugin add codex`:

```json theme={null}
{ "projectApiKey": "...", "baseUrl": "https://api.lmnr.ai" }
```

The environment variables `LMNR_PROJECT_API_KEY` and `LMNR_BASE_URL` override the file when set, which is handy for CI or a shell you already have configured. Traces are attributed to the identity from `lmnr-cli login` when present; set `LMNR_USER_ID` to override the user id attached to traces.

## Related integrations

> [card] [Claude Code](https://tracevell.com/docs/integrations/claude-code.md)
>
> Trace Claude Code sessions with a one-command plugin.

> [card] [OpenCode](https://tracevell.com/docs/integrations/opencode.md)
>
> Trace OpenCode coding agent sessions.

> [card] [Pi](https://tracevell.com/docs/integrations/pi.md)
>
> Trace Pi coding agent sessions with a one-command extension.

> [card] [OpenAI](https://tracevell.com/docs/integrations/openai.md)
>
> Trace the OpenAI SDK directly in TypeScript and Python.

> [card] [OpenAI Agents SDK](https://tracevell.com/docs/integrations/openai-agents-sdk.md)
>
> Trace agent runs, handoffs, and tool calls.

> [card] [All integrations](https://tracevell.com/docs/integrations.md)
>
> Browse every provider, framework, coding agent, and browser integration Tracevell supports.


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