Infinium Codex Connector

Bridge between Codex CLI hooks and Infinium agent tracing. Automatically captures Codex CLI sessions — tool calls, prompts, token usage — and sends structured traces to the Infinium platform for Maestro analysis.

Quick Start

Navigate to your project, install, and set up:

cd /path/to/your/project
pip install infinium-codex-connector
infinium-codex init
infinium-codex test       # verify credentials + network

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

If infinium-codex is not on your PATH, use python -m infinium_codex_connector as a drop-in replacement.

Requirements

• Python 3.9+
• Codex CLI with hooks enabled (codex features enable codex_hooks)
• An Infinium agent ID and secret

Windows: requires Codex CLI v0.119.0 or newer — earlier versions had hooks gated off on Windows (openai/codex#17268, merged 2026-04-09).

How It Works

After infinium-codex init, everything is automatic. You use Codex CLI exactly as before — the connector works silently in the background via hooks.

Codex CLI ──command hook──> python -m infinium_codex_connector.hook
                                 │
                                 ├─ append event to session JSONL file
                                 │
                                 └─ on Stop:
                                      spawn detached background worker
                                      → replay events → aggregate → send trace
                                                                       │
                                                                       ▼
                                                               Infinium API
                                                           POST /agents/{id}/trace

1. Codex CLI fires a command hook for each event (tool call, prompt, etc.)
2. The hook script appends the event to a session JSONL file on disk — returns instantly so Codex is never blocked.
3. On turn completion (Stop), a detached background worker replays all events, aggregates them into a structured trace, and sends it to Infinium via the Python SDK.
4. Maestro interprets the trace (grading accuracy, efficiency, prompt adherence).

CLI Reference

infinium-codex init

Interactive setup wizard. Configures credentials and Codex hooks.

Options:
  --agent-id TEXT        Agent ID (skip prompt)
  --agent-secret TEXT    Agent Secret (skip prompt)
  --base-url TEXT        API base URL
  --no-interactive       Use flags only, no prompts (for CI/scripting)

infinium-codex test

Send a minimal test trace to verify credentials + network.

Options:
  -v, --verbose    Show the full trace payload before sending

infinium-codex status

Show current configuration: tracing state, credentials, config source, hook locations, pending retries.

infinium-codex pause / infinium-codex resume

Temporarily stop or restart tracing. Hooks stay installed — events are silently skipped while paused.

infinium-codex history

View recently sent traces.

Options:
  -n, --limit N    Number of entries (default: 10)
  --json           Output raw JSON lines
  --clear          Delete all history

infinium-codex errors

View the connector error log (network failures, bad payloads, keyring issues).

infinium-codex retry

Resend traces that failed due to network issues.

Options:
  --dry-run    Show what would be retried without sending

infinium-codex update-credentials

Update your Agent ID or Secret.

infinium-codex uninstall

Remove the connector completely — hooks, config file, and keyring secret.

Options:
  -y, --yes    Skip confirmation prompt

infinium-codex cleanup

Remove stale session files (housekeeping).

infinium-codex start

Start HTTP server mode (alternative to command hooks, requires pip install infinium-codex-connector[server]).

Per-Project Configuration

Each project traces to its own Infinium agent:

cd /path/to/project-a
infinium-codex init    # Agent A credentials

cd /path/to/project-b
infinium-codex init    # Agent B credentials

Config resolution order:

1. Project config (.infinium/config.json at or above the working directory)
2. Environment variables (INFINIUM_AGENT_ID, INFINIUM_AGENT_SECRET — override for CI/Docker)

Add .infinium/ to your .gitignore.

Credential Storage

• Agent ID and API URL are stored in the project config file (.infinium/config.json)
• Agent Secret is stored in your OS keyring:
  • Windows: Credential Manager
  • macOS: Keychain
  • Linux: Secret Service (GNOME Keyring / KWallet)
• Environment variables (INFINIUM_AGENT_ID, INFINIUM_AGENT_SECRET) override stored values — useful for CI/Docker

What Gets Traced

Field	Source
name	First user prompt, truncated (e.g. "Fix the login validation")
description	First user prompt (200-char preview)
input_summary	First user prompt, up to 3000 chars — what Maestro reads as the request
output_summary	Last assistant response, up to 8000 chars — what Maestro reads as the deliverable
duration	Total session duration in seconds
steps	Ordered list: user prompts, tool calls (input_preview up to 200 chars, output_preview up to 1500 chars)
errors	Tool failures (Codex tool_response: false)
environment	Model, session source, working directory, permission mode
llm_usage	Prompt / completion / cached input tokens (from Codex transcript)

Captured Events

Event	What It Captures
SessionStart	Model, source (startup/resume), working directory
UserPromptSubmit	User prompt text (200-char step preview; the first prompt is kept up to 3000 chars as input_summary)
PreToolUse / PostToolUse	Tool name (Bash), command (up to 200 chars), success/failure (Codex sends a boolean; structured output, if ever provided, is kept up to 1500 chars)
Stop	Assistant's final response (1500-char step preview; the last response is kept up to 8000 chars as output_summary) — triggers trace flush

Configuration

Environment variables (all optional — init handles the common case):

# Credentials (override config file + keyring)
INFINIUM_AGENT_ID=...
INFINIUM_AGENT_SECRET=...
INFINIUM_BASE_URL=...

# Connector behavior
CONNECTOR_QUIET=false              # Suppress output
CONNECTOR_FLUSH_ON_STOP=true       # Send trace after each turn
CONNECTOR_FLUSH_ON_SESSION_END=true
CONNECTOR_SESSION_TTL=600          # Stale session cleanup threshold (seconds)
CONNECTOR_SESSION_DIR=...          # Override temp directory for session files

# Payload caps (characters) — defaults match what Maestro's trace judge renders
CONNECTOR_MAX_INPUT_PREVIEW=200    # Per-step input_preview
CONNECTOR_MAX_OUTPUT_PREVIEW=1500  # Per-step output_preview (tool results, turn responses)
CONNECTOR_MAX_INPUT_SUMMARY=3000   # Top-level input_summary (first user prompt)
CONNECTOR_MAX_OUTPUT_SUMMARY=8000  # Top-level output_summary (last assistant response)

Documentation

Full documentation: i42m.ai/docs/codex

License

MIT