🌐 ChromeTether

Dual-tier web browsing & live Chrome automation toolkit for AI coding assistants and autonomous agents via Model Context Protocol (MCP).

ChromeTether equips your AI agents (ZCode, OpenCode, Claude Code, Claude Desktop, Cursor, Windsurf, Cline, DeepSeek Harness/dsh, Antigravity) with a dual-tier web browsing system:

1. Tier 1 (Fast Reader): Instant HTTP fetching and Markdown conversion (~150ms, 0MB RAM) for static docs, blogs, and search without starting a browser.
2. Tier 2 (Live Chrome Attachment): Direct Chrome DevTools Protocol (CDP) control attaching to your currently open Google Chrome tabs via --auto-connect. No unwanted blank windows, no session loss, and full preservation of your logged-in accounts.

---

🌟 Architecture & Core Features

flowchart TD
    User["Your Prompt / Web Request"] --> Agent["AI Agent (ZCode, OpenCode, Claude, Cursor)"]
    Agent --> Decision{"What is the goal?"}
    
    Decision -- "Docs, Static Articles, GitHub, Web Search" --> Tier1["Tier 1: Fast Reader (tether-reader)"]
    Tier1 --> Res1["HTTP GET + Cheerio + Turndown\n(~150ms, 0MB Chrome RAM)"]
    
    Decision -- "Dynamic SPAs, Forms, Clicks, Live Tabs, Debugging" --> Tier2["Tier 2: Live Chrome (chrome-devtools)"]
    Tier2 --> Res2["Chrome DevTools Protocol (CDP)\n(Accessibility Tree UID, Screenshots, Network, Console)"]

Loading

1. Dual-Tier Workflow

Tier	Tools	Underlying Engine	Best Used For
Tier 1: Fast Reader	read_url_content, search_web	Lightweight HTTP GET + Cheerio + Turndown + DuckDuckGo	Reading documentation, API specs, blogs, GitHub issues/READMEs, and organic search. Runs in ~150ms with zero browser overhead.
Tier 2: Live Chrome	chrome-devtools (navigate_page, click, fill, take_snapshot, take_screenshot, list_console_messages, list_network_requests)	Official Google Chrome DevTools Protocol via chrome-devtools-mcp	Dynamic SPAs (React, Next.js, Vue), web apps, filling forms, submitting data, inspecting UI, diagnosing console errors, and capturing screenshots.

2. Live Chrome Attachment (--auto-connect)

Unlike other tools that spawn isolated, blank browser profiles every time, ChromeTether defaults to --auto-connect:

• Attaches directly to your active, currently running Google Chrome window.
• Works with your already logged-in accounts (GitHub, AWS, Jira, internal dashboards).
• Inspects and automates the exact tabs you have in front of you.

3. Token-Efficient Interaction (uid)

• Avoids context-window blowouts caused by dumping raw HTML.
• Uses Chrome's Accessibility Tree where every interactive button, input, and link is assigned a numeric uid (e.g. [uid: 10] button "Submit").
• The AI interacts with 100% precision: fill(14, "value") and click(10).

4. Application Map (tether-map)

The installer also registers tether-map, a local MCP server for building a reusable map of an application while an agent explores it in Chrome. It groups observed requests by method and URL path (for example, /api/orders/123 and /api/orders/456 become GET /api/orders/{id}), then records status codes, query parameter names, and the page where each endpoint was seen.

Ask your agent: “Map the pages and API requests you observe while exploring https://app.example.com.” The workflow is:

1. start_app_map(target_url); include allowed_origins if the application uses a separate API origin.
2. Navigate with chrome-devtools, then call record_app_page(page_url, title) for visited pages.
3. Call Chrome DevTools list_network_requests({includePreservedRequests: true}) and pass the observed URL, method, status, and resource type to record_app_requests(page_url, requests). Calls accept up to 200 requests.
4. Call get_app_map({kind: "api"}) to focus on API endpoints. Use endpoint_offset, page_offset, and limit to page through the saved map (50 items per group by default, at most 100).

This first version relies on the agent to pass Chrome observations to tether-map; it does not intercept traffic automatically. Only explicitly allowed origins are recorded. Request bodies, headers, cookies, URL query values, and fragments are not saved. The map defaults to ~/.chrometether/app-map.json (override with CHROMETETHER_MAP_FILE before starting the MCP server). start_app_map replaces the existing map at that path.

---

🚀 1-Click Installation

Option 1: PowerShell Script (Windows)

Clone the repository and run:

git clone https://github.com/toannguyen3107/chrometether.git
cd chrometether
npm install
.\scripts\setup.ps1

Option 2: CLI Command (Cross-Platform)

git clone https://github.com/toannguyen3107/chrometether.git
cd chrometether
npm install

# Check status of detected agent environments
node bin/chrometether.js status

# Automatically configure all detected agents
node bin/chrometether.js install all

# Or install for a specific agent
node bin/chrometether.js install zcode
node bin/chrometether.js install opencode
node bin/chrometether.js install claude-code
node bin/chrometether.js install claude-desktop
node bin/chrometether.js install cursor
node bin/chrometether.js install windsurf
node bin/chrometether.js install cline
node bin/chrometether.js install dsh
node bin/chrometether.js install antigravity

---

⚙️ Enabling Remote Debugging in Google Chrome (One-Time Setup)

To allow ChromeTether to safely attach to your running Chrome tabs, enable remote debugging:

Method A (Recommended)

1. Open Google Chrome.
2. Navigate to: chrome://inspect/#remote-debugging
3. Check the box: "Enable remote debugging" (or "Discover network targets").

Method B (Command Line / Shortcut)

Launch Chrome with the remote debugging flag:

chrome.exe --remote-debugging-port=9222

---

🤖 Supported Agent Integrations

Agent	Config File	Features Added
ZCode (Z.ai)	~/.zcode/cli/config.json	Registers chrome-devtools, tether-reader, and tether-map. Installs /browser slash command and browser skills.
OpenCode CLI	~/.config/opencode/opencode.jsonc	Merged using OpenCode MCP array schema with --auto-connect.
Claude Code CLI	~/.claude.json	MCP configuration + installs browser skills in ~/.claude/skills/.
Claude Desktop	claude_desktop_config.json	MCP configuration with --auto-connect.
Cursor IDE	~/.cursor/mcp.json	Cursor MCP server registration.
Windsurf (Codeium)	~/.codeium/windsurf/mcp_config.json	Cascade MCP server registration.
Roo Code / Cline	cline_mcp_settings.json	VS Code extension MCP configuration.

---

🧪 Verification & Diagnostics

Run the comprehensive health check:

npm test

Tests:

• Fast Reader HTML-to-Markdown conversion.
• DuckDuckGo organic search without API keys.
• tether-reader Stdio MCP protocol initialization.
• tether-map Stdio MCP protocol initialization.
• chrome-devtools Stdio MCP protocol initialization.

Run npm run test-map for the offline application-map tests and npm run test-merger for installer configuration tests.

---

🔒 Security & Privacy

• Safe Merging: The installer creates automatic timestamped .bak backups before modifying any configuration file, preserving all your pre-existing MCP servers.
• No Telemetry / No Cloud Relays: All MCP communication occurs over local Stdio.
• No API Keys Required: Fast web search runs through DuckDuckGo public search without requiring any third-party API tokens.

---

📄 License

MIT License © 2026 Toan Nguyen