infinium-copilot-cli-connector 1.0.0

Bridge between GitHub Copilot CLI hooks and Infinium agent tracing

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
description	Initial or first user prompt (full)
duration	Total session duration in seconds
steps	Ordered list: user prompts, tool calls
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 (truncated)
preToolUse / postToolUse	Tool name, parsed args, result type, LLM text
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

Documentation

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

License

MIT