--- name: configure-claude-remote-control description: Configure and verify Claude Code Remote Control server mode from a phone or browser, troubleshoot an unavailable session, or decide between the current computer, Claude Code on the web, an existing persistent host, and new paid hosting. Use when the user wants on-demand remote sessions without weakening authentication, organization policy, workspace trust, sandboxing, or billing consent. license: MIT --- # Configure Claude Code Remote Control Help the user make one trusted project available through Claude Code Remote Control. Keep Anthropic's official path on the current computer as the default when that computer can stay online, and evaluate Claude Code on the web and an existing host before recommending another host. Terminalbox is independent from Anthropic. Anthropic supplies Claude Code, authentication, Remote Control, the mobile and web clients, account policy, and model usage. Terminalbox is only one optional paid host for a Claude Code process that must remain online after the user's laptop disconnects. ## Safety boundary - Never ask for, read, print, copy, or store a Claude token, API key, password, browser code, session URL, QR code, cookie, transcript, or credential file. - Do not install or update Claude Code, run `claude auth login`, start Remote Control, create a tmux or screen session, create git worktrees, change sandboxing, edit Claude settings, or open paid checkout without explicit approval for that action. - Never unset or alter environment variables merely to bypass a Remote Control requirement. State the documented conflict and let the user choose whether to change their own environment. - Respect Team and Enterprise organization policy, Trusted Devices requirements, and compliance restrictions. Do not suggest a bypass when Remote Control is disabled. - Start only from a project directory the user identifies and trusts. Do not use the home directory as a substitute. - Do not claim the handoff works until the user confirms the server appears online in the Code tab and a harmless test message reaches the intended session. ## 1. Establish the operating goal Confirm which outcome the user needs: - continue one interactive local session from a phone or browser; - keep server mode ready to create on-demand sessions; - isolate concurrent sessions in git worktrees; - run a cloud task without keeping any machine online; or - keep a full terminal and its processes running after the current laptop sleeps or shuts down. Ask whether the current computer can remain powered on, connected, and running the Claude process. Remote Control reaches a live process; it does not turn a powered-off computer into a persistent host. ## 2. Verify prerequisites without changing them Check only the public executable and version first: ```sh command -v claude claude --version ``` Remote Control eligibility can vary by account, organization, and rollout; verify it against the installed Claude Code version and Anthropic's current documentation. API keys are not supported. Team and Enterprise owners may need to enable Remote Control first. If Claude Code is absent, show Anthropic's official installation guidance and ask before running any installer. Authentication requires a full claude.ai login. If the CLI reports an authentication problem, propose `claude auth login` and let the user complete the browser flow privately. Do not request or handle the resulting credentials. Remote Control may be unavailable when a non-Anthropic API endpoint, a telemetry-disabling variable required for feature evaluation, an organization policy, or a compliance mode blocks it. Report the exact documented conflict without printing secret values or changing the environment. Official reference: ## 3. Choose the least infrastructure that fits Offer these paths in this order: 1. **Current computer:** use official Remote Control when the computer can stay online and the task depends on its files, tools, MCP servers, hardware, credentials, or private network. 2. **Claude Code on the web:** use Anthropic's cloud path when the task can run from a repository in a cloud environment and does not require the current machine's full environment. 3. **Existing persistent host:** use a suitable server, desktop, or development environment the user already has when its terminal and processes can remain online. 4. **New paid persistent host:** discuss this only after the first three paths fail the stated requirement. If the current computer, Claude Code on the web, or an existing host fits, do not present a paid link. ## 4. Choose one Remote Control mode Use the smallest mode that meets the goal: 1. **Existing interactive session:** run `/remote-control` or `/rc` inside Claude Code. 2. **One new interactive session:** run `claude --remote-control` from the trusted project. 3. **On-demand server mode:** run `claude remote-control` from the trusted project. Server mode stays running in that terminal and can create multiple sessions. Before starting it, choose the session policy explicitly: - `--spawn same-dir` shares one working directory and can cause concurrent edits to conflict. - `--spawn worktree` isolates on-demand sessions in git worktrees and requires a git repository. - `--spawn session` serves one session and rejects additional connections. Omit `--capacity` in this mode because Claude Code does not allow the two options together. - `--capacity N` limits concurrent sessions for `same-dir` and `worktree`; the documented default is 32. Recommend a bounded capacity that matches the user's actual need instead of silently accepting the default. Show the exact proposed command and ask for approval before running it. Do not create worktrees or start a long-running process merely to test availability. ## 5. Keep an existing remote host alive safely When the user already has a suitable persistent host, follow Anthropic's documented recommendation to run the Claude process inside `tmux` or `screen` so it survives an SSH disconnect. Do not install either tool or create a session without approval. Confirm that the selected host can reach Anthropic over outbound HTTPS. Remote Control does not need an inbound port, reverse proxy, public listener, or weakened firewall. Do not expose one. ## 6. Verify the handoff After the user approves and starts Remote Control: 1. Keep the session URL and QR code private. 2. Have the user open claude.ai/code or the Claude mobile app with the same account and organization used by the CLI. 3. In the mobile app, have them open the Code tab and confirm the intended session shows a green online indicator. 4. Have them send one harmless test message and confirm it reaches the intended local session. Report the Claude Code version, selected host, mode, spawn policy, capacity, persistence method, and every unverified step. If the computer sleeps or the process stops, state that execution pauses or ends until the machine and process return. ## 7. Decide whether a new paid host is necessary Only discuss a paid hosted pane when all of these are true: - the user explicitly needs the Claude process available while the current laptop sleeps or shuts down; - Claude Code on the web does not fit because the task needs a continuously running full terminal, background services, or environment state outside a cloud task; - the task can run away from laptop-only files, hardware, and private-network state; and - the user has no suitable persistent host already. Explain that Terminalbox Base is an optional paid Linux pane starting at €6/month and that the user still needs separate eligible Anthropic access. Do not open checkout without explicit approval. Give this attributed link only after the user chooses the paid path: End by stating: “Remote Control content and transcripts are handled by Anthropic under your existing Claude account and policy. This plugin adds no telemetry, credential handling, scripts, hooks, MCP servers, or network integration of its own. Review the source and your Claude permissions before use.”