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:

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 <name> 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:

npx thinkpool-pair@latest login

Install or remove the account-wide background service:

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:

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:

{"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 and gateway key 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:

# 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:

npx thinkpool-pair@latest set-default-dir /path/to/project

Bind one room explicitly when needed:

npx thinkpool-pair@latest bind <ROOM> /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:

npx thinkpool-pair@latest provider
npx thinkpool-pair@latest provider anthropic
npx thinkpool-pair@latest provider custom --base <url> --token <key> --model <id>

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:

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:

npx thinkpool-pair@latest <ROOM> -- claude
npx thinkpool-pair@latest <ROOM> -- codex
npx thinkpool-pair@latest <ROOM> -- hermes

Add --headless when the process should be driven only from the room. Direct room services use the same command with the room code:

npx thinkpool-pair@latest install-service <ROOM> -- claude
npx thinkpool-pair@latest uninstall-service <ROOM>

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:

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:

npx thinkpool-pair@latest login

A service is installed but not serving

Use the launcher’s restart/update action or:

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:

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:

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:

node bridge/bridge.mjs

Publishing is separate from the web-app deploy:

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 and the thinkpool Terms of Service.