touch-browser

Purpose

touch-browser is the evidence verification layer for AI agents. Its work begins after page retrieval, and it is aimed at scenarios where one needs to determine whether a claim is supported, contradicted, or still requires more browsing by a web page. The product positioning is "evidence first, not factual finality": it helps AI collect local page evidence and trace its source, while truth judgments across pages or at a broader scope are still made by higher-level models or humans.

It is explicitly not a general-purpose truth oracle, not a general-purpose crawler replacement, and does not guarantee that every unsupported claim is false.

Main capabilities

• Claim verification:extract Verify a claim against the current page and return a structured claimOutcome, containing four determinations: evidence-supported (the current page provides usable support), contradicted (the current page provides conflicting evidence), insufficient-evidence (the current page has insufficient direct support), needs-more-browsing (the current page is not specific enough yet and another page is needed).
• Optional prediction surface: outputs confidenceBand, reviewRecommended, supportSnippets, verdictExplanation, matchSignals, letting the agent decide the next step instead of blindly trusting the first match. When reviewRecommended is true, the claim should not be reused without human or secondary verification.
• Grouping and synthesis: evidenceSupportedClaims, contradictedClaims, insufficientEvidenceClaims, needsMoreBrowsingClaims are state-grouped views of the same extraction result;session-synthesize aggregate the grouped view of tabs already opened in the session into JSON or Markdown with citations.
• Support read surface:read-view provide readable Markdown for human review or verification models;compact-view provide low-token semantic state for the agent loop;search perform structured discovery before opening candidate pages.
• Security and audit surface:policy classify pages and actions as allow, review, or block;serve expose the runtime via stdio JSON-RPC for MCP or agent integration.
• Optional prediction routing layer: use as a verifier-friendly routing layer.

How to use

60-second validation: before the first browser-supported run, check the local runtime first.quickstart show the safe local first-use flow, success signals, and common pitfalls;doctor validate the installed executable, runtime resources, data root, Node runtime, Playwright Chromium, MCP bridge entry point, and semantic model readiness. If attention-required is reported, fix local dependencies first before judging browser behavior.

After installation, one command can be run to experience the difference from raw scraping. The verdict output path is: check the top-level status -> check summary.reusableClaims and reuseSummary.allClaimsReusable -> check each claimOutcomes[].verdict -> check claimOutcomes[].reviewRecommended -> when one evidence line is needed, cite claimOutcomes[].primarySupportSnippet -> when handing evidence to other systems, use claimOutcomes[].citation.url and citation.retrievedAt.

Decision tree for reading claimOutcome: first-time users should ignore most fields at first and follow this order: if reviewRecommended is true, do not reuse without human or secondary verification; when one citation-style evidence line is needed, use primarySupportSnippet; when the reason for the verdict is needed, read verdictExplanation; if the verdict is insufficient to answer, follow nextActionHint; use matchSignals only when debugging or comparing evidence quality.

MCP path: the main local host MCP path is the npm package @nangman-infra/touch-browser-mcp, scope is public documents and research-type web pages, the contract is headless-only, automatically selects the search engine, and hands off to human-supervised recovery upon encountering challenge/auth/MFA. On first launch, the package downloads the matching standalone runtime package from GitHub Releases, verifies the published .sha256, installs it to ~/.touch-browser/npm-mcp/versions/, then starts touch-browser mcp. Suitable for direct integration by local MCP hosts such as Claude Desktop, Cursor, and Codex.

Recommended MCP loop:tb_search -> tb_search_open_top -> tb_read_view -> tb_extract。tb_session_create accepts an optional caller-provided sessionId for external correlation;tb_open stateless use requires target, and when a sessionId is present target may be omitted to reopen the active tab page URL;tb_read_view、tb_extract、tb_policy target may be omitted when the sessionId points to an already-open active tab;tb_extract claims is always required;tb_session_synthesize requires sessionId and at least one open tab. Long-running MCP calls emit notifications/progress when the host provides _meta.progressToken;tb_cancel can reset the daemon; in-flight requests use MCP notifications/cancelled. engine and headed are not exposed via MCP.

Standalone package: A tagged v* push builds macOS and Linux standalone packages in the Standalone Release workflow, including bin/touch-browser, the Rust binary under runtime/touch-browser-bin, a bundled Node runtime with the Playwright adapter, and the default semantic run script (lazy-downloads the semantic/NLI models). Browser actions default to the Playwright adapter as a zero-config compatible default; new CLI deployments are recommended to use the Rust CDP path, and the CDP adapter reports browser-supported captures as sourceType: "cdp-rust", reuses a persistent browser context directory, applies the search identity configuration to search result captures, and covers consistency fixtures and CLI E2E verification for follow, click, type, submit, pagination, expand, iframe, shadow DOM, SPA updates, download clicks, persistent session actions, cross-origin nested shadow interaction, etc. Chrome or Chromium is still required; set TOUCH_BROWSER_CDP_BROWSER=/absolute/path/to/chrome when in a non-standard location.

The default release profile is slim, including Playwright Chromium for zero-config browser actions, skipping the semantic model cache, and lazy-downloading the semantic/NLI models on first use. Use the full profile when an offline package needs to include a warm model cache. The installer performs a managed installation: versions are located in ~/.touch-browser/install/versions/<bundle-name>, the active version is ~/.touch-browser/install/current, the PATH command points to ~/.touch-browser/install/current/bin/touch-browser，touch-browser update swaps current for the newly verified release package,touch-browser uninstall --purge-all --yes removes the managed installation and all stored data.

Installed search by default retains engine-level persistent trust configuration: Google is located in ~/.touch-browser/browser-search/profiles/google-default, Brave is located in ~/.touch-browser/browser-search/profiles/brave-default, and the profile state metadata is ~/.touch-browser/browser-search/<engine>.profile-state.json.

Building from source: Prerequisites are rustup, Node.js 18+, and pnpm. A source checkout is a contributor workflow; release and operations documentation still assumes use of the touch-browser command installed from the standalone package.bootstrap-local.sh installs the default semantic model to ~/.touch-browser/models/evidence/embedding and ~/.touch-browser/models/evidence/nli. Use TOUCH_BROWSER_EVIDENCE_EMBEDDING_MODEL_PATH or TOUCH_BROWSER_EVIDENCE_NLI_MODEL_PATH only when you need to override the default locations.

Applicable Scenarios

• AI agent workflows that need sources pointing to evidence rather than raw HTML dumps.
• Need support for snippets and verdict explanations for the agent to check before answering.
• Need a safe pending path for borderline claims rather than making things up.
• Need policy-gated browsing rather than blind automation.
• Need replayable, auditable multi-page research sessions.

Limitations

• Evidence-first, not fact-final; truth across pages or at a broader scope is decided by higher-level models or humans.
• Does not guarantee that every unsupported claim is false.
• The MCP package scope is narrower than the full CLI, limited to public documentation and research-type web pages.
• When a page presents a challenge, auth, MFA, or other situations requiring supervised recovery, stop and hand off to a human rather than retrying with different browser settings.
• The latest local benchmark rerun signal comes from 2026-05-05 and is not a commitment for every future public page.

License

This repository uses MPL-2.0, allowing commercial and non-commercial use; if you distribute modified MPL-covered files, those files remain subject to MPL-2.0; independent files in a larger work may be under different terms. See LICENSE for the full legal text and LICENSE-POLICY.md for the plain-language policy.