Infinium Cline Connector

Bridge between Cline (VS Code extension) hooks and Infinium agent tracing. Automatically captures Cline tasks — tool calls, prompts, token usage — 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-cline-connector
infinium-cline init
infinium-cline test       # verify credentials + network

Then in VS Code: Settings → Extensions → Cline → Features → Enable Hooks.

That's it. Now just use Cline as you normally would — every task is automatically traced to Infinium.

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

Requirements

• Python 3.9+
• Cline VS Code extension v3.36+ with hooks enabled (Settings → Cline → Features → Enable Hooks)
• An Infinium agent ID and secret

How It Works

After infinium-cline init, Cline fires a command hook for each event. The hook writes a JSON response on stdout (required by Cline), stores the event, and returns instantly.

Cline (VS Code) ──command hook──> python -m infinium_cline_connector.hook
                                      │
                                      ├─ IMMEDIATELY writes stdout response (required)
                                      ├─ append event to session JSONL file
                                      │
                                      └─ on TaskComplete / TaskCancel:
                                           spawn detached background worker
                                           → replay events → aggregate
                                           → read ui_messages.json for tokens
                                           → send trace
                                                                       │
                                                                       ▼
                                                               Infinium API
                                                           POST /agents/{id}/trace

1. Cline fires a command hook for each event (tool call, prompt, etc.) with a nested JSON payload.
2. The hook writes {"cancel": false, "contextModification": null, "errorMessage": null} to stdout — Cline hangs without it.
3. On TaskComplete or TaskCancel, a detached background worker replays all events, reads Cline's ui_messages.json for token usage, aggregates, and sends a trace.

CLI Reference

infinium-cline init

Interactive setup wizard. Writes hook scripts into .clinerules/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-cline test

Send a minimal test trace to verify credentials + network.

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

infinium-cline status

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

infinium-cline pause / infinium-cline resume

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

infinium-cline history

View recently sent traces.

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

infinium-cline errors

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

infinium-cline retry

Resend traces that failed due to network issues.

infinium-cline update-credentials

Update your Agent ID or Secret.

infinium-cline uninstall

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

infinium-cline cleanup

Remove stale session files (housekeeping).

infinium-cline start

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

Per-Project Configuration

Each project traces to its own Infinium agent:

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

cd /path/to/project-b
infinium-cline 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	First user prompt, truncated to 30 chars
description	First user prompt (200-char preview)
input_summary	First user prompt, up to 3000 chars — what Maestro reads as the request
output_summary	Final assistant response, up to 8000 chars — what Maestro reads as the deliverable (Cline's hook events do not yet expose this text)
duration	Total task 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 (success: false in postToolUse)
environment	Model (provider/slug), workspace root, Cline version
llm_usage	Input / output / cache-read / cache-write tokens, total cost (from ui_messages.json)

Captured Events

Event	What It Captures
TaskStart / TaskResume	Task description (200-char step preview; kept up to 3000 chars as input_summary), model, workspace root
UserPromptSubmit	User prompt text (200-char step preview; the first prompt is kept up to 3000 chars as input_summary)
PreToolUse / PostToolUse	Tool name, parameters (up to 200 chars), result (up to 1500 chars), success, duration
PreCompact	Conversation length + estimated tokens before compact
TaskComplete / TaskCancel	Triggers trace 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_SESSION_END=true
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 responses)
CONNECTOR_MAX_INPUT_SUMMARY=3000   # Top-level input_summary (first user prompt)
CONNECTOR_MAX_OUTPUT_SUMMARY=8000  # Top-level output_summary (final assistant response)

Documentation

Full documentation: i42m.ai/docs/cline

License

MIT