LinkShell documentation

Q: The app says the computer can't be reached

Check the computer is awake and linkshell host status shows the gateway connected, then run linkshell doctor. The app reconnects on its own once it's back.

Q: An agent shows "not logged in"

Sign in to that agent once in a terminal on the computer (/login in claude, codex login, copilot login…); LinkShell uses that sign-in.

LinkShell has two parts: the Host on your computer, managed by the Mac or Windows desktop app or CLI, and the app on your phone. Here it is, in order.

Install

Mac · Apple Silicon Mac · Intel

The standalone Mac app requires macOS 13 or later and includes its runtime; no separate Node installation is needed. Open it to sign in, manage the host and install updates. The CLI installation below is an alternative.

Windows · Installer Windows · ZIP

The Windows desktop app requires Windows 10 1809+ / Windows 11 x64 and bundles CLI, Host and Node. Its window is the same Electron app as on Mac and needs no WebView2 Runtime. The installer and portable ZIP are unsigned and may show unknown-publisher or SmartScreen prompts.

The CLI requires macOS or Linux and Node.js 22.13 or newer (already bundled in the standalone Mac app).

$ npm i -g linkshell-cli
# or
$ brew install LiuTianjie/linkshell/linkshell
# or
$ curl -fsSL https://liutianjie.github.io/LinkShell/install.sh | sh

Install and sign in to the agents you want to use on the computer yourself (for example claude, codex login, gemini, copilot login). Phone app: iPhone · Android APK.

Mac desktop app and updates

Overview and Settings include sign-in, account status and sign-out. Sign-in opens your browser and refreshes automatically when complete; the official gateway requires an iTool membership. Account sign-in and gateway connectivity are separate states. Closing the window leaves the app in the menu bar; quitting the UI keeps the Host running.

The app, CLI, Host and Node update together. Automatic checks only check versions; installation requires confirmation and may interrupt active work. The app restores its owned Host and preserves identity, pairings and history. Existing npm / Homebrew installations are not overwritten. Settings can install an optional terminal command that follows app updates.

Local data stays in ~/.linkshell, outside the app. See the desktop guide.

Start LinkShell

$ linkshell host --daemon   # run in the background
$ linkshell host status     # agents, sessions, gateway
$ linkshell host stop

The host starts agents with your login shell's environment, so PATH, proxies and API keys match your terminal. Sessions and history live in ~/.linkshell; restarting the computer doesn't need a new pairing.

Connect a phone

Pro: the official gateway

$ linkshell login
$ linkshell host stop && linkshell host --daemon

Sign in to the app with the same account and the computer shows up under Computers; no QR code needed. About the iTool membership.

Your own gateway: pairing

$ linkshell host --gateway wss://gw.example.com --daemon
$ linkshell pair

The terminal shows a QR code and a 6-digit code. In the app, go to Computers → Add computer and scan it or type the code. The gateway is remembered, so later starts don't need --gateway; --gateway off turns it off.

Self-host a gateway

A gateway only relays encrypted data and needs very little. Pick one:

# with the CLI on a server
$ linkshell gateway --port 8787 --daemon
# or Docker
$ docker run -d --name linkshell-gateway -p 8787:8787 \
    -v linkshell-gateway:/data nickname4th/linkshell-gateway

On the internet, put an HTTPS reverse proxy in front (Caddy or Nginx) and use wss://your-domain. For home use only, you can run the gateway on the computer itself and use ws://LAN-IP:8787.

From your terminal

$ linkshell claude [args]   # Claude Code, hand-off ready
$ linkshell codex [args]    # Codex, shared with the phone

Arguments pass straight through (for example linkshell claude --resume <id>). While Claude runs at your desk the phone follows along live; sending from the phone takes over, the terminal says so, and any key takes it back.

Claude doesn't save a session until its first message, so a session with no messages yet can't be handed to the phone.

On your phone

New session: pick an agent and a project folder and go.
Answer questions: Codex (including Desktop asynchronous questions), Claude, Cursor and Grok show when input is needed. Answer or skip from the phone's question card. Cursor supports choices; text answers depend on the agent.
Messages while busy: they queue above the composer, where you can reorder them, take one back to edit, or send it now (into the running turn for Codex and Claude; other agents stop the turn first). Stopping puts queued text back in the composer.
Fork and worktrees: fork from under any reply, or the whole session from its menu; a new session or a fork can go into a new git worktree (under ~/.linkshell/worktrees/, on its own branch). A worktree without changes is removed with its session.
Side conversations: 旁支对话 in the session menu, or type /side (Codex) or /btw (Claude, Grok) with a question. Codex answers in a read-only temporary fork and can look at files; Claude and Grok answer from the conversation. A side conversation lives on the computer until it is closed and never enters the session.
Command palette: type /, tap the composer’s command button, or choose Commands from the session menu. Search commands and skills without losing your draft.
Persistent goals: use /goal with Codex or Claude Code, or open the goal screen from the menu. Codex supports token budgets, pause and resume; Claude supports setting and clearing completion conditions. Requires support from the installed agent.
Background tasks: /tasks or the session header shows commands that keep running after a reply, their output and exit codes. Stop individual Codex tasks; Claude Bash / Monitor tasks are viewable, with stopping handled on the computer.
Adaptive layouts: the conversation, composer and controls adapt to the available space on iPhone Duo and standard iPhones.
Workflows, sub-agents and files: the button beside a session's title lists its Workflows and sub-agents; return to background runs above the composer, and browse project files from a session's or a terminal's menu.
Settings: under the composer, change model, effort and permission mode (whatever the agent offers).
Agent connections and tools: open an agent's settings under Computers to sign in, configure MCP servers and additional directories, or add a custom ACP connection. Agents that support edit suggestions can propose changes from the file page for you to preview and apply; available features depend on the agent.
Tidying: long-press a session to rename, archive or delete it; open Archives from the bottom of Home or find it in search. Codex archives sync with its native records and remain readable without restoring them. Claude and other agents are archived only in LinkShell. Remove an unused computer by long-pressing it under My computers.
Session recovery: CLI 0.10.19 rechecks task activity so finished tasks do not keep appearing as running. Missing or unreadable history shows an explanation while retaining cached messages; reopen the session to retry.
Apple Watch: 2.3.33 adds independent watch connections. Sign in with an email/password account or enter a computer pairing code in Connection Settings to view sessions, handle simple approvals and send short messages. Optional iPhone companion mode remains available. Independent connections run in the foreground and require Gateway 0.6.20 or later.
Terminal, preview, screen: from Computers, open a terminal, open a local port (full screen available), or view the screen and control it with a trackpad and keyboard. The screen's toolbar has one-tap shortcuts (copy, paste, switch app, Mission Control, screenshots, F-keys, and your own) and a text box to write in and send, with the phone's clipboard. Supports Apple silicon and Intel Macs on macOS 13 or later; choose the standalone download for your chip, while the CLI helper selects the native architecture automatically; linkshell setup takes you through its two permissions, linkshell screen does just that part.

Remote screen quality and connection

My computers in the web and desktop workspace shows equal-size cards with live CPU and memory readings. Eight monitoring styles mix in the grid; each computer remembers its style, which you can change individually. Search or rename a computer, then open its desktop to choose a display, adjust quality or enter fullscreen. Offline computers keep their cards. Resource readings require Host 0.4.83 or newer.

Open your Mac desktop on the phone, switch displays, use landscape or full screen and pinch to zoom. Choose trackpad mode for precise pointer movement or direct touch to click a spot. Right click, scroll, drag and use familiar Mac shortcuts, or send longer text and your phone's clipboard. Full control requires macOS 13 or later; Linux supports viewing.

Connection info offers widths of 1280, 1920, 2560 or native (up to 3840, bounded by the source display). iOS supports displays up to 120 Hz; actual resolution, frame rate and latency depend on both devices, the source display, network, power and temperature. Quality may decrease on a poor connection; use Retry when you need a new connection.

Changing displays or quality keeps the established screen connection. Visiting another page in the app or web workspace pauses capture; return within two minutes to resume on the same connection. Backgrounding the app, hiding the browser tab or disconnecting releases it, so the next visit connects again. Older host versions keep their existing reconnect behavior.

Sustained 120 fps, stable 4K/60 and real-device weak-network performance remain unproven. See the remote-desktop architecture and diagrams for the paths, fallback rules and known issues.

iPhone Duo and adaptive layouts

From app 2.3.7, LinkShell uses iPhone Duo’s available regions and fold information. With sufficient width, Changes or Preview can sit beside the conversation. Fold regions inform the layout of content and controls; narrower windows and standard iPhones use one column. Session and tool-panel state is preserved as the layout changes.

Duo layouts have been checked in the simulator; actual presentation depends on the size and posture reported by the system.

Use Computer Use from your phone

Tell Codex what you want done in the phone conversation and let it work in your computer's browser or desktop apps. Watch its actions live in a floating preview and keep giving instructions as it works.

Watch while chatting: the preview stays in place as you scroll. Drag it aside, tap to enlarge it, collapse it to an icon or close it. Reopen it with “Show computer preview” in the session menu.
Pick up where you left off: the last frame stays after the turn, and reopening the session restores the preview state.

Currently supports Codex on macOS with compatible Computer Use tools configured, and versions of the computer and phone apps that support this feature. Allow LinkShell to record the Mac's screen; run linkshell screen to set it up.

Commands

linkshell setup: First-time setup: start LinkShell, the screen's two permissions, connect your phone
linkshell host [--daemon] [--gateway <url>]: Start LinkShell; status, stop
linkshell pair: Pair a phone through the gateway
linkshell devices: List paired phones; remove unpairs one
linkshell screen: Set up watching and controlling the screen (the two macOS permissions)
linkshell login / logout: Pro account (official gateway)
linkshell claude / codex: Start an agent in your terminal, shared with the phone
linkshell gateway [--port] [--daemon]: Run your own gateway; status, stop
linkshell doctor: Check the environment and connectivity
linkshell upgrade: Upgrade to the latest version

FAQ

The app says the computer can't be reached

Check the computer is awake and linkshell host status shows the gateway connected, then run linkshell doctor. The app reconnects on its own once it's back.

An agent shows "not logged in"

Sign in to that agent once in a terminal on the computer (/login in claude, codex login, copilot login…); LinkShell uses that sign-in.

Upgrading from 1.x

2.0 changed both the app and the computer side, so upgrade both and pair again. The 1.x app and linkshell start are no longer supported.