Splice

<div align="center"> <img src="assets/logo.svg" alt="Splice — two strands spliced into one" width="440"> ### Browser cognition infrastructure for autonomous coding agents [](https://github.com/Arnavnemade1/Splice/actions) [](https://opensource.org/licenses/MIT) [](https://www.typescriptlang.org/) [](https://www.python.org/) [](https://modelcontextprotocol.io/) Splice is an **MCP server** that gives AI coding agents a browser they can actually reason about. It doesn't stop at screenshots or raw DOM — it diagnoses browser state, compiles natural-language intent into verified actions, redacts hostile page content, isolates multi-account sessions, coordinates multiple agents on shared browser state, and records the evidence agents need to recover and improve. [Install](#install) · [Why Splice](#why-splice) · [Tool Reference](#tool-reference) · [Introspection Stack](#the-introspection-stack) · [Quick Start](#quick-start) · [Architecture](#architecture) · [Security Model](#security-model) · [Contributing](#contributing) </div> --- ## Why Splice **Splice does not run agents for you — it makes the agent you already have far more reliable, debuggable, and secure.** Modern autonomous web agents fail because browsers are stateful, noisy, and adversarial. Splice adds a cognition and safety layer so agents can: - understand *why* an action failed instead of retrying blindly, - verify an action actually worked against declared postconditions, - avoid prompt-injection and secret leakage from page content, - recover from browser crashes and stale element references, - run multiple isolated account sessions in parallel, - coordinate several agents against one shared browser without stepping on each other, and - **explain, measure, and optimize their own thinking** — every decision is mapped, screened for hazards, calibrated against outcomes, and reconstructed into a train-of-thought report with a ranked optimization plan. > Splice is the cognitive browser layer for MCP-based agents — the safety and observability layer every agent stack should assume is present. --- ## Install ```bash npm install splice npx splice init # scaffolds splice.config.json + prints MCP client snippets npx splice doctor # verifies Chromium, build output, and runtime deps ``` For Claude Code specifically, registration is one command: ```bash claude mcp add splice -- npx -y splice start ``` See [AGENT_INSTALL.md](AGENT_INSTALL.md) for the deterministic, machine-checkable install path (written for agents installing themselves) and [INTEGRATION.md](INTEGRATION.md) for wiring Splice into a custom agent via the raw MCP SDK. --- ## Tool Reference Splice exposes **69 MCP tools** over stdio, grouped below by what they're for. Full JSON schemas live in [src/index.ts](src/index.ts); this table is the map. ### Navigate & Observe | Tool | What it does | | --- | --- | | `navigate` | Go to a URL — auto-retries transient failures, dismisses cookie banners, waits for stability. | | `get_semantic_tree_optimized` | AI-optimized page tree pruned by intent, viewed through a lens (UX/Security/Performance/Network/Behavior/Vision), with `deltaOnly` mode for cheap incremental reads. | | `wait_for` | Semantic waiting on text/element/URL/network conditions — replaces polling loops. | | `get_network_activity` | Lifecycle-tracked requests with aggregates and a plain-English "what went wrong" summary. | | `get_page_events` | Dialogs, popups, and downloads a DOM-only observer never sees. | | `inspect_viewport` | Numbered-highlight screenshot plus structured data on video/canvas/iframe/slider/carousel widgets the tree under-reports. | | `capture_annotated_screenshot` / `capture_node_screenshot` | Screenshots with bounding boxes, or of a single element, for vision-model use. | ### Act & Verify | Tool | What it does | | --- | --- | | `diagnose_agent_state` | Classifies the page (ready, ui_obstruction, auth_required, captcha, navigation_pending, etc.) with a recommended next tool and a stuck-loop forecast. | | `compile_verified_action` | The main way to act — compiles a structured intent into a ranked target with preconditions/postconditions, executes, and verifies against your declared `expect`. | | `interact` | Low-level click/type/focus/select/press by element ID, with self-healing on stale references. | | `fill_form` | Fills an entire form by human labels in one call, with honest per-field status and optional verified submit. | | `extract_structured` | Schema-driven scraping — name fields, get back rows from tables/cards/label-value pairs with confidence scores. | | `assert_page_state` | Cheap postcondition checks (URL/title/text/element) without a full tree read. | | `run_accessibility_audit` | Deterministic WCAG audit scored 0–100, with fixes and how each failure degrades agent operation. | ### Sessions, Snapshots & Stealth | Tool | What it does | | --- | --- | | `create_session` / `switch_session` / `list_sessions` / `save_session` / `destroy_session` | Isolated, named browser identities — separate cookies, storage, and fingerprint per account, saved logins restored automatically. | | `get_stealth_profile` | Returns the active fingerprint plus a Web Bot Auth (Ed25519) directory so cooperative sites can verify signed requests. | | `get_web_bot_auth` / `configure_web_bot_auth` | **The honest, CAPTCHA-free access path.** Sign outbound requests (RFC 9421 HTTP Message Signatures, Ed25519) for an operator-set origin allowlist, so cooperating sites can verify *which* bot is calling and grant access without a challenge — identification, not evasion. Enable/scope it, publish the JWK-Set directory, and self-verify the signature round-trips. Off by default. | | `save_snapshot` / `load_snapshot` | Serialize or restore full session state (cookies, auth) instantly. | | `fork_state` / `speculative_fork` / `commit_branch` | Clone browser state into background branches for shadow-testing risky actions or pre-loading URLs. | ### Recovery & Debugging | Tool | What it does | | --- | --- | | `request_human_intervention` | Halts the agent and opens a visible Chromium window for a human to clear a CAPTCHA or blocker. | | `debug_failure` | Saves a time-travel Playwright trace of the session. | | `execute_script` | Arbitrary JS in the browser context. | | `toggle_watch_mode` | Switch between headless and headful so a human can watch. | | `get_runtime_health` | Browser connectivity, branch states, crash/recovery counters, uptime. | | `export_run_journal` | Export the append-only log of every tool call, outcome, and error for post-mortem analysis. | | `run_diagnostics` | Health-checks Playwright, Chromium, vault, and network connectivity. | | `maintenance_cleanup` | Deletes old snapshots, traces, and reports. | ### Introspection & Self-Improvement | Tool | What it does | | --- | --- | | `get_session_trace` | Live, ephemeral chain-of-thought — every intent, diagnosis, wait, and outcome from this session, nothing persisted. | | `run_jacobian_lens` | Sensitivity analysis of target selection: which intent words are load-bearing, whether the choice flips without them; with `deep: true`, the exact analytic Jacobian, token geometry, flip boundaries, **and the decision workspace** — Splice's low-dimensional J-space analog (named concept axes, effective dimensionality, concept-direction SVD, softmax decision Jacobian). Its own pre-action workspace, not the model's hidden state. | | `get_jspace_map` | The session's J-space map, built with zero setup: every compiled action and lens probe automatically records its decision geometry. Returns the dimensionality trend, session-wide concept leaderboard, choices made near a flip boundary, recurring dead-weight intent words, and map-derived recommendations. A session report (JSON + markdown) is written to `.splice/jspace/` automatically at session end. | | `generate_thought_report` | **Train of thought**: the session's cognition as a typed thinking transcript — observe → believe → decide → act → verify, each decision annotated with its J-space why and hazards — plus thinking-**pattern** analysis (blind retries, thought loops, dithering, hesitation, unverified streaks) and one ranked chain-of-thinking optimization plan merging every introspection engine's advice. Persisted to `.splice/thought/`. | | `get_jspace_detections` | The J-space detector's hazard log: every decision is auto-screened for dangerous geometry — near-tie readouts, **aliased candidates** the scorer can't tell apart ("which Delete button?"), flip-boundary proximity, rank-one intents, inert-majority phrasing, concept conflicts (won *despite* an obstruction/external penalty), dimensional collapse — plus session trends: unstable targets (page drift), fragility streaks, chronic ambiguity. Warning/critical findings also attach to plan evidence at compile time. Advisory only; never blocks. | | `explain_last_decision` | "Why did you pick that?" answered in a ten-second, plain-language story: winner, runner-up and margin, the word the choice hangs on (and the cheapest reweighting that would have flipped it), dead-weight words, prediction vs verified outcome, and whether this session's confidence has been trustworthy. The friendly face of the J-space machinery — no matrices. | | `run_intent_experiment` | Decision research before acting: races your phrasing against deterministic rewrites (optimizer, inert-token strip, exact-label quote) plus up to 4 of your own, ranked by the real scorer on the live page — nothing executes. Reports per-phrasing robustness, flip distance, and margin; whether phrasings even agree on the target (disagreement = ambiguous intent); and a recommended phrasing ready to compile. | | `generate_behavior_report` | Scored, persisted digest of a run's chain of thought with prioritized self-improvement recommendations (written to `.splice/behavior/`) — now including a **confidence-calibration record**: Brier score, per-band reliability, and the high-confidence actions that failed anyway. | | `optimize_prompt` | Offline rewrite of a verbose/conversational prompt into the structured intent Splice ranks best, or a better-fit primitive call. **Session-learning:** words the J-space map has repeatedly seen match nothing are stripped automatically (cross-checked against the current page's labels, always reported). | | `generate_observability_report` | High-aesthetic, auto-refreshing HTML dashboard of session activity. | | `get_product_intelligence` | Analyzes behavior logs (clicks, rage-clicks, friction) into feature recommendations. | ### Security | Tool | What it does | | --- | --- | | `run_security_audit` | Crawls a URL checking headers, XSS surfaces, CSRF tokens, sensitive data exposure, and third-party deps; returns a structured, AI-actionable report. | | `scan_local_secrets` | Scans the local workspace for hardcoded API keys/secrets before they leak. | | `toggle_resource_blocking` | Blocks ads, trackers, and heavy media — on by default for agents. | ### Multi-Agent Coordination | Tool | What it does | | --- | --- | | `register_agent` | Declares an agent's role (explorer, verifier, executor, auditor) for constraint and ownership tracking. | | `get_canonical_context` | Pulls the Canonical Context Snapshot — the single shared source of truth replacing agent-to-agent messaging. | | `acquire_branch_ownership` / `handoff_branch` | Claim or atomically transfer exclusive write access to a browser branch. | | `promote_finding` / `resolve_conflict` | Push a finding to the Immutable Evidence Ledger; resolve quorum conflicts by confidence. | | `get_coordination_health` | Live overhead metrics — conflicts, blocked actions, ownership violations. | | `get_summons` / `acknowledge_summon` | List and accept pending human help requests. | | `get_agent_analytics` | Per-agent success rate, latency, failure streaks, and ranked optimization directives. | ### Integrations | Tool | What it does | | --- | --- | | `toggle_openclaw_gateway` | Enable/disable the local OpenClaw gateway (port 18789) for external agent connections. | | `configure_discord_webhook` / `send_discord_update` | Wire up and send automated significant-event notifications to Discord. | ### MCP Resources Beyond tools, Splice exposes resources: the raw semantic tree, telemetry data, a health/performance dashboard, a live heartbeat feed, the recommended agent playbook (`splice://guide/agent-playbook`), and the animated Splice logo. --- ## The Introspection Stack Splice's most distinctive layer: the agent's own decisions become measurable objects. Everything below builds itself passively as the agent acts — zero extra calls — and each layer feeds the next: ```text every compiled action / lens probe │ ├─ J-SPACE MAP (get_jspace_map) ────────── the decision's geometry, recorded: │ effective dimensionality, carrying concept axes, flip-boundary distance, │ softmax confidence, dead-weight words — aggregated across the session │ ├─ DETECTOR (get_jspace_detections) ────── the geometry, screened: │ near-ties, aliased candidates ("which Delete button?"), boundary │ proximity, concept conflicts, page drift — warnings attach to the │ plan's evidence at the moment of action │ ├─ CALIBRATION (in behavior reports) ───── the confidence, audited: │ stated compile confidence vs verified outcomes — Brier score, per-band │ reliability, the high-confidence actions that failed anyway │ ├─ EXPLAIN / EXPERIMENT ────────────────── the decision, interrogated: │ explain_last_decision retells any choice in plain language; │ run_intent_experiment races phrasings on the live page before acting │ └─ TRAIN OF THOUGHT (generate_thought_report) ── the thinking, optimized: a typed transcript (observe → believe → decide → act → verify) with each decision's why inline, thinking-pattern detection (blind retries, loops, dithering, hesitation), and ONE ranked optimization plan ``` Session artifacts land in `.splice/` for the next run to read: `jspace/` (decision-geometry map, written automatically at close), `thought/` (train of thought, written automatically at close), `behavior/` (chain-of-thought digest with calibration). Offline: `splice report --jspace` and `splice report --thought`. The optimizer closes the loop: words the map has seen match nothing repeatedly are stripped from future intents automatically (cross-checked against the current page's labels, always reported). Honest scope, everywhere: this measures Splice's own pre-action decision workspace and observable cognition events — a structural analog of model introspection, never a claim of access to the calling model's hidden state. Want to ask these questions of a **real model's internals**? [`lab/`](lab/) is the Model Mind Lab: the interpretability experiments behind Anthropic's research program (Jacobian saliency, logit lens, activation patching, concept injection, induction heads) implemented from scratch on open weights, with the research mapped in [`lab/RESEARCH.md`](lab/RESEARCH.md). Standalone, CPU-only, not part of the MCP server. --- ## Quick Start ### Prerequisites - Node.js `>=20` - Python `>=3.10` (only if using the optional Python MCP server) ### From source ```bash npm install npm run build npm start # starts the MCP server (stdio) npm test # 50-step local validation against a synthetic web app npm run test:regression # known failure patterns: menus, validation, overlays, a11y npm run test:introspection # browser-free unit tests for the introspection stack npm run test:all # everything: 17 + 50 + 29 = 96 checks ``` ### CLI commands | Command | Description | | --- | --- | | `splice start` | Start the MCP server (stdio) | | `splice init` | Scaffold `splice.config.json` and print client registration snippets | | `splice doctor` | Verify Playwright/Chromium/build/network before first launch | | `splice config` | Inspect or edit local configuration | | `splice session` | Manage saved session identities from the CLI | | `splice report` | Generate a behavior or observability report | ### Recommended cognition loop ``` navigate → diagnose_agent_state → compile_verified_action (with expect) → verify via deltas ``` This loop, plus prompt hygiene and the self-improvement cycle, is documented in the `splice://guide/agent-playbook` MCP resource — read it first after connecting. ### Example: compiled verified action ```json { "name": "compile_verified_action", "arguments": { "intent": "click the pricing link", "execute": true, "expect": [{ "kind": "url_contains", "value": "/pricing" }], "constraints": { "noNavigationOutsideDomain": true, "avoidDestructiveActions": true } } } ``` ### Example: batch form fill ```json { "name": "fill_form", "arguments": { "fields": [ { "field": "email", "value": "user@example.com" }, { "field": "password", "value": "s3cureP@ss" } ], "submitIntent": true } } ``` --- ## Architecture ```text src/ # TypeScript source — MCP server, tool implementations index.ts # tool + resource registration (the 62 tools above) BrowserManager.ts # launches browser instances, manages branches, recovers crashed pages SemanticExtractor.ts # page understanding, delta-enabled observation AgentCoordinator.ts # multi-agent branch ownership, evidence ledger, quorum AgentTracker.ts # per-agent health metrics and optimization directives SecurityAuditor.ts # prompt-injection redaction, secret egress protection, security audits RecoveryMemory.ts # domain-scoped memory of which recovery fixes worked RunJournal.ts # append-only JSONL log of every tool call and outcome SessionStore.ts # named, isolated account sessions (cookies, storage, fingerprint) StealthProfile.ts # coherent per-session fingerprints + Web Bot Auth directory JacobianLens.ts / JSpace.ts # sensitivity analysis of target selection JSpaceMap.ts # session-wide decision-geometry map + per-session reports JSpaceDetector.ts # hazard detection over decision geometry (aliasing, near-ties, drift) Cognition.ts # confidence calibration + plain-language decision explanations TrainOfThought.ts # typed thinking transcript + thinking-pattern analysis + optimization plan BehaviorReport.ts # scored chain-of-thought digests and self-improvement recommendations PromptOptimizer.ts # deterministic, offline intent rewriting AccessibilityAuditor.ts # WCAG audit engine Resilience.ts # crash recovery, retries, graceful shutdown OpenClawGateway.ts / DiscordWebhook.ts / WebBotAuth.ts / CryptoManager.ts # integrations & crypto cli.ts # splice start / init / doctor / config / session / report dist/ # compiled runtime output dist_test/ # compiled tests dashboard/ # local observability UI python/ # optional Python MCP server integration lab/ # Model Mind Lab — real interpretability experiments on open weights # (Jacobian saliency, logit lens, patching, steering, induction heads) assets/ # logo and static resources ``` --- ## Security Model Splice is designed for autonomous agents operating in real browser environments: - **Input isolation** — agents receive only audited, redacted page content; prompt injection is stripped before it reaches the model. - **Output safety** — non-GET requests are inspected for secret patterns and blocked if unsafe; `scan_local_secrets` checks the local workspace too. - **Session isolation** — each named session gets its own cookies, storage, and stable fingerprint, never shared across accounts. - **Recovery transparency** — every crash, recovery, and coordination conflict is logged to the Run Journal and exportable for audit. - **Honest access, not evasion** — Splice deliberately ships no CAPTCHA-solver or proxy-rotation stack. When a page challenges the agent it *detects* the block and hands off to a human (`request_human_intervention`); for sites that support it, **Web Bot Auth** (`configure_web_bot_auth`) proves the agent's identity with signed requests so access can be granted without a CAPTCHA. The goal is verifiable identification, never defeating bot-detection. > Splice is not a sandbox replacement. It is a browser cognition and safety layer that helps agents act with evidence and accountability. --- ## Contributing We welcome contributions. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md) for community expectations. ```bash git clone https://github.com/Arnavnemade1/Splice.git cd Splice npm install npm run build npm test ``` --- ## Need help? - GitHub Issues: https://github.com/Arnavnemade1/Splice/issues - License: MIT - Homepage: https://github.com/Arnavnemade1/Splice#readme