linkshell-cli

Follow, steer and approve the coding agents running on your computer — from your phone. This is the computer side of LinkShell: it runs Claude Code, Codex and other agents you already have installed, and keeps them reachable from the LinkShell app (iPhone · Android) over an end-to-end encrypted channel.

Website · Docs · 简体中文

Install

macOS or Linux, Node.js 22.13 or newer.

npm i -g linkshell-cli
linkshell setup

linkshell setup does everything once, in order: it starts the host in the background, gets the screen ready (on a Mac, the two permission switches), and connects your phone. Each part also has its own command.

Connect your phone one of two ways:

• Pro — the official gateway. linkshell login, then sign in to the app with the same account. The computer shows up by itself.

• Your own gateway. Run one (below), then:

  linkshell host --gateway wss://gw.example.com --daemon
  linkshell pair    # scan the QR code in the app

Signed-in Free accounts can redeem a Pro activation code in the LinkShell phone app, Mac app or web workspace's account controls, or under Connection Settings → Membership & activation codes in Apple Watch independent mode. Buy a code on Liandong Xiaopu. iTool Settings → Upgrade to Pro remains available with the same account, including for renewing an active Pro membership.

Start sessions from the phone, or launch agents from your terminal so they can be handed over at any time:

linkshell claude    # Claude Code; a message from the phone takes over, any key here takes it back
linkshell codex     # Codex; the terminal and the phone are live at the same time

Claude Workflow progress, phases and Agent details require CLI 0.10.6 or newer and app 2.3.5 or newer. CLI 0.10.40 and newer automatically reconcile the running host with linkshell upgrade.

CLI 0.10.19 includes Host 0.4.19 session recovery fixes: stale running states, Codex native archives, missing Claude history and lazy ACP reconnection. This update needs only the computer-side CLI and a host restart; no mobile app, gateway or screen-helper update is required.

Remote screen

On Apple silicon and Intel Macs with macOS 13+, the CLI includes the signed universal LinkShell.app. macOS selects the native architecture automatically for screen capture, H.264 encoding and input; low-latency encoding is used where available. linkshell screen sets up Screen Recording and Accessibility; --check reports permissions and availability, not media performance. Linux viewing requires ffmpeg and an X11 display and has no input control.

Supported iOS app builds receive native WebRTC video and present it with Metal, requesting up to 120 fps within source/receiver, power, thermal and network limits. They automatically try standard WebView video and then RPC fallback if needed. A native receiver change needs a new iOS app binary as well as any required computer-side update. See the architecture and validation limits; a 120 fps request does not establish sustained 120 fps or stable 4K/60.

Commands

| | | | --- | --- | | linkshell setup | Set this computer up, once: the host, the screen's permissions, your phone | | linkshell host --daemon | Start LinkShell in the background | | linkshell status | The host, its agents, sessions and gateway connection | | linkshell host stop | Stop the host (linkshell stop stops everything LinkShell runs here) | | linkshell host --gateway <url> | Choose the gateway (off to disconnect, default for the official one); applies to a running host | | linkshell pair | Pair a phone through your own gateway | | linkshell devices | Paired phones; linkshell devices remove <name> unpairs one | | linkshell login / logout | Pro account: join or leave the official gateway, without restarting the host | | linkshell claude / linkshell codex | The agent's own UI, shareable with the phone (arguments pass through) | | linkshell gateway [--port 8787] [--daemon] | Run a gateway (gateway status, gateway stop) | | linkshell screen | Set up watching and controlling the screen (--check only reports) | | linkshell doctor | Check Node, agents, the host and its gateway | | linkshell upgrade | Upgrade the CLI and restart an outdated running host; preserve login, pairing and history |

Run your own gateway

A gateway only relays encrypted frames and brokers pairing. Yours is the same program as the official one, without the accounts: you pair each phone once, with a QR code or a six-digit code.

linkshell gateway --port 8787 --daemon

or with Docker: nickname4th/linkshell-gateway (see the self-hosting guide). Put it behind HTTPS and point hosts at wss://your-domain. All it keeps is one SQLite file, ~/.linkshell/relay.db: keep it and phones stay paired.

Files

~/.linkshell/
├── state.db              sessions and their history
├── identity.json         this computer's keys
├── paired-devices.json   phones paired with it
├── auth.json             the Pro login, if any
├── config.json           the chosen gateway
├── host.log              the host's log
├── worktrees/            git worktrees made for sessions started (or forked) into one
├── LinkShell.app         the Mac side of the screen, unpacked on first use (macOS)
└── relay.db              pairings, when this computer runs a gateway

LINKSHELL_HOME moves this directory. LinkShell never handles your agents' accounts or API keys: agents run as you, with your login shell's environment.

Coming from 1.x

2.0 changed both the app and the computer side: upgrade both and connect again. From 0.10 the 1.x commands (linkshell start, linkshell list) are gone, and linkshell gateway no longer serves the 1.x app. linkshell stop still ends a 1.x bridge left running from before the upgrade.

linkshell upgrade uses the newly installed CLI to restart an outdated running host, even when the CLI is already at the latest version. It retains the same home, identity, login and paired devices, waits for the gateway to reconnect, and leaves a stopped host stopped. Running agent turns and terminal processes stop during the restart; saved sessions remain available. The restart worker continues independently if an upgrade closes the host-owned terminal that launched it; its progress is in ~/.linkshell/upgrade.log (or LINKSHELL_HOME).

The first upgrade from a CLI older than 0.10.40 still runs the old updater. Once installation finishes, run linkshell upgrade again to bring the host forward. Subsequent upgrades need one invocation.

License

MIT