Installation

pip install infinium-claude-code-connector

Requirements: Python 3.9 or higher.

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

Setup

Navigate to your project and run the setup wizard:

cd /path/to/your/project
infinium-claude 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 Claude Code 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:   .claude/settings.json

  Setup complete! Claude Code will now send traces to Infinium.

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

If infinium-claude is not found, use python -m infinium_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-claude 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 Claude Code as normal.

  1. You open Claude Code in your project directory
  2. Hooks fire on each event (prompts, tool calls, responses)
  3. Events accumulate in a temporary session file
  4. On turn completion, the connector aggregates events into a structured trace
  5. The trace is sent to your Infinium agent via the API
  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-claude status
  Infinium Connector Status
  -------------------------
  Tracing:      active
  Agent ID:     a1b2c3d4-...
  Secret:       configured
  API URL:      https://platform.i42m.ai/api/v1
  Config from:  project (.infinium/config.json)
  Hooks:        .claude/settings.json (9 events)

View Trace History

See what traces have been sent:

infinium-claude history
  Last 3 trace(s):

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

Next Steps