Skip to main content

​
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: 
npx agentlogs login agentlogs.ai

​
2. Install AgentLogs Hooks

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

If you prefer to configure Codex yourself, first enable hook support in ~/.codex/config.toml:
[features]
codex_hooks = true
Then create ~/.codex/hooks.json with the following contents:
{
  "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.

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