ThinkRun

llms.txt

Local Mode

Control your real desktop Chrome browser instead of a cloud Playwright instance. Useful for debugging, testing with logged-in sessions, or accessing browser extensions.

Architecture

Local mode uses a native messaging host that Chrome auto-launches when the extension connects. The host serves HTTP on a local port — clients discover it automatically via a port file.

┌─────────────┐       ┌──────────────────┐       ┌───────────────┐
│ thinkrun CLI│ HTTP  │  Native Host     │ stdio │    Chrome     │
│ / MCP Server│──────>│ (auto-discovered)│<─────>│   Extension   │
│ curl / SDK  │       └──────────────────┘       └───────┬───────┘
└─────────────┘              │                           │
                      Routes commands             Executes actions
                      via X-Tab-Id header         in real browser tabs

Chrome auto-launches the native host binary. It writes its port to ~/.thinkbrowse/port. All clients (CLI, MCP server) read this file automatically.

Setup

1. Install the Chrome extension

Install from the Chrome Web Store, or for development: go to chrome://extensions, enable Developer Mode, click "Load unpacked", and select the extension/dist directory.

2. Set up the native host

Run the MCP setup commands, or use thinkrun setup if you installed the CLI. Chrome will auto-launch the native host when the extension connects — no server to manage. The install command writes native-host files and browser native-messaging registration under your user profile.

npx @thinkrun/mcp doctor
npx @thinkrun/mcp install-native-host
npx @thinkrun/mcp doctor

3. Verify the connection

curl http://localhost:$(cat ~/.thinkbrowse/port)/health
# → { "extensionConnected": true, "connectedTabs": 3, ... }

Using Local Mode

All commands work the same in local and cloud mode — the thinkrun CLI auto-detects the mode and routes to the native host or cloud API accordingly.

thinkrun (CLI)

# Same commands work in both local and cloud mode
thinkrun tabs
thinkrun attach <tabId>
thinkrun navigate "https://example.com"
thinkrun snapshot
thinkrun click "button.submit"
thinkrun release

See the section for the full command reference.

MCP Server (for AI agents)

npx @thinkrun/mcp doctor
npx @thinkrun/mcp --mode local

Run doctor before adding the server to Claude Desktop or any MCP-compatible client. See the MCP package for config examples.

Mode Auto-Detection

All clients (CLI, MCP server) auto-detect the mode in this order:

  1. THINKRUN_LOCAL=true env var → local mode
  2. Native host responding (port auto-discovered from ~/.thinkbrowse/port) → local mode
  3. API key available (env var or config file) → cloud mode