Installation

pip install infinium-copilot-cli-connector

Requirements: Python 3.9 or higher, GitHub Copilot CLI installed.

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-copilot 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 Copilot CLI 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:   hooks.json

  Note: Copilot CLI auto-discovers hooks.json in the current working
  directory. Run Copilot CLI from this project root and hooks will fire.

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

That’s it. Copilot CLI auto-discovers hooks.json in its current working directory, so when you run Copilot from your project root, tracing just works.

If infinium-copilot is not found, use python -m infinium_copilot_cli_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-copilot 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 Copilot CLI as normal.

  1. You run Copilot CLI from your project directory
  2. Copilot auto-discovers hooks.json in the cwd and fires the connector’s hook for each event
  3. The connector converts Unix-millisecond timestamps to ISO 8601, normalizes the event name, and synthesizes a sessionId from the parent process if Copilot doesn’t provide one
  4. Events accumulate in a temporary session JSONL file
  5. On sessionEnd, a detached background worker aggregates events into a structured trace
  6. The trace is sent to your Infinium agent via the API
  7. 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-copilot status
  Infinium Copilot CLI Connector Status
  --------------------------------------
  Tracing:       active
  Agent ID:      a1b2c3d4-...
  Secret:        configured
  API URL:       https://platform.i42m.ai/api/v1
  Granularity:   per-session (on sessionEnd)
  Config from:   project (.infinium/config.json)
  Hooks:         hooks.json

View Trace History

See what traces have been sent:

infinium-copilot 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