Infinium Claude Code Connector

Bridge between Claude Code hooks and Infinium agent tracing. Automatically captures Claude Code sessions — tool calls, prompts, subagent activity — 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-claude-code-connector
infinium-claude init
infinium-claude test

That's it. Now just use Claude Code as you normally would — every session is automatically traced to Infinium. No server to run, no extra terminal, nothing to remember.

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

How It Works

After infinium-claude init, everything is automatic. You use Claude Code exactly as before — the connector works silently in the background via hooks.

Claude Code ──command hook──> python -m infinium_connector.hook
                                  │
                                  ├─ append event to session JSONL file
                                  │
                                  └─ on Stop/SessionEnd:
                                       replay events → aggregate → send trace
                                                                      │
                                                                      ▼
                                                              Infinium API
                                                          POST /agents/{id}/trace

1. Claude Code 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
3. On turn completion (Stop) or session end, all events are replayed, aggregated into a structured trace, and sent to Infinium via the Python SDK
4. Maestro interprets the trace (grading accuracy, efficiency, prompt adherence)

CLI Reference

infinium-claude init

Interactive setup wizard. Configures credentials and Claude Code 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-claude test

Send a test trace to verify your setup works end-to-end.

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

infinium-claude status

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

infinium-claude pause / infinium-claude resume

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

Aliases: stop / continue

infinium-claude history

View recently sent traces.

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

infinium-claude retry

Resend traces that failed due to network issues.

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

infinium-claude update-credentials

Update your Agent ID or Secret.

infinium-claude uninstall

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

Options:
  -y, --yes    Skip confirmation prompt

infinium-claude cleanup

Remove stale session files (housekeeping).

infinium-claude start

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

Per-Project Configuration

Each project traces to its own Infinium agent:

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

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

Config resolution order:

1. Project config (.infinium/config.json in 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

Captured Events

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=3600         # 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/claude-code

License

MIT