# ThinkRun LLM Docs

> Canonical machine-readable docs for agents and LLM-integrated tooling.

Version: 1.5
Last-Updated: 2026-06-25

## What ThinkRun Is

ThinkRun is a screen recorder + browser-control surface for AI coding agents.
Record a browser session once and ThinkRun structures it — video, actions, DOM,
console/network, transcript, and AI analysis — into a portable artifact your AI
coding agent (Cursor, Claude Code, Codex) can read directly. Three value modes:

- Record feedback → your agent fixes it (stop typing paragraphs to explain a bug).
- Record a demonstration → the local CLI follows it as instructions (show, don't type).
- Let your agent record its own work → review what it did.

Surfaces: web app + in-page recorder, browser extension, typed CLI (`thinkrun`),
and an MCP server that uses your real logged-in Chrome session.

## Public URLs

- Docs: https://thinkrun.ai/docs
- Blog: https://thinkrun.ai/blog
- LLM docs: https://thinkrun.ai/llms.txt
- API base: https://api.thinkrun.ai

## Product Surfaces

- Cloud API sessions (REST): create sessions, run browser actions, capture artifacts
- Local bridge sessions (extension/native-host): local browser automation via localhost bridge
- Typed CLI: `thinkrun`
- Compatibility CLI: `browse`

## Share Links

Any ThinkRun share URL has three representations at the same path:

- Browser:   `https://thinkrun.ai/s/<token>`          — SPA with OG tags
- JSON:      `https://thinkrun.ai/s/<token>.json`     — agent-readable bundle
- Markdown:  `https://thinkrun.ai/s/<token>.md`       — LLM-context-efficient (~500 tokens)

Both JSON and Markdown are also served via Accept-header content negotiation:

```bash
curl -H 'Accept: application/json' https://thinkrun.ai/s/<token>
curl -H 'Accept: text/markdown'    https://thinkrun.ai/s/<token>
```

Every response includes a `Link:` header advertising the alternates
(`rel="alternate"`, `rel="describedby"`, `rel="canonical"`) so agents that
inspect headers can discover the bundle without knowing ThinkRun's API.

Password-protected shares require `x-share-password: <pw>` (plaintext over
HTTPS, verified server-side against a bcrypt hash). Rate-limited at 5 attempts
per 15 minutes per IP.

Bundle schema and full endpoint list: `GET /api/share/<token>/bundle`
(public, anonymous access; pass `x-api-key: <key>` for owner-level fields).

## Key Concepts

- Session-first model: actions require an active session
- Three execution modes:
  - Local mode (free — Chrome + ThinkRun extension + native host bridge, no API key required)
  - Extension Agent (credits — AI task dispatched from extension UI or REST API, not CLI)
  - Cloud Browser (credits — remote Playwright browser via `thinkrun cloud start`)
- Local mode setup: `npm install -g @thinkrun/cli && thinkrun setup` — no account required
- Artifacts and action logs are attached to sessions for replay and collaboration

## CLI Essentials

```bash
# Install (one-time)
npm install -g @thinkrun/cli
thinkrun setup              # downloads native host binary — no API key required for local mode

# Local mode (free — uses your own Chrome + ThinkRun extension)
thinkrun tabs               # list open tabs
thinkrun attach <tabId>     # attach to a tab
thinkrun navigate https://example.com
thinkrun click "button.submit"
thinkrun snapshot

# Cloud mode (optional — requires API key)
thinkrun config set-key tb_your_api_key
thinkrun cloud start
thinkrun navigate https://example.com

# Diagnose setup
thinkrun doctor             # bridge health + API-key health (missing/malformed/rejected); --offline skips network checks
```

## Local Mode (Native Host)

Requires native host running locally. Use `thinkrun doctor` to confirm.

```bash
# Recommended: create an isolated session (opens its own background Chrome window)
SID=$(bash scripts/browse.sh session-create)
bash scripts/browse.sh goto $SID "https://example.com"
bash scripts/browse.sh snapshot $SID
bash scripts/browse.sh session-delete $SID
```

To attach to an existing tab instead (no isolation — shares user's window):
```bash
thinkrun attach <tabId>
thinkrun snapshot
```

Window isolation: `session-create` opens an unfocused Chrome window per agent. Multiple agents
can browse simultaneously without normally interfering with each other or the user's browsing.

## Local Backend (Dev Mode)

For contributors running `mech-browser-service` locally:

```bash
thinkrun config set apiUrl http://localhost:3009
thinkrun config set-key ak_your_local_test_key   # from mech-browser-service/.env
thinkrun cloud start
thinkrun navigate http://localhost:3000
```

## Notes For Agents

- Always confirm session state before action execution.
- On auth errors, verify API URL first, then key type expected by that endpoint.
- Prefer `thinkrun doctor` when mode/auth/bridge state is ambiguous.
- If `thinkrun doctor` prints "False circuit-breaker trip", run `thinkrun reset-connection` — re-arms the native-host circuit breaker without reloading the extension. Safe to call when already connected (idempotent, exit 0).
- In local mode, prefer `session-create` (opens isolated window) over `attach` (shares user's window).
- Multiple agents can run concurrently — each gets its own window, no focus conflicts.

## Error codes & recovery (local)

- Human-readable docs: **https://thinkrun.ai/docs**
- This file (LLM-oriented): **https://thinkrun.ai/llms.txt**
- If you see `TAB_OWNED_BY_OTHER_SESSION` in local mode: stay local when no API key; run `thinkrun session debug --json`; avoid re-attach if already bound; use `thinkrun new-window` or `thinkrun release` as needed. Repository reference: `docs/ERROR_CODES.md`.

## Share API (public — no auth required)

Share links expose recordings and sessions as machine-readable bundles.

### Get full share bundle
```
GET /api/share/:token/bundle
Accept: application/json
```
Returns a share bundle payload that the `/s/:token.json` edge export normalizes into the public `thinkrun.share` contract.
- Canonical public fields exposed by `/s/:token.json` include:
  - `artifactType`, `schemaVersion`
  - `context`, `evidence`, `analysis`, `review`, `artifacts`
  - `claims[]` with `id`, `kind`, `title`, `description`, `verdict`, `confidence`, `evidenceRefs`, and optional `recommendedAction`
  - `evidenceCoverageByClaim`
- Claims are conservative by design:
  - narration-only evidence stays `narrated_only`
  - runtime- or screenshot-backed claims can rise to `mixed_support` or `confirmed`
  - contradictions are surfaced explicitly rather than smoothed into a summary
- Artifact availability is explicit. Consumers should rely on `artifacts.*.available` / `kind` rather than inferring absence from missing arrays.
- Password-protected shares require header: `x-share-password: <password>`
- Authenticated owners receive additional owner-level fields
- Rate limit: 20 req/min per IP

### Content negotiation shortcut
```
GET /s/:token
Accept: application/json   →  same as GET /api/share/:token/bundle
Accept: text/html          →  SPA viewer (default browser behavior)
```

### Canonical agent flow for public shares

1. Fetch `/s/:token.json`
2. Inspect `claims[]` and `evidenceCoverageByClaim` first
3. Use `analysis` as a compact summary, not as stronger proof than the cited evidence
4. Follow `context.agentInstructions.recommendedConsumptionOrder`

### Other share endpoints
```
GET  /api/share/:token/meta                          # metadata only (title, duration, passwordRequired)
GET  /api/share/:token/video[?vt=<token>]            # video/webm stream, supports Range
GET  /api/share/:token/screenshots/:objectId[?vt=]   # image proxy
POST /api/share/:token/video-auth                    # { password } → { videoToken, expiresAt }
```