Mobile Terminal for Claude Code

English | 中文

Mirror a VS Code terminal to your phone: from the couch or on your commute, keep chatting with Claude Code and other AI CLIs running in your terminal — send commands and check on progress from a mobile browser.

• Same screen on both ends: the terminal lives in a real VS Code panel, and your phone and PC see exactly the same view (rendered with xterm.js, faithful ANSI colors / TUI redraws)
• Mobile input built for AI CLIs: a native input bar (works with IME and voice dictation) plus a shortcut toolbar (Esc, Ctrl+C, Tab, Shift+Tab, arrow keys…), designed for Claude Code's interactive TUI
• Scan and go: VS Code pops up a QR code, scan it from your phone to connect, and the PWA can be added to your home screen
• Instant reconnect: backed by a server-side screen snapshot, the current view is restored immediately after a refresh / reconnect
• Multiple sessions: several terminal tabs, switchable from the phone

Quick Start

1. Run Mobile Terminal: 开启手机远程终端（配对二维码） (Open Mobile Remote Terminal / Pairing QR Code) from the Command Palette — this is the extension's only command, and running it starts the background service. You can also click 远程终端 (Remote Terminal) in the bottom-right status bar.
2. Scan the QR code from your phone (for LAN access, enable remoteTerminal.lanMode, or just use Tailscale)
3. Tap ＋ at the top of the phone UI to create a terminal session — the same terminal appears in your PC's VS Code terminal panel at once, mirrored on both ends

LAN Access (phone and computer on the same Wi-Fi)

The simplest, zero-dependency option — no extra software needed:

1. Enable remoteTerminal.lanMode in Settings (or add "remoteTerminal.lanMode": true to settings.json). The service then switches from local-only 127.0.0.1 to binding 0.0.0.0.
2. Re-run Mobile Terminal: 开启手机远程终端（配对二维码）. The panel generates a LAN-address QR code (http://<your computer's LAN IP>:8377/#token=…); scan it from your phone to connect.

Notes:

• Both devices must be on the same subnet: corporate / public Wi-Fi often enables AP isolation (clients can't reach each other). If you can't connect, suspect this first — switch to Tailscale instead.
• Multiple NICs / proxies like Clash running: the extension automatically skips proxy TUN interfaces (e.g. Clash's 198.18.x), Docker/VM bridges, Tailscale and other virtual adapters, and picks the real Wi-Fi IP from the routing table. If it still picks wrong, the panel lists alternative IPs, or you can set remoteTerminal.lanHost manually.
• Firewall: if the system prompts you on first launch, allow VS Code to listen on port 8377 (macOS: System Settings → Network → Firewall).
• Plain HTTP: LAN mode is unencrypted (authenticated with a 256-bit token), and the browser treats it as a non-secure context. For an encrypted connection, use Tailscale or a cloudflared tunnel instead.
• Tailscale users don't need to enable this: the extension binds the Tailscale virtual IP automatically, which is more secure (reachable only from devices on the same tailnet).

Public Access (not on the same Wi-Fi / phone on 5G)

Option 1: Tailscale (preferred)

Install Tailscale on both PC and phone and sign in to the same account — zero exposed ports, end-to-end WireGuard encryption. The extension auto-detects the Tailscale virtual IP and generates the matching QR code in the connection panel; no LAN mode required.

Advanced: if you want HTTPS (a secure browser context), run tailscale serve --bg http://127.0.0.1:8377 manually.

Option 2: cloudflared one-click tunnel (secondary)

Install cloudflared (macOS: brew install cloudflared), then click 启动公网隧道 (Start Public Tunnel) under the 公网隧道 (Public Tunnel) tab in the connection panel. The extension sets up a temporary encrypted tunnel (*.trycloudflare.com, HTTPS) and generates a QR code; click 停止公网隧道 (Stop Public Tunnel) in the same tab when you're done.

Note: the tunnel URL changes on every start; security is guaranteed by the 256-bit token.

Security

• 256-bit random token authentication (stored in VS Code SecretStorage), with rate limiting on failures + lockout after repeated failures. If you suspect a leak, click 重置 Token (Reset Token) in the connection panel to invalidate it instantly.
• The service binds only 127.0.0.1 by default; Tailscale mode additionally binds its virtual IP (reachable only within the tailnet); public access always goes through an encrypted tunnel — the extension itself is never directly exposed to the internet.

Troubleshooting

• Error opening on phone right after the tunnel is created (530/1033): edge-node propagation takes 1–2 seconds; just refresh.
• Tunnel fails to establish: some networks block QUIC (UDP 7844); try running cloudflared tunnel --url http://127.0.0.1:8377 --protocol http2 manually in a terminal to verify.
• "Read-only mirror mode" message: the node-pty native module failed to load (usually an ABI mismatch caused by a VS Code upgrade). Update the extension to a matching version; in this mode the phone can only view output.
• Voice input: there's no in-app mic button — use your phone keyboard's built-in dictation in the input bar (it works over plain HTTP too).

Settings

Requirements

VS Code ≥ 1.93; macOS / Windows / Linux (x64 / arm64) — install the VSIX matching your platform.

Mobile Terminal for Claude Code

English | 中文

把 VS Code 终端「镜像」到手机浏览器：在沙发上、通勤路上，用手机继续和终端里的 Claude Code 等 AI CLI 对话、下达指令、查看进展。

• 双端同屏：终端真实显示在 VS Code 面板里，手机与 PC 看到完全相同的画面（xterm.js 渲染，ANSI 彩色 / TUI 重绘保真）
• 为 AI CLI 优化的手机输入：原生输入条（中文输入法 / 语音听写可用）+ 快捷键工具条（Esc、Ctrl+C、Tab、Shift+Tab、方向键…），专为 Claude Code 交互式 TUI 设计
• 扫码即用：VS Code 内弹出二维码，手机扫码即连，PWA 可添加到主屏幕
• 断线秒恢复：基于服务端屏幕快照，刷新 / 重连后立即恢复当前画面
• 多会话：多个终端标签，手机端可切换

快速开始

1. 命令面板执行 Mobile Terminal: 开启手机远程终端（配对二维码）（扩展唯一命令，执行即启动后台服务；也可点击状态栏右下角「远程终端」）
2. 手机扫码（局域网需开启 remoteTerminal.lanMode，或直接使用 Tailscale）
3. 手机端点顶部「＋」新建终端会话——PC 的 VS Code 终端面板会同步出现同一终端，双端同屏

局域网访问（手机与电脑同一 Wi-Fi）

最简单的零依赖方案，无需安装任何额外软件：

1. 设置中开启 remoteTerminal.lanMode（或 settings.json 加 "remoteTerminal.lanMode": true），服务即从仅本机 127.0.0.1 改为绑定 0.0.0.0
2. 重新执行 Mobile Terminal: 开启手机远程终端（配对二维码），面板会生成局域网地址二维码（http://<电脑局域网 IP>:8377/#token=…），手机扫码即连

注意事项：

• 两台设备必须在同一网段：公司/公共 Wi-Fi 常开启 AP 隔离（客户端互访被禁），连不上时优先怀疑这一点，可改用 Tailscale
• 多网卡 / 开着 Clash 等代理：插件自动跳过代理 TUN（如 Clash 的 198.18.x）、Docker/虚拟机桥、Tailscale 等虚拟网卡并按路由表选出真实 Wi-Fi IP；若仍选错，面板会列出备选 IP，也可用 remoteTerminal.lanHost 手动指定
• 防火墙：首次启动如系统弹出放行询问，请允许 VS Code 监听 8377 端口（macOS：系统设置 → 网络 → 防火墙）
• 明文 HTTP：局域网模式不加密（凭 256-bit token 鉴权），浏览器视为非安全上下文；需要加密连接请改用 Tailscale 或 cloudflared 隧道
• 已安装 Tailscale 的用户无需开启此项：插件自动绑定 Tailscale 虚拟 IP，更安全（仅同 tailnet 设备可达）

公网访问（不在同一 Wi-Fi / 手机走 5G）

方案一：Tailscale（首选）

PC 与手机各安装 Tailscale 并登录同一账号即可——零端口暴露、全程 WireGuard 加密。插件会自动检测 Tailscale 虚拟 IP 并在连接面板中生成对应二维码，无需开启局域网模式。

进阶：如需 HTTPS（安全上下文），可手动执行 tailscale serve --bg http://127.0.0.1:8377。

方案二：cloudflared 一键隧道（次选）

安装 cloudflared（macOS：brew install cloudflared），在连接面板「公网隧道」标签点 启动公网隧道。插件自动建立临时加密隧道（*.trycloudflare.com，HTTPS）并生成二维码；不用时在同一标签点「停止公网隧道」。

注意：隧道 URL 每次启动都会变化，安全性由 256-bit token 保障。

安全

• 256-bit 随机 token 鉴权（VS Code SecretStorage 存储），失败限速 + 连续失败锁定；怀疑泄露时在连接面板点「重置 Token」一键作废
• 服务默认仅绑定 127.0.0.1；Tailscale 模式额外绑定其虚拟 IP（仅同 tailnet 可达）；公网一律走加密隧道，插件自身永不裸露公网

排障

• 隧道刚建立时手机打开报错（530/1033）：边缘节点传播需 1–2 秒，刷新即可
• 隧道建立失败：部分网络封锁 QUIC（UDP 7844），可尝试在终端手动运行 cloudflared tunnel --url http://127.0.0.1:8377 --protocol http2 验证
• 提示「只读镜像模式」：node-pty 原生模块加载失败（通常为 VS Code 升级导致 ABI 失配），请更新插件到匹配版本；该模式下手机端仅可查看输出
• 语音输入：应用内没有麦克风按钮，请用手机键盘自带的语音听写在输入条里输入（明文 HTTP 下同样可用）

配置项

系统要求

VS Code ≥ 1.93；macOS / Windows / Linux（x64 / arm64），请安装与平台匹配的 VSIX。