Installation

pip install infinium-codex-connector

Requirements: Python 3.9 or higher, OpenAI Codex CLI installed.

The connector depends on infinium-o2 (the Infinium Python SDK), click (CLI framework), and keyring (secure credential storage). These are installed automatically.

Enable Codex Hooks

Codex’s hook system is feature-flagged. Enable it once:

codex features enable codex_hooks

Alternatively, edit ~/.codex/config.toml:

[features]
codex_hooks = true

Windows users: make sure your Codex CLI is v0.119.0 or newer. Older versions don’t fire hooks on Windows. Check with codex --version.

Setup

Navigate to your project and run the setup wizard:

cd /path/to/your/project
infinium-codex init

The wizard asks for two things:

  1. Agent ID — Your Infinium agent ID (from the platform)
  2. Agent Secret — Your agent secret (stored securely in the OS keyring)
  Infinium Codex Connector
  ========================

  Enter your Infinium Agent ID: a1b2c3d4-...
  Enter your Infinium Agent Secret: ****

  Config saved to:    .infinium/config.json
  Secret stored in:   OS keyring (secure)
  Hooks written to:   .codex/hooks.json
  Codex hooks feature enabled.

  Setup complete! Codex CLI will now send traces to Infinium.

That’s it. Now just use Codex CLI as you normally would — every session in this project is automatically traced to Infinium.

If infinium-codex is not found, use python -m infinium_codex_connector instead. You may need to add Python’s Scripts directory to your system PATH.

Verify Your Connection

After setup, send a test trace to confirm everything works:

infinium-codex test

You should see:

  Agent ID:  a1b2c3d4-...
  API URL:   https://platform.i42m.ai/api/v1
  Sending test trace...

  Connection verified! Trace ID: abc123...
  Your setup is working correctly.

If the test fails, check the Troubleshooting guide.

How Tracing Works

Once set up, tracing is fully automatic. There’s nothing extra to run or remember — just use Codex CLI as normal.

  1. You open Codex CLI in your project directory
  2. Codex fires command hooks on each event (prompts, shell commands, stop)
  3. The connector appends events to a temporary session JSONL file and returns immediately — Codex is never blocked
  4. On Stop, a detached background worker aggregates events into a structured trace
  5. The trace is sent to your Infinium agent via the API, along with token usage read from Codex’s transcript
  6. Maestro analyzes the trace and produces a quality score

You’ll see your traces appear in the Infinium platform within seconds.

Check Your Status

At any time, verify your configuration:

infinium-codex status
  Infinium Codex Connector Status
  --------------------------------
  Tracing:      active
  Agent ID:     a1b2c3d4-...
  Secret:       configured
  API URL:      https://platform.i42m.ai/api/v1
  Granularity:  both (per-turn + per-session)
  Config from:  project (.infinium/config.json)
  Hooks:        .codex/hooks.json

View Trace History

See what traces have been sent:

infinium-codex history
  Last 3 trace(s):

  Time                 Steps Tools Errors Status   Trace ID
  -------------------- ----- ----- ------ -------- ------------
  2026-04-18 14:32         8     5      0 sent     a3f2c891...
  2026-04-18 13:10         3     2      0 sent     b7d4e012...
  2026-04-18 11:45        12     8      1 sent     c9a1f234...

Next Steps