infinium-claude-code-connector 1.2.1

Bridge between Claude Code hooks and Infinium agent tracing

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 init
infinium 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 is not on your PATH, use python -m infinium_connector as a drop-in replacement.

How It Works

After infinium 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 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 test

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

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

infinium status

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

infinium pause / infinium resume

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

Aliases: stop / continue

infinium history

View recently sent traces.

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

infinium retry

Resend traces that failed due to network issues.

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

infinium update-credentials

Update your Agent ID or Secret.

infinium uninstall

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

Options:
  -y, --yes    Skip confirmation prompt

infinium cleanup

Remove stale session files (housekeeping).

infinium 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 init    # Enter Agent A credentials

cd /path/to/project-b
infinium 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

Field	Source
name	Session summary (e.g., "Claude Code session (3 turns)")
description	First user prompt
duration	Total session duration in seconds
steps	Ordered list: user prompts, tool calls, subagent spawns
errors	Tool failures with error messages
environment	Model, session source, working directory, permission mode

Captured Events

Event	What It Captures
SessionStart	Model, source (startup/resume), working directory
UserPromptSubmit	User prompt text (truncated to 500 chars)
PreToolUse / PostToolUse	Tool name, input, output, duration
PostToolUseFailure	Error details
SubagentStart / SubagentStop	Subagent lifecycle (cowork, agent teams)
Stop	Assistant's final response — triggers trace flush
SessionEnd	Session cleanup — triggers final 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=3600         # Stale session cleanup threshold (seconds)
CONNECTOR_SESSION_DIR=...          # Override temp directory for session files

Documentation

Full documentation: i42m.ai/docs/claude-code

License

MIT