LinkShell

LinkShell

Leave your desk. Your agents keep going.
Follow, steer and approve the coding agents running on your computer, from your phone.

CLI version on npm Test status MIT license

Website · Docs · iPhone · Android · Mac · 简体中文

LinkShell: a 50-second film recorded from the app
▶ Watch the film (50 s, recorded from the app)

Claude Code, Codex and other coding agents keep running on your computer. From your phone you watch them work, approve what they ask for, send a message into a running turn, and open the computer's screen when you need to. When you sit down again, the session is still in your terminal. Your code and the agent processes never leave your machine, and everything between phone and computer is end-to-end encrypted. Works with iPhone (including iPhone Duo), Apple Watch, Android and the browser, against macOS, Linux or Windows. Fusion Mode in the desktop app opens another computer's app windows alongside your local ones. Version 0.10.106 adds Fusion v2 with reconnect/resume and Windows support in preview. Both computers must upgrade; clipboard sharing is currently Mac-to-Mac only. See the [Fusion specification and validation limits](docs/v2/fusion.md). ## What it does
A session on the phone: a plan, file edits and a permission request
Follow the work, approve with a tap
New replies stream in; saved history appears without replaying the stream. Plans, tool calls and diffs update live. Permission requests and questions come to the phone, the Lock Screen and the watch.
A message typed while the agent is busy, about to be queued
Cut in while it is busy
Messages sent mid-turn wait in a queue. Reorder them, take one back, or steer one straight into the running turn. Stop a turn from the phone.
The phone in landscape showing the computer's screen
Your Mac, in your pocket
Open the real desktop, zoom in on the details and take the mouse and keyboard. Up to 3840 px wide, with iOS display support up to 120 Hz.
- **Lock Screen and Apple Watch.** A Live Activity shows progress and pending requests, with Deny / Allow on the card (iOS 17+). The watch app follows sessions, answers simple requests and sends short replies, on its own connection or through the iPhone. See [Apple Watch](docs/v2/apple-watch.md) and [Live Activities](docs/v2/live-activity.md). - **Hand sessions back and forth.** Start an agent with `linkshell claude` or `linkshell codex` and pass it between the terminal and the phone. Sessions opened in plain `claude` / `codex` or the Claude and Codex desktop apps can be followed too. - **Computer Use, from the phone.** Ask Codex to use the browser or desktop apps on your Mac and watch it live in a floating preview. See [Computer Use](docs/v2/computer-use.md). - **Questions, plans and goals.** Answer an agent's structured questions; use plan mode, `/goal`, slash commands and your skills. See [agent questions](docs/v2/agent-questions.md) and [commands and goals](docs/v2/commands-and-goals.md). - **Sub-agents, Workflows and background tasks.** Follow a Claude Workflow by phase, open each sub-agent's conversation, and check commands that outlive a reply. See [background tasks](docs/v2/background-tasks.md). - **Forks and worktrees.** Fork a session from any reply to try another direction, in the same directory or a new git worktree. - **Side conversations.** Ask about a session without interrupting it or adding to it, the agent's own way: Codex's `/side` (a read-only temporary fork), Claude's and Grok's `/btw`. - **A real terminal and localhost.** Terminals on your computer with a Ctrl / Esc / Tab / arrow-key bar, and your dev server's port on the phone over the same encrypted channel, with no open ports. - **Files, settings and connections.** Browse project files and hidden folders, send photos and files, and choose the agent’s model, effort and permission options. Start a quick conversation in your home directory; choices are remembered per computer and agent. Configure MCP servers and custom [ACP](docs/v2/acp-support.md) agents. - **Projects across computers.** Group projects by name, then by computer and path, while keeping each computer’s sessions and actions separate. Switch freely between all computers and the current one. - **My computers.** A compact list keeps CPU, memory, disk usage and desktop actions in each row. Expand a row for capacity details and recent trends; search, rename, unlock and retry without leaving the list. Disk readings require Host 0.4.91 or newer. - **Desktop workspace.** Resize or collapse the sidebar; scroll the file tree and file preview independently. Switching between local and remote access keeps one entry for the same computer. - **Adaptive layouts.** iPhone Duo puts the conversation beside its changes or a preview, and adapts to folds and orientation; iPad uses a split view. - **Search and housekeeping.** Search sessions by title, preview, path, branch or agent; rename, archive and delete, synced to Codex and Claude's own records where they support it. See [session recovery](docs/v2/session-recovery.md). ## Install on your computer **Mac: the standalone app** (macOS 13+, [Apple Silicon](https://github.com/LiuTianjie/LinkShell/releases/download/desktop-v0.10.116/LinkShell-0.10.116-arm64.dmg) · [Intel](https://github.com/LiuTianjie/LinkShell/releases/download/desktop-v0.10.116/LinkShell-0.10.116-x64.dmg)). Drag it into Applications, open it and sign in, then turn on Screen Recording and Accessibility in its Settings. It brings its own CLI, Host and Node and updates them together; nothing else is needed. It also gives you a desktop workspace for this Mac or another computer, token usage by agent, and launch at login. See the [desktop guide](docs/mac-desktop.md). **Windows: desktop preview** (Windows 10 1809+ / Windows 11, x64: [installer](https://github.com/LiuTianjie/LinkShell/releases/download/desktop-v0.10.116/LinkShell-Setup-0.10.116-windows-x64.exe) · [portable ZIP](https://github.com/LiuTianjie/LinkShell/releases/download/desktop-v0.10.116/LinkShell-0.10.116-windows-x64.zip); ARM64: [installer](https://github.com/LiuTianjie/LinkShell/releases/download/desktop-v0.10.116/LinkShell-Setup-0.10.116-windows-arm64.exe) · [portable ZIP](https://github.com/LiuTianjie/LinkShell/releases/download/desktop-v0.10.116/LinkShell-0.10.116-windows-arm64.zip)). Both bundle Node, CLI, Host, ConPTY and screen components, with the same desktop workspace as macOS for conversations, terminals, files and port previews. The window is the same Electron app as on macOS and needs no WebView2 Runtime. Direct H.264 video and JPEG fallback support viewing and control on the unlocked desktop. Packages are unsigned and may show unknown-publisher or SmartScreen prompts; see the [Windows guide](docs/windows-desktop.md) for installation and validation limits. **macOS or Linux: the CLI** (Node.js 22.13 or newer). ```bash npm i -g linkshell-cli linkshell setup ``` `linkshell setup` starts the host in the background, walks you through the two macOS permissions the screen needs (a LinkShell window takes you to each switch), and connects your phone. Run it again any time; each part also has its own command. Homebrew and an install script work too: ```bash brew install LiuTianjie/linkshell/linkshell curl -fsSL https://liutianjie.github.io/LinkShell/install.sh | sh ``` On Linux the screen can be watched but not controlled, and needs `ffmpeg` with an X11 display. Intel Macs are supported; real-hardware capture performance on Intel is not yet validated. The agents you use must be installed and signed in on the computer as usual (`claude`, `codex login`, `gemini`, `copilot login`, …). LinkShell runs them as you, with your login shell's environment, and never handles their accounts or API keys. ## Connect your phone Get the app: [iPhone](https://apps.apple.com/cn/app/linkshell/id6761547516) · [Android](https://github.com/LiuTianjie/LinkShell/releases/latest). Then either: - **Official gateway (iTool membership).** Sign in on the computer (`linkshell login`, or in the desktop app) and in the phone app with the same account, and the computer appears by itself. - **Free: your own gateway.** Run a gateway ([below](#run-your-own-gateway)), point the host at it and pair each phone once by QR code or six-digit code: ```bash linkshell host --gateway wss://gw.example.com --daemon linkshell pair # in the app: Computers → Add computer ``` Every feature is free with a self-hosted gateway. To use the official gateway, buy LinkShell on its own (CNY 9.9/month or 49/year; USD 3.19/month or 13.49/year), or choose the all-products annual bundle (CNY 99 or USD 26.49). Prices include tax. [Choose a plan on iTool](https://www.itool.tech/en/pro?product=linkshell) with the same account; Alipay is one-time and Creem renews automatically until canceled. Refresh membership in the desktop app or web workspace after purchase. Existing access and referral rewards are preserved. The gateway also serves a browser client at its root URL, with the same pairing or account sign-in. See [the web client](apps/web/README.md). ## Agents | Agent | Mode | What you get | | --- | --- | --- | | **Codex** | Shared | `linkshell codex` and the phone are live at once; either side can send, interrupt and approve | | **Claude Code** | Handoff | Claude's own UI at your desk; a message from the phone takes over, any key at the computer takes it back | | **Gemini CLI, Google Antigravity, GitHub Copilot, OpenCode, Cursor, Grok, Cline, Kilo Code** | Remote | Start and continue sessions from the phone over the [Agent Client Protocol](https://agentclientprotocol.com): live output, approvals, modes and models | | **Qwen Code, Kimi Code, CodeBuddy, Qoder, MiniMax Code, TRAE, DeepSeek, GLM, iFlow, Comate** | Remote | Built-in ACP support for mainstream Chinese coding agents (`qwen --acp`, `kimi acp`, `codebuddy --acp`, `qodercli --acp`, `mcode acp`, `traecli acp serve`, `dsh --profile acp`, `glm-acp-agent`, `iflow --experimental-acp`, `comate-acp`), plus custom ACP connections | | **Any CLI** | Terminal | A terminal on the computer, viewed and typed into from the phone | Codex works with ChatGPT sign-in, an API key or a custom provider (including one managed by CC Switch). A Claude session opened in the Claude desktop app can be followed and continued from the phone, but the desktop app only shows what the phone did after a restart; use `linkshell claude` to hand a session back and forth.
What each agent supports from the phone | | Codex | Claude Code | Gemini, Copilot and others | | --- | --- | --- | --- | | A message during a running turn | joins the turn | joins the turn | stops the turn, then runs | | Fork a session, or from a reply | native | native | by LinkShell: the conversation is passed as text | | Side conversation | `/side`: a read-only temporary fork | `/btw`: answered from the conversation, no tools | Grok's `/btw`; not in the others | | Sessions in git worktrees | yes | yes | yes | | Slash commands | `/compact`, `/review`, `/init`, your skills | Claude's own list and your skills | whatever the agent offers | | Questions for you | yes, including Desktop asynchronous questions | yes | Cursor choices, Grok questions, standard ACP forms | | Plan mode | a setting on the phone | a permission mode | whatever modes the agent offers | | Persistent goals | set, pause, resume, clear, token budget | set and clear, when `/goal` is available | not integrated | | Background commands | status, output, stop one task | Bash / Monitor status and output | not integrated |
## Run your own gateway A gateway relays encrypted frames and brokers pairing; it never sees your code or conversations. A self-hosted one is the same program as the official gateway, without accounts. ```bash # with the CLI linkshell gateway --port 8787 --daemon # or with Docker docker run -d --name linkshell-gateway -p 8787:8787 \ -v linkshell-gateway:/data nickname4th/linkshell-gateway ``` Its only state is one SQLite file of public keys and pairings: `~/.linkshell/relay.db` with the CLI, `/data/relay.db` in the container. Keep it and phones stay paired. On the internet, put an HTTPS reverse proxy in front and use `wss://your-domain`; at home the gateway can run on the same computer (`linkshell host --gateway ws://:8787`). See the [deployment guide](docs/deploy.md). ## Security - **End-to-end encryption.** Phone and computer agree on keys signed by their long-term identities; every frame after that is sealed with XChaCha20-Poly1305. Gateways relay ciphertext only. The direct peer-to-peer channel for the screen and previews is negotiated over that tunnel. Where no direct path works, the official gateway's TURN server relays the screen's video, which stays DTLS-SRTP encrypted end to end. - **Pairing grants access.** A paired phone can do what you can do in a terminal on that computer. Pair only devices you trust and keep pairing codes to yourself; remove a phone with `linkshell devices remove `. - **Your accounts stay yours.** Agents run as your user with their own sign-in. Pro covers the gateway only. - **Local state.** Sessions, history and keys live in `~/.linkshell` on the computer (`LINKSHELL_HOME` moves it). Architecture details: [design](docs/v2/architecture.md) and [remote desktop](docs/v2/screen-realtime.md). ## Commands | Task | Command | | --- | --- | | Set up a computer: host, screen permissions, phone | `linkshell setup` | | Start the host in the background / see it / stop it | `linkshell host --daemon` / `linkshell host status` / `linkshell host stop` | | Connect on same-Wi-Fi LAN / set sleep policy | `linkshell host --lan [port]` / `linkshell host --keep-awake ` | | Pair a phone (own or LAN gateway) | `linkshell pair` | | List or remove paired phones | `linkshell devices` / `linkshell devices remove ` | | Use the official gateway (iTool membership) | `linkshell login` / `linkshell logout` | | Claude Code / Codex, shareable with the phone | `linkshell claude` / `linkshell codex` (arguments pass through) | | Set up or check the screen | `linkshell screen` / `linkshell screen --check` | | Open the Mac status app | `linkshell app` | | Run a gateway | `linkshell gateway [--port 8787] [--daemon]` | | Check the environment | `linkshell doctor` | | Upgrade (restarts a running host, keeping pairings and history) | `linkshell upgrade` | The standalone Mac app updates itself from its Updates page. > **Coming from 1.x?** 2.0 changed both the app and the computer side: upgrade both and pair again. ## Development A pnpm workspace; Node.js 22.13 or newer. ```bash git clone https://github.com/LiuTianjie/LinkShell.git cd LinkShell pnpm install pnpm build && pnpm typecheck && pnpm test ``` On macOS the full build also builds LinkShell.app and needs Xcode's Swift toolchain. On Windows it builds the desktop and screen helper with .NET Framework 4.8; `pnpm -r --filter "./packages/*" build` builds the TypeScript packages only (what Linux CI runs). To work on the app, run a development host with its own state directory, then Metro: ```bash LINKSHELL_HOME="$HOME/.linkshell-dev" pnpm dev:cli host --dev-port 7878 pnpm dev:app ``` | Directory | What it is | | --- | --- | | `packages/wire` | Session model, JSON-RPC methods, end-to-end encryption, relay client | | `packages/host` | The host daemon: agent drivers (Codex, Claude, ACP), terminals, ports, screen | | `packages/gateway` | The relay: routing encrypted frames, pairing, accounts | | `packages/cli` | `linkshell`: host, pairing, agent launchers, gateway, login | | `packages/client-core` | Client state and timeline shared by the apps | | `apps/client` | The iPhone, Apple Watch and Android app (Expo / React Native) | | `apps/mac` | LinkShell.app: screen capture, video, input, permissions, desktop workspace | | `apps/web` | The browser client served by the gateway | | `docs/site` | The website and the install script | Focused bug reports and pull requests are welcome. Include the CLI version, OS, agent and a minimal reproduction, and redact pairing codes and tokens. Releases follow the [release SOP](docs/release-sop.md). ## Support the project Sponsored by [AI18N](https://ai18n.chat/), an AI API gateway with OpenAI- and Anthropic-compatible interfaces. LinkShell is also on [Product Hunt](https://www.producthunt.com/products/linkshell).
Buy the author a coffee

WeChat Pay donation code Alipay donation code

## License [MIT](LICENSE)