touch-browser

Ask a claim. Get page-grounded evidence, verdicts, and citations.

touch-browser is an evidence verification layer for AI agents. It does more than fetch a page or convert HTML to Markdown. It opens a page, compiles a structured snapshot, and tells you whether the current page supports a claim, contradicts it, or still needs more browsing.

Use it when you need:

• source-linked evidence instead of raw HTML dumps
• support snippets and verdict explanations that an agent can inspect before answering
• a safe unresolved path for borderline claims instead of bluffing
• policy-gated browsing instead of blind automation
• replayable, auditable multi-page research sessions

Evidence-first, not fact-final:

• touch-browser helps an AI collect page-local evidence and trace where it came from
• a higher-level model or human still decides what is true across pages or across the wider world

What extract Returns

Abbreviated claimOutcome shape from the current extractor:

{
  "statement": "The Starter plan costs $29 per month.",
  "verdict": "evidence-supported",
  "confidenceBand": "high",
  "reviewRecommended": false,
  "supportSnippets": [
    {
      "blockId": "b4",
      "stableRef": "rmain:table:plan-monthly-price-snapshots-starter-29-10-000-t",
      "snippet": "Starter | $29 | 10,000"
    }
  ],
  "verdictExplanation": "Matched direct support in 3 page block(s). Review the attached snippets before reusing the claim."
}

The extractor returns four verdicts:

• evidence-supported: the current page surfaced usable support
• contradicted: the current page surfaced conflicting evidence
• insufficient-evidence: the current page did not provide enough direct support
• needs-more-browsing: the current page is not specific enough yet, so the next step is another page

confidenceBand, reviewRecommended, supportSnippets, verdictExplanation, and matchSignals are there so an agent can decide what to do next without blindly trusting the first match.

Standalone Bundle

Tagged v* pushes now build standalone macOS and Linux bundles in the Standalone Release workflow. Each bundle includes:

• bin/touch-browser
• the optimized Rust binary under runtime/touch-browser-bin
• a bundled Node runtime and Playwright adapter
• the default semantic runner scripts and model cache

When a tagged release is published, download the matching tarball from GitHub Releases, unpack it, and run:

./touch-browser-<version>-<platform>-<arch>/install.sh
touch-browser telemetry-summary
touch-browser update --check

To build the same portable bundle locally:

pnpm install --frozen-lockfile
pnpm run build:standalone-bundle -- v0.1.0-rc1

# Then install the bundled command into PATH
./dist/standalone/touch-browser-v0.1.0-rc1-<platform>-<arch>/install.sh
touch-browser telemetry-summary
touch-browser update --check

The official user path is:

1. unpack a standalone bundle
2. run install.sh
3. use the installed touch-browser command for every CLI and serve operation

The installer now performs a managed install:

• managed versions live under ~/.touch-browser/install/versions/<bundle-name>
• the active version is ~/.touch-browser/install/current
• the PATH command points at ~/.touch-browser/install/current/bin/touch-browser
• touch-browser update swaps current to a newly verified release bundle
• touch-browser uninstall --purge-all --yes removes the managed install and all stored data

First Run

This is the command-only proof path that matches the installed user experience:

touch-browser open https://www.iana.org/help/example-domains --browser --session-file /tmp/tb-first-run.json
touch-browser session-read --session-file /tmp/tb-first-run.json --main-only
touch-browser session-extract --session-file /tmp/tb-first-run.json \
  --claim "As described in RFC 2606 and RFC 6761, a number of domains such as example.com and example.org are maintained for documentation purposes."
touch-browser session-synthesize --session-file /tmp/tb-first-run.json --format markdown
touch-browser session-close --session-file /tmp/tb-first-run.json

Installed search now keeps an engine-level persistent trust profile by default:

• Google: ~/.touch-browser/browser-search/profiles/google-default
• Brave: ~/.touch-browser/browser-search/profiles/brave-default
• profile state metadata: ~/.touch-browser/browser-search/<engine>.profile-state.json

Contributor Build From Source

Prerequisites: rustup, Node.js 18+, pnpm.

bash scripts/bootstrap-local.sh
cargo build --release -p touch-browser-cli
pnpm run build:standalone-bundle -- local-dev
./dist/standalone/touch-browser-local-dev-<platform>-<arch>/install.sh

Source checkout is a contributor workflow. Release and operations docs still assume the installed touch-browser command from the standalone bundle.

bootstrap-local.sh installs the default semantic models under:

• ~/.touch-browser/models/evidence/embedding
• ~/.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 those default locations.

Why Not Markdown Alone?

touch-browser is not trying to replace every crawler or browser tool. Its job starts after page acquisition.

Product Surface

Primary surface:

• extract: verify claims against the current page and return structured claim outcomes

Supporting read surfaces:

• read-view: readable Markdown for a human reviewer or verifier model
• compact-view: low-token semantic state for agent loops
• search: structured discovery before opening candidate pages

Safety and audit surfaces:

• policy: classify pages and actions as allow, review, or block
• session-synthesize: turn a multi-page session into JSON or Markdown with citations
• serve: expose the runtime over stdio JSON-RPC for MCP or agent integration

What touch-browser Is

• an evidence-first extractor
• a selective prediction surface
• a verifier-friendly routing layer

What touch-browser Is Not

• a universal truth oracle
• a generic crawler replacement
• a guarantee that every unsupported claim is false

MCP Example

Minimal MCP bridge setup from the repository root:

{
  "mcpServers": {
    "touch-browser": {
      "command": "node",
      "args": ["integrations/mcp/bridge/index.mjs"]
    }
  }
}

The bridge starts touch-browser serve underneath and exposes tools like tb_search, tb_search_open_top, tb_open, tb_read_view, tb_extract, tb_tab_open, and tb_session_synthesize.

The standalone bundle ships touch-browser serve. The checked-in MCP bridge launcher remains a repository integration asset and is run from a repo checkout or container image, not from the installed standalone command alone.

By default the bridge prefers an explicit TOUCH_BROWSER_SERVE_COMMAND, then an explicit binary path, then an installed or packaged touch-browser binary, then repo-local target/{release,debug} binaries. If none are available, it fails fast with an install/build instruction instead of dropping back to cargo run.

Use TOUCH_BROWSER_SERVE_COMMAND if you want to force a specific built binary or wrapper command.

Architecture

Query / URL / fixture / browser tab
  -> browser-first search result parsing
  -> Acquisition
  -> Observation compiler
  -> read-view / compact-view
  -> extract (evidence + citations + optional verifier)
  -> policy
  -> session synthesis / replay
  -> CLI / JSON-RPC serve / MCP

Docs And Proof

• quick start and operations: doc/INSTALL_AND_OPERATIONS.md
• command surface: doc/CLI_SURFACE_SPEC.md
• evidence operating model: doc/EVIDENCE_OPERATING_MODEL.md
• examples: examples/README.md
• integrations: integrations/README.md
• benchmarks and positioning: doc/README.md
• pilot and operations package: doc/PILOT_PACKAGE_SPEC.md, doc/OPERATIONS_SECURITY_PACKAGE_SPEC.md

License

This repository now uses MPL-2.0.

• commercial and non-commercial use are allowed
• if you distribute modified MPL-covered files, those covered files stay under MPL-2.0
• separate files in a larger work can use different terms
• full legal text: LICENSE
• plain-language policy: LICENSE-POLICY.md