infinium-cline-connector 1.0.0

Bridge between Cline (VS Code extension) hooks and Infinium agent tracing

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
description	First user prompt (full)
duration	Total task duration in seconds
steps	Ordered list: user prompts, tool calls
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, model, workspace root
UserPromptSubmit	User prompt text (truncated)
PreToolUse / PostToolUse	Tool name, parameters, result, 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

Documentation

Full documentation: i42m.ai/docs/cline

License

MIT