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

# Codex

> Set up AgentLogs with OpenAI Codex for automatic transcript capture

# Codex Integration

Codex is OpenAI's CLI for coding with GPT models. AgentLogs provides automatic transcript capture through Codex hooks.

## Features

* **Automatic capture** - Transcripts are uploaded after each agent response
* **Native hooks** - Uses Codex's built-in hook system instead of a background watcher
* **Git commit tracking** - Uses `PreToolUse` and `PostToolUse` to link Codex-made commits back to the session in AgentLogs

## Installation

### 1. Authentication

Run the following command in the terminal:

```bash theme={null}
npx agentlogs login agentlogs.ai
```

### 2. Install AgentLogs Hooks

Run:

```bash theme={null}
npx agentlogs codex install
```

This does two things:

* Adds `codex_hooks = true` under `[features]` in `~/.codex/config.toml`
* Writes AgentLogs `SessionStart`, `PreToolUse`, `PostToolUse`, and `Stop` entries to `~/.codex/hooks.json`

Codex reads `hooks.json` when `codex_hooks` is enabled in `~/.codex/config.toml`.

### 3. Manual Configuration

<Accordion title="Manual configuration">
  If you prefer to configure Codex yourself, first enable hook support in `~/.codex/config.toml`:

  ```toml theme={null}
  [features]
  codex_hooks = true
  ```

  Then create `~/.codex/hooks.json` with the following contents:

  ```json theme={null}
  {
    "hooks": {
      "SessionStart": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "bash -c 'if [ -n \"$AGENTLOGS_CLI_PATH\" ]; then exec $AGENTLOGS_CLI_PATH codex hook; else exec npx -y agentlogs@latest codex hook; fi'",
              "timeoutSec": 30
            }
          ]
        }
      ],
      "PreToolUse": [
        {
          "matcher": "Bash",
          "hooks": [
            {
              "type": "command",
              "command": "bash -c 'if [ -n \"$AGENTLOGS_CLI_PATH\" ]; then exec $AGENTLOGS_CLI_PATH codex hook; else exec npx -y agentlogs@latest codex hook; fi'",
              "timeoutSec": 30
            }
          ]
        }
      ],
      "PostToolUse": [
        {
          "matcher": "Bash",
          "hooks": [
            {
              "type": "command",
              "command": "bash -c 'if [ -n \"$AGENTLOGS_CLI_PATH\" ]; then exec $AGENTLOGS_CLI_PATH codex hook; else exec npx -y agentlogs@latest codex hook; fi'",
              "timeoutSec": 30
            }
          ]
        }
      ],
      "Stop": [
        {
          "hooks": [
            {
              "type": "command",
              "command": "bash -c 'if [ -n \"$AGENTLOGS_CLI_PATH\" ]; then exec $AGENTLOGS_CLI_PATH codex hook; else exec npx -y agentlogs@latest codex hook; fi'",
              "timeoutSec": 30
            }
          ]
        }
      ]
    }
  }
  ```

  If you're testing a local AgentLogs checkout, export `AGENTLOGS_CLI_PATH='bun /absolute/path/to/packages/cli/src/index.ts'` before starting Codex to force hooks to use your local CLI instead of npm.

  You can also place the same `hooks.json` file in a project-local `.codex/` directory if you want the integration enabled only for one repository.
</Accordion>

## How It Works

* **SessionStart** confirms the hook wiring and gives AgentLogs a native Codex integration point.
* **PreToolUse** uploads the current transcript before `git commit` so the session already exists in AgentLogs.
* **PostToolUse** records successful git commits against that session in AgentLogs.
* **Stop** uploads the current transcript after each completed agent response.

Uploads are deduplicated server-side by session ID, so repeated Stop events update the same transcript instead of creating duplicates.

Codex does not currently support hook-driven command rewriting for `PreToolUse`, so AgentLogs can track commits in the dashboard but cannot automatically append a transcript URL to the git commit message body.

## Manual Upload

You can manually upload transcripts using the CLI:

```bash theme={null}
# Interactive picker to browse and upload any transcript
npx agentlogs upload

# Filter to only Codex transcripts
npx agentlogs upload --source codex

# Upload a specific transcript file
npx agentlogs codex upload ~/.codex/sessions/2025/01/25/session-abc123.jsonl
```

The interactive `upload` command discovers transcripts from all agents and lets you pick one to upload.