{"id":48696704,"url":"https://github.com/nangman-infra/touch-browser","last_synced_at":"2026-04-25T19:01:04.786Z","repository":{"id":349263292,"uuid":"1201312599","full_name":"nangman-infra/touch-browser","owner":"nangman-infra","description":"Turn any web page into traceable, citable evidence for AI agents.","archived":false,"fork":false,"pushed_at":"2026-04-22T03:52:11.000Z","size":2027,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-22T06:02:59.675Z","etag":null,"topics":["ai-agent","browser-automation","citation","evidence-extraction","fact-checking","mcp","nlp","rust","self-hosted","web-scraping"],"latest_commit_sha":null,"homepage":"https://nangman.cloud","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/nangman-infra.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-04T14:03:34.000Z","updated_at":"2026-04-22T03:28:47.000Z","dependencies_parsed_at":null,"dependency_job_id":"ac09badf-bbaf-403e-a972-4f360b49d855","html_url":"https://github.com/nangman-infra/touch-browser","commit_stats":null,"previous_names":["nangman-infra/touch-browser"],"tags_count":15,"template":false,"template_full_name":null,"purl":"pkg:github/nangman-infra/touch-browser","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nangman-infra%2Ftouch-browser","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nangman-infra%2Ftouch-browser/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nangman-infra%2Ftouch-browser/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nangman-infra%2Ftouch-browser/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nangman-infra","download_url":"https://codeload.github.com/nangman-infra/touch-browser/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nangman-infra%2Ftouch-browser/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32273223,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-25T18:29:39.964Z","status":"ssl_error","status_checked_at":"2026-04-25T18:29:32.149Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-agent","browser-automation","citation","evidence-extraction","fact-checking","mcp","nlp","rust","self-hosted","web-scraping"],"created_at":"2026-04-11T08:10:14.502Z","updated_at":"2026-04-25T19:01:04.746Z","avatar_url":"https://github.com/nangman-infra.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# touch-browser\n\n![Terminal demo](demo/terminal-demo.gif)\n\n[![License: MPL-2.0](https://img.shields.io/badge/license-MPL--2.0-brightgreen.svg)](LICENSE)\n[![Status: pilot-ready](https://img.shields.io/badge/status-pilot--ready-2d7d46.svg)](doc/RELEASE_READINESS_SPEC.md)\n\nAsk a claim. Get page-grounded evidence, verdicts, and citations.\n\n`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.\n\nUse it when you need:\n\n- source-linked evidence instead of raw HTML dumps\n- support snippets and verdict explanations that an agent can inspect before answering\n- a safe unresolved path for borderline claims instead of bluffing\n- policy-gated browsing instead of blind automation\n- replayable, auditable multi-page research sessions\n\nEvidence-first, not fact-final:\n\n- `touch-browser` helps an AI collect page-local evidence and trace where it came from\n- a higher-level model or human still decides what is true across pages or across the wider world\n\n## What `extract` Returns\n\nAbbreviated `claimOutcome` shape from the current extractor:\n\n```json\n{\n  \"statement\": \"The Starter plan costs $29 per month.\",\n  \"verdict\": \"evidence-supported\",\n  \"confidenceBand\": \"high\",\n  \"reviewRecommended\": false,\n  \"supportSnippets\": [\n    {\n      \"blockId\": \"b4\",\n      \"stableRef\": \"rmain:table:plan-monthly-price-snapshots-starter-29-10-000-t\",\n      \"snippet\": \"Starter | $29 | 10,000\"\n    }\n  ],\n  \"verdictExplanation\": \"Matched direct support in 3 page block(s). Review the attached snippets before reusing the claim.\"\n}\n```\n\nThe extractor returns four verdicts:\n\n- `evidence-supported`: the current page surfaced usable support\n- `contradicted`: the current page surfaced conflicting evidence\n- `insufficient-evidence`: the current page did not provide enough direct support\n- `needs-more-browsing`: the current page is not specific enough yet, so the next step is another page\n\n`confidenceBand`, `reviewRecommended`, `supportSnippets`, `verdictExplanation`, and `matchSignals` are there so an agent can decide what to do next without blindly trusting the first match.\n\n## MCP Package\n\nPrimary local-host MCP path:\n\n- npm package: `@nangman-infra/touch-browser-mcp`\n- scope: public docs and research web\n- MCP contract: headless-only, automatic search-engine selection, supervised recovery handoff for challenge/auth/MFA\n\nRecommended host config:\n\n```json\n{\n  \"mcpServers\": {\n    \"touch-browser\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nangman-infra/touch-browser-mcp\"]\n    }\n  }\n}\n```\n\nOn first launch, the package downloads the matching standalone runtime bundle from [GitHub Releases](https://github.com/nangman-infra/touch-browser/releases), verifies the published `.sha256`, installs it under `~/.touch-browser/npm-mcp/versions/`, and then starts `touch-browser mcp`.\n\nUse this package when you want a local MCP host such as Claude Desktop, Cursor, or Codex to attach without a separate manual runtime install.\n\n## Standalone Bundle\n\nTagged `v*` pushes now build standalone macOS and Linux bundles in the `Standalone Release` workflow. Each bundle includes:\n\n- `bin/touch-browser`\n- the optimized Rust binary under `runtime/touch-browser-bin`\n- a bundled Node runtime and Playwright adapter\n- the default semantic runner scripts and model cache\n\nWhen a tagged release is published, download the matching tarball from [GitHub Releases](https://github.com/nangman-infra/touch-browser/releases), unpack it, and run:\n\n```bash\n./touch-browser-\u003cversion\u003e-\u003cplatform\u003e-\u003carch\u003e/install.sh\ntouch-browser telemetry-summary\ntouch-browser update --check\n```\n\nTo build the same portable bundle locally:\n\n```bash\npnpm install --frozen-lockfile\npnpm run build:standalone-bundle -- v0.1.0-rc1\n\n# Then install the bundled command into PATH\n./dist/standalone/touch-browser-v0.1.0-rc1-\u003cplatform\u003e-\u003carch\u003e/install.sh\ntouch-browser telemetry-summary\ntouch-browser update --check\n```\n\nThe standalone path is still the official CLI, operations, offline, and fallback install path:\n\n1. unpack a standalone bundle\n2. run `install.sh`\n3. use the installed `touch-browser` command for every CLI and serve operation\n\nThe installer now performs a managed install:\n\n- managed versions live under `~/.touch-browser/install/versions/\u003cbundle-name\u003e`\n- the active version is `~/.touch-browser/install/current`\n- the PATH command points at `~/.touch-browser/install/current/bin/touch-browser`\n- `touch-browser update` swaps `current` to a newly verified release bundle\n- `touch-browser uninstall --purge-all --yes` removes the managed install and all stored data\n\n## First Run\n\nThis is the command-only proof path that matches the installed user experience:\n\n```bash\ntouch-browser open https://www.iana.org/help/example-domains --browser --session-file /tmp/tb-first-run.json\ntouch-browser session-read --session-file /tmp/tb-first-run.json --main-only\ntouch-browser session-extract --session-file /tmp/tb-first-run.json \\\n  --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.\"\ntouch-browser session-synthesize --session-file /tmp/tb-first-run.json --format markdown\ntouch-browser session-close --session-file /tmp/tb-first-run.json\n```\n\nInstalled search now keeps an engine-level persistent trust profile by default:\n\n- Google: `~/.touch-browser/browser-search/profiles/google-default`\n- Brave: `~/.touch-browser/browser-search/profiles/brave-default`\n- profile state metadata: `~/.touch-browser/browser-search/\u003cengine\u003e.profile-state.json`\n\n## Contributor Build From Source\n\nPrerequisites: [rustup](https://rustup.rs), Node.js 18+, `pnpm`.\n\n```bash\nbash scripts/bootstrap-local.sh\ncargo build --release -p touch-browser-cli\npnpm run build:standalone-bundle -- local-dev\n./dist/standalone/touch-browser-local-dev-\u003cplatform\u003e-\u003carch\u003e/install.sh\n```\n\nSource checkout is a contributor workflow. Release and operations docs still assume the installed `touch-browser` command from the standalone bundle.\n\n`bootstrap-local.sh` installs the default semantic models under:\n\n- `~/.touch-browser/models/evidence/embedding`\n- `~/.touch-browser/models/evidence/nli`\n\nUse `TOUCH_BROWSER_EVIDENCE_EMBEDDING_MODEL_PATH` or `TOUCH_BROWSER_EVIDENCE_NLI_MODEL_PATH` only when you need to override those default locations.\n\n## Why Not Markdown Alone?\n\n`touch-browser` is not trying to replace every crawler or browser tool. Its job starts after page acquisition.\n\n| Need | Markdown-only fetch | touch-browser |\n| --- | --- | --- |\n| Read the page | yes | yes |\n| Keep source-linked block refs | partial | yes |\n| Judge whether the page supports a claim | no | yes |\n| Return contradiction and unresolved states | no | yes |\n| Give support snippets and verdict explanations | no | yes |\n| Tell the agent to escalate instead of answering | no | yes |\n\n## Product Surface\n\nPrimary surface:\n\n- `extract`: verify claims against the current page and return structured claim outcomes\n\nSupporting read surfaces:\n\n- `read-view`: readable Markdown for a human reviewer or verifier model\n- `compact-view`: low-token semantic state for agent loops\n- `search`: structured discovery before opening candidate pages\n\nSafety and audit surfaces:\n\n- `policy`: classify pages and actions as allow, review, or block\n- `session-synthesize`: turn a multi-page session into JSON or Markdown with citations\n- `serve`: expose the runtime over stdio JSON-RPC for MCP or agent integration\n\n## What touch-browser Is\n\n- an evidence-first extractor\n- a selective prediction surface\n- a verifier-friendly routing layer\n\n## What touch-browser Is Not\n\n- a universal truth oracle\n- a generic crawler replacement\n- a guarantee that every unsupported claim is false\n\n## MCP Example\n\nRecommended MCP setup for local hosts:\n\n```json\n{\n  \"mcpServers\": {\n    \"touch-browser\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@nangman-infra/touch-browser-mcp\"]\n    }\n  }\n}\n```\n\nThe MCP package is intentionally narrower than the full CLI:\n\n- scope is public docs and research web\n- recommended loop is `tb_search -\u003e tb_search_open_top -\u003e tb_read_view -\u003e tb_extract`\n- `engine` is not exposed over MCP\n- `headed` is not exposed over MCP\n- if the page indicates challenge, auth, MFA, or other supervised recovery, stop and hand off to a human instead of retrying with different browser settings\n\nAlternative MCP bridge setup for an installed standalone command:\n\n```json\n{\n  \"mcpServers\": {\n    \"touch-browser\": {\n      \"command\": \"touch-browser\",\n      \"args\": [\"mcp\"]\n    }\n  }\n}\n```\n\nThe 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`.\n\nRepository checkout integration asset:\n\n```json\n{\n  \"mcpServers\": {\n    \"touch-browser\": {\n      \"command\": \"node\",\n      \"args\": [\"integrations/mcp/bridge/index.mjs\"]\n    }\n  }\n}\n```\n\nThe standalone bundle ships `touch-browser mcp` and `touch-browser serve`. The checked-in Node launcher remains a repository integration asset for repo checkouts or container images.\n\nBy 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`.\n\nUse `TOUCH_BROWSER_SERVE_COMMAND` if you want to force a specific built binary or wrapper command.\n\n## Architecture\n\n```text\nQuery / URL / fixture / browser tab\n  -\u003e browser-first search result parsing\n  -\u003e Acquisition\n  -\u003e Observation compiler\n  -\u003e read-view / compact-view\n  -\u003e extract (evidence + citations + optional verifier)\n  -\u003e policy\n  -\u003e session synthesis / replay\n  -\u003e CLI / JSON-RPC serve / MCP\n```\n\n## Docs And Proof\n\n- quick start and operations: [doc/INSTALL_AND_OPERATIONS.md](doc/INSTALL_AND_OPERATIONS.md)\n- command surface: [doc/CLI_SURFACE_SPEC.md](doc/CLI_SURFACE_SPEC.md)\n- evidence operating model: [doc/EVIDENCE_OPERATING_MODEL.md](doc/EVIDENCE_OPERATING_MODEL.md)\n- npm MCP package: [packages/mcp/README.md](packages/mcp/README.md)\n- examples: [examples/README.md](examples/README.md)\n- integrations: [integrations/README.md](integrations/README.md)\n- benchmarks and positioning: [doc/README.md](doc/README.md)\n- pilot and operations package: [doc/PILOT_PACKAGE_SPEC.md](doc/PILOT_PACKAGE_SPEC.md), [doc/OPERATIONS_SECURITY_PACKAGE_SPEC.md](doc/OPERATIONS_SECURITY_PACKAGE_SPEC.md)\n\n## License\n\nThis repository now uses `MPL-2.0`.\n\n- commercial and non-commercial use are allowed\n- if you distribute modified MPL-covered files, those covered files stay under `MPL-2.0`\n- separate files in a larger work can use different terms\n- full legal text: [LICENSE](LICENSE)\n- plain-language policy: [LICENSE-POLICY.md](LICENSE-POLICY.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnangman-infra%2Ftouch-browser","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnangman-infra%2Ftouch-browser","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnangman-infra%2Ftouch-browser/lists"}