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, ... }

Windows setup

Local mode works on Windows 10 and 11 with Chrome, Edge, Brave, or Vivaldi. You do not need an administrator account: everything installs under your own user profile. Run these steps in PowerShell.

1. Install the prerequisites

Install Node.js LTS (which includes npm) and add the ThinkRun extension from the Chrome Web Store. Edge, Brave, and Vivaldi can install from the same store listing.

2. Install the CLI and register the native host

npm install -g @thinkrun/cli
thinkrun setup

thinkrun setup downloads the native host (about 110 MB), verifies its checksum, and registers it for every supported browser it finds. On Windows the registration is a registry key under HKCU\Software\...\NativeMessagingHosts plus a manifest file in %APPDATA%. The binary lives at %USERPROFILE%\.thinkbrowse\bin\thinkbrowse-host.exe. Setup also asks for an API key; local mode does not need one, so you can skip it and add one later with thinkrun config set-key.

3. Restart the browser and verify

Browsers read native-messaging registrations at startup, so close and reopen Chrome after setup if it was already running. Then run doctor.

thinkrun doctor
# Look for:
#   ✓ Bridge health: thinkbrowse-native-host (extensionConnected=true, ...)
#   - Manifest: N/A (Windows — registry-based)   <- expected on Windows

# Optional: confirm the registration and the bridge directly
reg query "HKCU\Software\Google\Chrome\NativeMessagingHosts\com.thinkbrowse.host"
Invoke-RestMethod "http://localhost:$(Get-Content ~\.thinkbrowse\port)/health"

4. Attach and drive a tab

thinkrun tabs
thinkrun attach <tabId>
thinkrun navigate "https://example.com"
thinkrun screenshot --output page.png
thinkrun release

Troubleshooting on Windows

  • EXTENSION_NOT_CONNECTED: the browser must be open with the ThinkRun extension enabled. Restart the browser once after thinkrun setup.
  • reg query reports the key is missing: rerun thinkrun setup --force. Setup only registers browsers it detects, so install the browser first.
  • Managed devices: a NativeMessagingBlocklist or ExtensionInstallBlocklist policy from your organization prevents the host from starting. Check chrome://policy.
  • The port file is at %USERPROFILE%\.thinkbrowse\port; if the number changes after a browser restart, doctor picks up the new value.

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