Quick Start

Get started with Sploink

Sploink wraps your agent session and captures system-level signals in real time — shell commands, file edits, git state, and test runs. This guide gets you running in under 5 minutes.

Installation

Install the Python package

Sploink requires Python 3.10+. Install via pip from your project directory.

bash

$ pip install sploink

Verify the install

bash

$ sploink --helpUsage: sploink [OPTIONS] COMMAND [ARGS]...  Sploink — measure AI coding agent behavior.Commands:  run        Wrap an agent session and capture signals.  dashboard  Launch the real-time TUI dashboard for a session.

First Run

Run sploink init

This configures the Claude Code plugin and installs the VS Code extension in one shot.

bash

$ sploink init✓ Claude Code hooks configured (~/.claude/settings.json)✓ VS Code extension installed

Start your agent

For Claude Code, just run it normally — no wrapper needed. For Cursor or other agents, open your project in VS Code/Cursor.

bash

$ claude "refactor the auth module"# Sploink captures every tool call automatically

Watch the dashboard

Open the Sploink panel in your VS Code sidebar. Convergence and momentum update in real time as the agent works.

bash

# Live scoring (updates every few events):[14:22:06] events=3   convergence: 0.43  thrash: no  momentum: stuck (+0.00)[14:22:11] events=9   convergence: 0.61  thrash: no  momentum: accelerating (+0.18)[14:22:16] events=14  convergence: 0.58  thrash: no  momentum: decelerating (-0.03)[14:22:21] events=19  convergence: 0.71  thrash: no  momentum: accelerating (+0.13)

Using Cursor or a custom agent instead of Claude Code? See Cursor or Custom Agents in the Agent Frameworks section for agent-specific setup.

VS Code Extension

The Sploink VS Code extension adds IDE-level signal capture — diagnostics, cursor activity, and file saves — and surfaces a live dashboard in your sidebar.

Build the extension webview

bash

$ cd vscode-extension/webview$ npm install && npm run build

Launch in Extension Development Host

Open vscode-extension/ in VS Code, then press F5. This compiles the extension and opens a new Extension Development Host window.

The preLaunchTask in launch.json runs the webview build and TypeScript compile automatically — no manual steps needed after the first npm install.

Open the Sploink sidebar

In the Extension Development Host window, click the Sploink icon in the activity bar (or press Cmd+Shift+S). The dashboard panel shows WAITING… until your first event arrives.

Other Agents + Extension Tandem

For Cursor and other non-Claude-Code agents, run the CLI wrapper alongside the VS Code extension to get both system-level and IDE-level capture in a single session. Claude Code users don't need this — the native plugin covers both layers automatically.

Signal flow

CLI wrapper — filesystem, git, shell, process spawns

writes → ~/.sploink/sessions/<id>.json

writes → ~/.sploink/live-session.json

VS Code extension — diagnostics, cursor, file saves

watches → ~/.sploink/live-session.json

activates full tracking when session detected

Sidebar dashboard — convergence, momentum, thrash

updates live on every event

Start the VS Code extension (F5)

Open the Sploink sidebar. It shows WAITING… — the extension is already capturing diagnostics and editor activity in pre-session mode.

Run the CLI wrapper in a terminal

bash

$ sploink run -- cursor "fix the login bug"# or any other agent:$ sploink run -- my-agent "refactor auth"[sploink] session b7d2e09f-...✓ live-session.json written

The extension detects live-session.json within 1 second and activates full tracking — file watcher, git watcher, and diagnostics poller all start.

Watch it update as the agent works

Every file save, git op, and shell command pushes an event into the metric engine. The sidebar updates in real time:

STATUSEXECUTING

Convergence67%

Momentum↑ accelerating

Git component82%

Test pass rate50%

Churn score80%

Get notified on thrash

When thrash is detected (same file edited 3+ times without a commit, or a command failing repeatedly), a VS Code warning notification fires automatically:

Sploink: Thrashing detected

repeated_file_edits (80% confidence)

Thrash notifications have a 30-second cooldown to avoid noise during rapid iteration.

Session ends automatically

When the agent process exits, the CLI wrapper removes live-session.json. The extension detects this and returns to pre-session mode. Final session data is written to:

bash

~/.sploink/sessions/<session_id>.json   # full event log~/.sploink/logs/<session_id>.log        # scored metrics timeline

sploink init

One-time setup command. Installs the Claude Code plugin and VS Code extension — after this, just run claude normally.

bash

$ sploink init✓ Claude Code hooks configured (~/.claude/settings.json)✓ VS Code extension installed✓ Ready — run claude normally, sessions are tracked automatically

sploink init is idempotent — safe to run multiple times. It will not overwrite existing hook configurations.

sploink run

Wrap an agent session and capture all signals.

bash

sploink run [OPTIONS] -- COMMAND [ARGS]...Options:  --task-id TEXT     UUIDv4 task ID (auto-generated if omitted)  --agent TEXT       Agent identifier: claude-code, cursor, custom  --session-id TEXT  UUIDv4 session ID (auto-generated if omitted)  --user-id TEXT     User ID (defaults to OS username)Examples:  $ sploink run -- cursor "fix the login bug"  $ sploink run -- python my_agent.py "refactor auth"  $ sploink run --task-id <uuid> -- bash

sploink dashboard

Launch the terminal TUI dashboard for a session. Called automatically by sploink run, but can be run manually to attach to any session.

bash

sploink dashboard SESSION_IDExample:  $ sploink dashboard a3f8c21d-4b5e-4f7a-8c9d-1e2f3a4b5c6d

Convergence Score

A weighted composite score (0.0–1.0) measuring how well the agent is progressing toward task completion.

Git convergence

40% weight

Diff growth trajectory + commit frequency. Monotonically growing diff → 1.0.

Test convergence

35% weight

Average pass rate across test_finished events. No test events → 0.5 (neutral).

Churn score

25% weight

Penalises files edited 3+ times without a commit. 5+ churning files → 0.0.

Thrash Detection

Thrash confidence is built from three independent signals, capped at 1.0.

text

# Confidence triggers:+0.4  Same target_path in 3+ consecutive file_edited events+0.4  Same command in 3+ command_finished events with exit_code != 0+0.2  Zero net diff_size_bytes growth over last 10 eventsis_thrashing = True if confidence >= 0.5

Momentum

Momentum compares convergence in the current 10-event window against the previous 10-event window.

text

momentum = convergence(last 10 events) - convergence(previous 10 events)trend:  > +0.05  → "accelerating"  < -0.05  → "decelerating"  else     → "stuck"

Agent Frameworks

Claude Code Plugin

The Claude Code plugin uses native PostToolUse hooks to capture every tool call — Edit, Bash, Read, Write — directly into the Sploink event stream. No wrapper command needed.

Install and initialise

bash

$ pip install sploink$ sploink init✓ Claude Code hooks configured (~/.claude/settings.json)✓ VS Code extension installed

Run claude normally

bash

$ claude "refactor the auth module"# Sploink captures automatically:# Edit → file_edited event# Bash → command_finished event# Read → file_read event

No sploink run -- prefix required. The hook fires on every tool use automatically.

Watch the dashboard

Open VS Code — the Sploink sidebar updates in real time as the agent works. Convergence rises as code is written, thrash fires if the agent loops.

Tool → event mapping

Edit, Writefile_edited

Bashcommand_finished

Readfile_read

Glob, Grepfile_search

Tasksubagent_spawned

Cursor

Cursor uses the VS Code extension for capture — no CLI wrapper or hook config needed. The extension watches the workspace directly via VS Code APIs.

Install the VS Code extension

Since Cursor is built on VS Code, the Sploink extension installs directly from the marketplace or via:

bash

$ pip install sploink$ sploink init   # installs the VS Code/Cursor extension automatically

Open your project in Cursor and start agent mode

The extension captures file edits, diagnostics, and git state as Cursor's agent works. Open the Sploink panel in the sidebar to see the live dashboard.

Cursor agent mode edits files through the VS Code API, so onDidChangeTextDocument fires on every agent keystroke — giving Sploink full edit-level granularity.

Custom Agents

For any agent without a native plugin, use the CLI wrapper. It captures OS-level signals regardless of what agent is running inside.

bash

$ sploink run -- my-agent "fix the bug"$ sploink run -- python agent.py "refactor auth"$ sploink run -- bash run_agent.sh

The CLI wrapper works with any subprocess. Everything after -- is passed verbatim to the child process.

What's next

Agent Frameworks — Claude Code, Cursor, custom agents CLI Reference — all flags and config options Metrics deep dive — formulas and worked examples