ThinkRun

Setup

Mode is auto-detected: if the native host is running (Chrome must be open with the extension), it uses local mode. Otherwise it falls back to cloud mode with an API key.

# Cloud mode
export THINKRUN_API_KEY=your-api-key

# Local mode (auto-detected if native host is running)
# Just open Chrome with the ThinkRun extension — no server to start
export THINKRUN_LOCAL=true  # optional: force local mode

Dependencies: curl, jq

If using the typed CLI against a local mech-browser-service endpoint, use that server's TEST_API_KEY and run thinkrun doctor for diagnostics.

Environment Variables

Config file: ~/.config/thinkrun/config.json (alternative to env vars for API key)

Session Management

Navigation

Observation

Interaction

Tab Management (Local Mode)

Screenshot captions: when a local tab is synced to ThinkRun, thinkrun screenshot requires --caption <text> so the dashboard shows the intended meaning of the capture.

Tab targeting without attach: All action commands accept -t/--tab <tabId> to target a specific Chrome tab directly without running attach first. Priority: --tab flag > THINKRUN_TAB_ID env var > agent-scoped working-location file (from attach, under ~/.thinkrun/working-locations/<agentId>.json). Lock safety: commands are blocked if another live agent owns the tab.

Recovery contract: If the remembered tab was closed, commands fail with TAB_NOT_FOUND and clear stale continuity so the next step is thinkrun tabs followed by thinkrun attach <tabId>. If ownership looks inconsistent, run thinkrun session debug --json before re-attaching so you can distinguish a same-controller repair from a true foreign-owner block.

Agent Identity

Run once per agent before the first attach or new-window call. The generated agentId (prefixed agt_) is persisted to ~/.thinkrun/agent.json and used for tab lock ownership and the Activity Feed.

Alternative: set THINKRUN_AGENT_ID=agt_... to override the file-based identity.

Retry Behavior

Both modes automatically retry transient errors with exponential backoff (1s, 2s, 4s).

Local Workflow Recovery

Example Workflow

# Create session and navigate
SID=$(browse session-create)
browse goto "$SID" "https://example.com"

# Observe
browse snapshot "$SID"
browse extract "$SID" text

# Interact
browse click "$SID" "a[href]"
browse fill "$SID" "input[name=q]" "search term"
browse press "$SID" "Enter"

# Clean up
browse session-delete "$SID"

Agent / CI Mode (--json)

Pass --json or pipe stdout to get machine-readable NDJSON output. JSON mode auto-enables when stdout is not a TTY (piped or redirected).

# Success → stdout:
{"success":true,"command":"navigate","durationMs":842,"data":{"url":"https://example.com","title":"Example"}}

# Error → stderr (exit 1):
{"success":false,"command":"click","error":"Element not found","code":"ELEMENT_NOT_FOUND","hint":"Run: thinkrun snapshot","retryable":true}

AI Tasks (Local Mode)

Delegate multi-step tasks to the native host AI loop. Requires an active local tab session.

Run thinkrun attach <tabId> before using task commands.

Quick Setup

# Installation
npm install -g @thinkrun/cli

# Cloud setup
thinkrun config set apiKey YOUR_KEY
thinkrun doctor

# Cloud session
thinkrun cloud start
thinkrun navigate https://example.com
thinkrun snapshot
thinkrun cloud stop

# Local session (optional: persist agent identity first)
thinkrun agent-init --name "my-agent"   # generates agt_ id, registers with cloud
thinkrun tabs
thinkrun attach <tabId>
thinkrun navigate https://example.com
thinkrun screenshot --caption "Sign-in page before entering credentials"
thinkrun task "click the Sign In button"
thinkrun release                        # releases lock + closes cloud session

# Target a specific tab without attach (--tab flag)
thinkrun navigate --tab 656849988 https://example.com
thinkrun screenshot --tab 656849988 --caption "Top story on Hacker News" --output /tmp/shot.png
# Or set once for the shell session:
export THINKRUN_TAB_ID=656849988

Page Cache (Stateless)

Fetch HTML, extract text, or capture a screenshot for any URL without creating a browser session. Cloud mode consumes credits (HTML/text: 1, screenshot: 3). Local mode is free. Force local-only with --sensitive to prevent third-party fetches.

# Installed package
thinkrun cache html https://example.com
thinkrun cache html https://example.com --provider local

# Extract plain text
thinkrun cache text https://example.com

# Capture screenshot
thinkrun cache screenshot https://example.com --full-page --max-dimension 1920
thinkrun cache screenshot https://example.com --provider cloud

# From repo (development)
bun run packages/cli/bin/thinkrun.ts cache html https://example.com
bun run packages/cli/bin/thinkrun.ts cache screenshot https://example.com --full-page

# Common options (all subcommands)
#  --provider cloud|local   provider selection (default: cloud when billing is configured)
#  --sensitive              force local-only (URL not sent to third parties)
#  --timeout <ms>           navigation timeout (default: 30000, max: 60000)
#  --wait-for <value>       load | domcontentloaded | networkidle | positive ms
#  --full-page              full scrollable page capture (screenshot only)
#  --max-dimension <px>     resize longest edge to N pixels (screenshot only)