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.

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

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.