# `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. ## 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: 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. ## 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).