# thinkpool-pair > Connect Claude Code, Codex, or Hermes on your computer to a thinkpool Code room. Latest version **0.7.469** (published 2026-10-14) · SEE LICENSE IN LICENSE license · 0 weekly downloads ## Install ```sh npm install thinkpool-pair pnpm add thinkpool-pair yarn add thinkpool-pair bun add thinkpool-pair ``` Provides the command `thinkpool-pair`. ## Health **Score 60/100 (C)** — status: active. Positive: esm support; no vulnerabilities; recently updated; high maintenance score. Warnings: low downloads; no types; pre 1.0. ## Facts | | | |---|---| | Version | 0.7.469 | | Published | 2026-10-14 | | First published | 2026-06-09 | | Weekly downloads | 0 | | License | SEE LICENSE IN LICENSE | | TypeScript types | none | | Module format | ESM | | Node | >=18 | | Dependencies | 7 | | Unpacked size | 1 MB | | Known vulnerabilities | 0 (+1 in 1 direct dependencies) | | Install scripts | no | | Maintainers | thinkpool | ## Links - npm: https://www.npmjs.com/package/thinkpool-pair - npm.io page: https://npm.io/package/thinkpool-pair ## Dependencies (7) - [zod](https://npm.io/package/zod.md) 4.5.4 - [yaml](https://npm.io/package/yaml.md) 2.9.0 - [compromise](https://npm.io/package/compromise.md) 14.16.0 - [@supabase/supabase-js](https://npm.io/package/@supabase/supabase-js.md) 2.112.2 - [@agentclientprotocol/sdk](https://npm.io/package/@agentclientprotocol/sdk.md) 1.3.0 - [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) 1.30.0 - [@anthropic-ai/claude-agent-sdk](https://npm.io/package/@anthropic-ai/claude-agent-sdk.md) 0.3.283 ## Recent versions - 0.7.469 (latest) — 2026-10-14 - 0.7.468 — 2026-10-14 - 0.7.467 — 2026-10-13 - 0.7.466 — 2026-10-13 - 0.7.465 — 2026-10-13 - 0.7.464 — 2026-10-07 - 0.7.463 — 2026-10-07 - 0.7.462 — 2026-10-02 - 0.7.461 — 2026-09-30 - 0.7.459 — 2026-09-26 - 0.7.458 — 2026-09-26 - 0.7.457 — 2026-09-26 - 0.7.456 — 2026-09-26 - 0.7.455 — 2026-09-23 - 0.7.454 — 2026-09-22 - … 485 more at https://npm.io/package/thinkpool-pair/versions ## README # `thinkpool-pair` `thinkpool-pair` connects coding agents running on a machine you control to a thinkpool Code room. Both people in the room can watch and steer the visible agent lanes from a browser or phone. The bridge makes outbound connections to thinkpool’s Supabase project. It does not require an inbound port, tunnel, or public IP. ## Requirements - Node.js 18 or newer - A thinkpool account and Code session - At least one supported runtime available on the host: - Claude - Codex - Hermes - The provider login or API credentials required by that runtime **The bridge does not include a coding agent.** Claude Code, Codex, or Hermes must already be installed and runnable on the bridge machine. BYOK only supplies model-provider credentials to an installed runtime; a provider key does not install or replace the agent itself. ## Start the bridge Run the launcher from the project directory the agents should use: ```bash npx thinkpool-pair@latest ``` The launcher shows the linked account, detected runtimes, current directory, and background-service state. On first use it asks to link the machine in a browser. Then choose one of: - **Serve all my sessions** — runs in the current terminal until `Ctrl-C`. - **Always-on background service** — starts at login/reboot and restarts after a crash. The normal install is pinned to the confirmed package version; use the launcher’s **Restart & update bridge** action when a new version should land. Back in the room, open the runtime/model you want for each terminal. A terminal works inside one repository on the bridge machine (the bridge checkout by default); to work in another repo discovered under `~/Projects` (or `TP_REPO_ROOTS`), send `/repo ` as that terminal’s first message, or pass `repo` when an agent opens a terminal. ## Account and service commands Link the machine without opening the full launcher: ```bash npx thinkpool-pair@latest login ``` Install or remove the account-wide background service: ```bash npx thinkpool-pair@latest install-service npx thinkpool-pair@latest restart-service npx thinkpool-pair@latest uninstall-service ``` `install-service` is pinned by default so a later bad npm publish cannot silently replace a working unattended bridge. Opt into tracking `@latest` only when that trade-off is intentional: ```bash npx thinkpool-pair@latest install-service --auto-update ``` ### Optional: Jev semantic past-work search via Vercel Past-work search stays local by default. Hosts can opt specific rooms into Jev ranking through Vercel AI Gateway. Configure `AI_GATEWAY_API_KEY` and a comma-separated `TP_JEV_SEARCH_ROOMS` allowlist in the bridge environment, or create a host-owned `~/.thinkpool-pair/jev-search.json` file with mode `0600`: ```json {"apiKey":"YOUR_VERCEL_AI_GATEWAY_KEY","rooms":["ROOMCODE"]} ``` Use a dedicated gateway key with a small lifetime budget. Keep it outside the repo and room transcript. Environment values override file values; an empty `TP_JEV_SEARCH_ROOMS` disables the pilot. The file is re-read for each search, so changes apply without restarting a bridge version that includes this adapter. Installing this code into an older running bridge still requires a bridge update. Opting in sends the filtered query and at most 24 excerpts (260 characters each) to Vercel and its Jev provider. Excerpts come only from the current room's bounded archive scan. Terminal metadata and raw transcripts are not sent. Existing secret and host-path filters run before transmission, but pattern filters cannot guarantee that arbitrary prose contains no sensitive information. Enable only rooms approved for this external processing. No local inference cache or transcript telemetry is added. The adapter uses `typesafe-ai/jev` at the fixed `/v1/evaluate` gateway endpoint. This is a provider model alias, not a pinned model version. Jev's relevance scores rank candidates only; they never approve tools, complete Flow gates, or authorize work. Every result keeps its original local citation. The shortlist favors partial lexical matches and includes eight recent remaining excerpts; older evidence outside this shortlist can still be missed. A two-second deadline, gateway errors, invalid answers, or no relevant candidates return the ordinary local search results. The existing three-searches-per-turn limit remains in effect. From a source checkout, `node bridge/jev-search-smoke.mjs ROOMCODE` runs an explicit live test using synthetic records only. It verifies paraphrase retrieval and a 24-candidate batch, and reports gateway usage/cost without printing credentials. Ordinary unit tests use fake responses and never call the gateway. See [Vercel evaluation API](https://vercel.com/docs/ai-gateway/modalities/evaluation) and [gateway key budgets](https://vercel.com/docs/ai-gateway/observability-and-spend/budgets). ### Optional: keep the bridge computer awake The launcher’s **Settings → Keep computer awake** option prevents system sleep while the bridge is running. The same choice is available from the CLI: ```bash # Foreground, for this run only npx thinkpool-pair@latest --keep-awake # Persist the choice and install the background service npx thinkpool-pair@latest install-service --keep-awake # Persistently turn it back off while reinstalling/updating the service npx thinkpool-pair@latest install-service --no-keep-awake ``` **Important:** keep-awake can substantially increase battery use. It prevents the computer from sleeping; it does **not** keep the display illuminated. Display dimming, screen locking, and display sleep continue normally. Closing a laptop lid may still put it to sleep depending on the operating system and its power settings. On some Linux systems the sleep inhibitor can also block an explicit suspend request while the bridge runs. The implementation is process-bound and releases automatically when the bridge stops: macOS uses `caffeinate -i`, Linux uses `systemd-inhibit --what=sleep`, and Windows uses a system-only power request without `ES_DISPLAY_REQUIRED`. If the platform helper is unavailable, the bridge warns and continues without keep-awake rather than failing startup. Service implementation by platform: - macOS: LaunchAgent - Linux: systemd user service; run `loginctl enable-linger "$USER"` once if it must survive logout - Windows: Startup-folder command file On Windows the startup entry launches at login; update it from the launcher and relaunch the bridge window to apply the new version. ## Project directories The account bridge serves sessions from their bound project directories. Set a default for new/unbound sessions: ```bash npx thinkpool-pair@latest set-default-dir /path/to/project ``` Bind one room explicitly when needed: ```bash npx thinkpool-pair@latest bind /path/to/project ``` Room codes are treated as secrets because room members can drive agents that have access to the bound project and the host permissions granted to that lane. ## Runtimes and providers | Runtime | Authentication/provider behavior | |---|---| | Claude | Uses the host’s normal Anthropic login by default. A registered Anthropic-compatible provider can be selected for a lane. | | Codex | Uses the host’s Codex/OpenAI login. Custom bridge providers are not wired to Codex lanes. | | Hermes | Uses an isolated thinkpool ACP profile. Set it up explicitly before the first Hermes lane. | The launcher’s **Settings → Provider** flow configures the host default for Claude-compatible lanes. The equivalent CLI commands are: ```bash npx thinkpool-pair@latest provider npx thinkpool-pair@latest provider anthropic npx thinkpool-pair@latest provider custom --base --token --model ``` The custom endpoint must implement the Anthropic Messages API. A raw OpenAI-compatible chat-completions endpoint is not enough; place a translating gateway in front of it or use the runtime that natively owns that provider. Set up an isolated Hermes profile with one of: ```bash npx thinkpool-pair@latest setup-hermes --clone npx thinkpool-pair@latest setup-hermes --clean ``` `--clone` copies the active Hermes provider/configuration into the isolated profile. `--clean` creates the isolation boundary without copying credentials. ## Direct single-room mode The account-wide launcher is the normal path. A direct room process is still available for debugging or a deliberately single-room host: ```bash npx thinkpool-pair@latest -- claude npx thinkpool-pair@latest -- codex npx thinkpool-pair@latest -- hermes ``` Add `--headless` when the process should be driven only from the room. Direct room services use the same command with the room code: ```bash npx thinkpool-pair@latest install-service -- claude npx thinkpool-pair@latest uninstall-service ``` ## Cloud or always-on host The bridge can run on a VM, dev box, home server, or container because its room connection is outbound-only. Use the same launcher/service commands and provide the runtime’s headless credentials through the host’s secret manager. For Claude, either an Anthropic API key or a valid Claude Code OAuth token can authenticate the runtime. Treat subscription/OAuth tokens as personal secrets; do not hand them to a third-party host. ## What crosses the boundary The bridge and web app deliberately split responsibility: - Agent processes, repository access, provider credentials, and raw terminal bytes remain on the bridge machine. - thinkpool relays room events and terminal output to authorized room members. - The account-level **Settings → Features → Clean invisible Unicode** option can apply conservative invisible-character hygiene before agent prose is stored or broadcast. It is off by default. This is not statistical-watermark detection or provenance removal. - thinkpool stores the reader transcript and room events so members can reopen the room. - thinkpool does not store a copy of the repository or a second copy of the raw PTY byte stream. - Voice dictation is an application API path and uses the configured transcription service; it is not a local-only bridge operation. Inspect the host-side boundary before pairing a sensitive repository: ```bash npx thinkpool-pair@latest privacy-report ``` The report lists configured project directories, local bridge records, known outbound domains, remote storage categories, and the report’s limits. It does not print provider keys, refresh tokens, or bridge private keys. Structured session state is stored below `~/.thinkpool-pair/` so an agent lane can resume after a bridge restart. Protect that directory like other local developer credentials and session state. ## Visual verification tools Structured Claude and Codex lanes can use bridge-owned preview tools even when their own sandbox cannot bind a port or launch a browser: - `preview_start` serves a built directory inside the lane worktree. - `preview_capture` records exact desktop and mobile renders. - `preview_inspect` reads rendered DOM text and geometry. - `preview_stop` releases the preview server. Preview roots are read-only, cannot escape the lane worktree, and accept only the preview server’s loopback origin for page requests. The browser starts on demand and is reused while work is active. After the last active or queued job finishes, 60 seconds of inactivity closes it; the next job starts it again. Each job uses a fresh browser context, disposed on success or failure. Desktop (1440×900) and mobile (390×844) run sequentially. Mobile enables touch, mobile viewport behavior, and a mobile Chromium identity at device scale 1. It does not claim to emulate Safari or a physical iPhone. Managed preview jobs across all rooms share one host slot with the repository browser checks and the Design render/freeze helpers, including the browser tests in `test:unit`. The unit runner also uses one worker. The slot uses an exclusive loopback listener on port 47683; it serves no application protocol and disappears if its owning process exits. Waiting jobs time out after two minutes without stealing an active slot. Personal Chrome tabs and independently launched browser scripts are outside this managed limit. From the repository, run `npm run test:browser` for sequential Chromium and WebKit viewport, touch/click, and session-isolation checks. Use `npm run test:browser -- --engine=chromium` on older Macs without supported WebKit. `TP_BROWSER_PATH` also selects an installed Chrome for the app tests and Design helpers when bundled Chromium cannot run on the host. CI installs both pinned Playwright engines and runs the existing landing focus and Lynx request-lifecycle app tests under WebKit (`TP_TEST_BROWSER_ENGINE=webkit`). Safari-sensitive releases still require a real-device check of login, keyboard/focus, scrolling, and the changed interaction; record the device/OS and result separately. ## Optional bridge environment variables | Variable | Purpose | |---|---| | `TP_NAME` | Label this bridge in the room | | `TP_PAIR_ROOT` | Override the local state directory | | `TP_SUPABASE_URL` / `TP_SUPABASE_ANON` | Override the built-in thinkpool project endpoint/public key | | `TP_ANTHROPIC_BASE_URL` / `TP_ANTHROPIC_AUTH_TOKEN` / `TP_ANTHROPIC_MODEL` | Override the Claude-compatible provider without writing provider config | | `TP_CONTEXT_MAX` | Override the context-window size used by the room meter | | `TP_BROWSER_PATH` | Point preview capture at a non-standard Chrome/Chromium binary | | `TP_FLOW_OFF=1` | Disable Dispatch on this bridge (legacy environment-variable name) | | `TP_HOST_LIVE_LANES` | Lower the shared parent-and-worker host ceiling from its safety maximum of 12 | | `TP_SPAWN_OFF=1` | Disable agent-spawned worker lanes | | `TP_PAIRBUS_OFF=1` | Disable the paired-room bus | | `TP_CROSSROOM_OFF=1` | Disable cross-session reach | Provider and account configuration written by the launcher is preferred for a managed service because shell startup files are not guaranteed to be sourced. ## Troubleshooting ### The room cannot see the bridge Run the launcher and check its account/runtime/service header. If the account link is missing or expired, rerun: ```bash npx thinkpool-pair@latest login ``` ### A service is installed but not serving Use the launcher’s restart/update action or: ```bash npx thinkpool-pair@latest restart-service ``` The install command prints the platform-specific log directory. Inspect that log before reinstalling; repeated installation can hide the original failure. ### No runtimes are available Install and configure Claude Code, Codex, or Hermes on the host, then restart the launcher. Runtime availability is detected from the host; the web room cannot install a missing CLI. BYOK configures provider credentials only and does not replace the local agent runtime. ### A custom model fails immediately Check that the endpoint implements Anthropic Messages semantics and that the model ID exists on that provider. Codex lanes ignore the bridge’s custom Claude provider configuration and use the Codex/OpenAI login. ### Preview capture cannot find Chrome Install Chrome/Chromium on the bridge host or set `TP_BROWSER_PATH` to its executable. ## Develop the bridge package From the repository root: ```bash npm --prefix bridge ci npm run test:bridge node bridge/test-packed-artifact.mjs ``` The public npm artifact is built separately from the readable private source: ```bash npm --prefix bridge run build:package node bridge/.publish-package/publish-guard.mjs ``` The staging build preserves the runtime module/file graph but removes comments, formatting, and local symbol names. It emits no source maps and integrity-binds every published file. Raw `npm pack` and `npm publish` from `bridge/` are deliberately blocked; the release command below builds and verifies the staged artifact itself. Run the checked-out launcher with: ```bash node bridge/bridge.mjs ``` Publishing is separate from the web-app deploy: ```bash npm --prefix bridge run release ``` The release command has external side effects and requires npm publish authority. Do not use it as a local verification command. ## Licence `thinkpool-pair` is proprietary software. A lawful recipient may install and run an unmodified copy to use thinkpool. Redistribution, modification, resale, and other uses require prior written permission. See [LICENSE](LICENSE) and the [thinkpool Terms of Service](https://thinkpool.io/terms). --- _Source: https://npm.io/package/thinkpool-pair · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._