The Infinium Codex CLI Connector automatically captures your OpenAI Codex CLI sessions and sends structured traces to the Infinium platform, where Maestro — our behavioral intelligence engine — analyzes and scores agent performance.

No code changes required. Install the connector, run the setup wizard, enable the Codex hooks feature, and every Codex CLI session is traced automatically.

Core Concept

Codex CLI does the work. The connector captures what happened. Maestro evaluates how well it went.

The connector hooks into Codex’s native hook system and records facts — prompts, shell commands, errors, durations, token usage — then sends them to Infinium as structured traces. Maestro interprets the trace and scores performance without the agent ever evaluating itself.

How It Works

Codex CLI Session
    │
    ├── SessionStart        ← Hook fires
    ├── UserPromptSubmit    ← Captures prompt
    ├── PreToolUse          ← Tracks Bash command about to run
    ├── PostToolUse         ← Captures success/failure
    ├── Stop                ← Turn complete → sends trace
    │
    ▼
Infinium Connector
    │
    ├── Aggregates events into structured turns
    ├── Reads the Codex transcript for token usage
    ├── Builds: TaskData (steps, errors, tools, durations, llm_usage)
    ├── Sends: POST /agents/{id}/trace
    │
    ▼
Infinium Platform
    │
    └── Maestro evaluates trace quality and scores performance

Features

  • Zero-Config Tracing — Hooks install automatically, no code changes needed
  • Per-Turn Traces — Each prompt-response cycle sends a trace on Stop
  • Bash Command Tracking — Captures every shell command with success/failure signal
  • Token Usage — Reads Codex’s session transcript for prompt/completion/cached token counts
  • Secure Credentials — Agent secret stored in OS keyring (Windows Credential Manager, macOS Keychain, Linux Secret Service)
  • Per-Project Agents — Different projects can trace to different Infinium agents
  • Pause & Resume — Temporarily disable tracing without reconfiguring
  • Failed Trace Retry — Automatic recovery from network failures
  • Local History — View recently sent traces without leaving the terminal
  • Non-Blocking — Traces are built and sent in a detached background worker so Codex CLI is never stalled waiting for network I/O
GuideDescription
Getting StartedInstall, enable codex_hooks, setup wizard, verify connection
ConfigurationProject scope, credentials, environment variables
CommandsFull CLI reference for all infinium-codex commands

Reference

ReferenceDescription
Traced EventsWhat data is captured and how it maps to traces
TroubleshootingCommon issues and how to resolve them

Package Info

  • PyPI: infinium-codex-connector
  • CLI: infinium-codex
  • Python: >= 3.9
  • Dependencies: infinium-o2, click, keyring
  • License: MIT

Compatibility

  • Codex CLI: any modern release with codex_hooks available
  • Windows: requires Codex CLI v0.119.0 or newer — earlier versions gated hooks off on Windows (openai/codex#17268, merged April 2026)