Infinium Copilot CLI Connector

Bridge between GitHub Copilot CLI hooks and Infinium agent tracing. Automatically captures Copilot CLI sessions — tool calls, prompts, errors — 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-copilot-cli-connector
infinium-copilot init
infinium-copilot test       # verify credentials + network

That's it. Now just use Copilot CLI as you normally would — every session is automatically traced to Infinium. Copilot CLI auto-discovers hooks.json in your working directory.

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

Requirements

• Python 3.9+
• GitHub Copilot CLI (GA as of Feb 2026)
• An Infinium agent ID and secret

How It Works

After infinium-copilot init, everything is automatic. Copilot CLI loads ./hooks.json and fires the connector for each event.

Copilot CLI ──./hooks.json──> python -m infinium_copilot_cli_connector.hook
                                 │
                                 ├─ converts Unix-ms timestamps to ISO 8601
                                 ├─ normalizes camelCase / PascalCase event names
                                 ├─ synthesizes sessionId from parent PID if absent
                                 ├─ append event to session JSONL file
                                 │
                                 └─ on sessionEnd (or postToolUse for per-turn):
                                      spawn detached background worker
                                      → replay events → aggregate → send trace
                                                                       │
                                                                       ▼
                                                               Infinium API
                                                           POST /agents/{id}/trace

1. Copilot CLI fires a hook for each event (sessionStart, preToolUse, postToolUse, userPromptSubmitted, sessionEnd, errorOccurred).
2. The hook normalizes the payload (Unix-ms → ISO 8601, camelCase canonicalization), appends to a session JSONL file, and returns instantly.
3. On sessionEnd (or postToolUse for per-turn traces), a detached worker replays, aggregates, and sends to Infinium.

CLI Reference

infinium-copilot init

Interactive setup wizard. Writes ./hooks.json that points at the connector.

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

Send a minimal test trace to verify credentials + network.

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

infinium-copilot status

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

infinium-copilot pause / infinium-copilot resume

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

infinium-copilot history

View recently sent traces.

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

infinium-copilot errors

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

infinium-copilot retry

Resend traces that failed due to network issues.

infinium-copilot update-credentials

Update your Agent ID or Secret.

infinium-copilot uninstall

Remove the connector completely — hook entries from hooks.json, config file, and keyring secret.

infinium-copilot cleanup

Remove stale session files (housekeeping).

infinium-copilot start

Start HTTP server mode (requires pip install infinium-copilot-cli-connector[server]).

Per-Project Configuration

Each project traces to its own Infinium agent:

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

cd /path/to/project-b
infinium-copilot 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	Initial or first user prompt, truncated to 30 chars
description	Initial or first user prompt (200-char preview)
input_summary	Initial or first user prompt, up to 3000 chars — what Maestro reads as the request
output_summary	Session outcome synthesized from the last tool result, 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 + errorOccurred events
environment	Working directory, session source, end reason

Captured Events

Event	What It Captures
sessionStart	Source (new/resume/startup), initial prompt
userPromptSubmitted	User prompt text (200-char step preview; the first prompt is kept up to 3000 chars as input_summary)
preToolUse / postToolUse	Tool name, parsed args (up to 200 chars), result type, LLM text (up to 1500 chars per step; the last result is kept up to 8000 chars as output_summary)
errorOccurred	Error message, name, stack
sessionEnd	Reason (complete/error/abort/timeout/user_exit) — triggers trace flush

Trace Granularity

Choose during init or via CONNECTOR_FLUSH_ON_STOP:

• Per-session (default) — one summary trace per session (on sessionEnd)
• Per-turn — a trace after every postToolUse (noisy but detailed)
• Both — per-turn traces plus a final session summary

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=false          # Per-turn flush on postToolUse
CONNECTOR_FLUSH_ON_SESSION_END=true    # Summary flush on sessionEnd
CONNECTOR_SESSION_TTL=1800             # 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 outcomes)
CONNECTOR_MAX_INPUT_SUMMARY=3000       # Top-level input_summary (first user prompt)
CONNECTOR_MAX_OUTPUT_SUMMARY=8000      # Top-level output_summary (session outcome from the last tool result)

Documentation

Full documentation: i42m.ai/docs/copilot-cli

License

MIT