# CLAUDE.md This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. ## What is LinkShell Follow, steer and approve the coding agents running on your computer, from your phone. Three parts: - **The host** — a daemon on the computer (`linkshell host`). It owns the agent sessions (Codex, Claude Code, ACP agents), terminals, port previews and the screen, and keeps their history. - **The app** — iOS / Android (`apps/client`). A client of the host. - **The gateway** — a relay between the two. Everything it routes is end-to-end encrypted; it only authenticates peers by key, brokers pairing and knows who may reach whom. There is one generation of everything. The 1.x PTY bridge, its protocol, its web console and its half of the gateway are deleted; don't bring them back. ## Build & Dev pnpm workspace (`apps/*`, `packages/*`), Node.js 22.13+ (the host and the gateway use `node:sqlite`). ```bash pnpm install pnpm build # pnpm -r build: tsc in each package; on a Mac also builds LinkShell.app (apps/mac) pnpm typecheck # pnpm -r typecheck pnpm test # every package's tests, one package at a time; on a Mac also apps/mac's swift test pnpm -r --filter "./packages/*" build # the packages only: what CI builds and tests (Linux) pnpm --filter @linkshell/host test # one package (vitest) ``` Run the pieces from the checkout: ```bash cd packages/cli && npx tsx src/index.ts host --dev-port 7878 # a host that also serves its API on ws://127.0.0.1:7878 (loopback, development only) pnpm dev:app # Metro for the app (expo start) pnpm dev:ios # development build "LinkShell Dev" (com.bd.linkshell.v2), installs beside the released app pnpm dev:android pnpm dev:gateway # the gateway from source (tsx src/main.ts), port 8787, data in packages/gateway/data/relay.db pnpm dev:cli # the CLI from source (tsx src/index.ts) ``` - A development build of the app connects to `ws://127.0.0.1:7878` by default (`EXPO_PUBLIC_LINKSHELL_HOST`, `apps/client/src/lib/settings.ts`). - `LINKSHELL_HOME=` gives a host its own state directory, so a development host doesn't share `~/.linkshell` with the installed one. - The CLI compiles the host's and the gateway's sources too: after changing either, run the full `pnpm build` and `pnpm typecheck`, not just one package's. - Real agents: `pnpm --filter @linkshell/host live:codex` / `live:claude` (need the agent installed and signed in; `live:claude` from your own terminal). LinkShell.app (`apps/mac`, Swift; macOS 13+, Apple silicon and Intel, Xcode's Swift): ```bash pnpm --filter @linkshell/mac build # build/LinkShell.app and build/LinkShell.app.tar.gz pnpm --filter @linkshell/mac test # swift test: what needs no screen and no network pnpm --filter @linkshell/mac check # that, then pass or fail for the built app (about a minute) ``` Without a Developer ID certificate it is signed ad hoc: fine for development, a different app to macOS (its own permissions), never for release. See `apps/mac/README.md`. App release builds: `pnpm prod:ios` / `pnpm prod:android` (`apps/client/scripts/release.mjs`; always a clean prebuild of the release variant — there is no quick variant). ## Project Structure - `packages/wire` (`@linkshell/wire`) — what the host, the gateway and the app share. `model.ts` + `updates.ts` (sessions and their events, ACP-shaped), `rpc.ts` (the host's JSON-RPC methods and notifications, zod), `peer.ts` (JSON-RPC peer), `crypto.ts` (identities, signatures, channel keys), `relay.ts` (gateway frames, pairing link, the end-to-end tunnel), `relay-client.ts` (one connection to a gateway), `direct.ts` (direct-channel framing). - `packages/host` (`@linkshell/host`) — the daemon. `host.ts` (`startHost`, paths), `hub.ts` (`SessionHub`), `store.ts` (SQLite `state.db`), `drivers/` (`codex/` app-server, `claude/` handoff, `acp/` everything else, `registry.ts`), `rpc/server.ts` (every RPC method), `gateway.ts` (`GatewayLink`: identity, pairing, tunnels), `direct.ts` (WebRTC data channel, werift), `terminals.ts` (node-pty), `ports.ts` (previews), `screen.ts` + `screen-viewer.ts` + `screen-pacer.ts` + `input.ts` (the screen), `fusion.ts` (starts the remote half of Fusion), `worktrees.ts`, `fs.ts`. - `packages/gateway` (`@linkshell/gateway`) — the relay; the official gateway and a self-hosted one are this same package. `relay.ts` (`Gateway`: auth, routing, pairing, backpressure), `store.ts` (SQLite), `accounts.ts` (`supabaseVerifier`), `subscription.ts` (the Pro check), `rate-limit.ts`, `serve.ts` (`startGateway`: HTTP server, `/healthz`, the upgrade), `main.ts` (the executable: env → `startGateway`), `index.ts` (exports only). `Dockerfile` builds `nickname4th/linkshell-gateway`. - `packages/cli` (`linkshell-cli`, bin `linkshell`) — commander commands in `src/index.ts` and `src/commands/*`; `auth.ts` (the account), `utils/daemon.ts` (background processes, pid and log files). - `packages/client-core` (`@linkshell/client-core`) — client state without UI: `host-link.ts` (RPC connection), `tunnel-socket.ts` (that connection through a gateway), `store.ts` (zustand), `timeline.ts` (event log → what is rendered), `streams.ts` (byte streams for previews and the screen), `pairing.ts`. - `apps/client` (`@linkshell/client`) — the app: Expo + React Native + Expo Router. Routes in `src/app/`, screens in `src/screens/`, `src/lib/` (`client.tsx`, `computers.ts`, `identity.ts`, `account.ts`, `direct.ts`), native modules in `modules/` (`link-terminal`, `link-socket`, `link-screen` for iOS WebRTC/Metal screen reception). Read `apps/client/AGENTS.md` before touching Expo APIs. - `apps/mac` (`@linkshell/mac`) — LinkShell.app: captures the Mac's screen, sends it (WebRTC video, or encoded for the host), posts pointer and key events, and holds the two macOS permissions. Shipped to npm as one helper archive, and as separate notarized arm64/x64 standalone DMGs with bundled Node/CLI/Host, the Electron window and Sparkle updates; see `docs/mac-desktop.md`. - `apps/desktop` (`@linkshell/desktop`, private) — the desktop window: Electron 44 inside the same LinkShell.app (same bundle id and signature; the Swift executable `execv`s into `LinkShell Desktop` when the user opens the app). Main process (window, menus, IPC for 本机管理 through the bundled CLI), preload bridge, `LinkShellNative.node` (permissions, login item, Sparkle). `scripts/package.mjs` puts Electron into a built LinkShell.app and signs it; `scripts/electron-dist.mjs` fetches the other architecture's Electron; `apps/mac/scripts/build-standalone.mjs` runs both for each DMG. On Windows the same main process ships as `LinkShell.exe` (`apps/windows`: `scripts/electron.mjs` assembles it, beside the native screen helper and installer). The workspace it shows is `apps/desktop-ui`. See `docs/design/desktop-electron-plan.md`. - `apps/desktop-ui` (`@linkshell/desktop-ui`, private) — the desktop workspace: React 19 for Electron 44's Chromium only (native `` / popover, no Radix). `src/core/` (engine, router, stores, i18n tables), `src/features/` (`shell`, `session`, `inspector`, `remote`, `system`), `src/bridge/` (the `{action}` messages to the main process, shortcuts), `src/primitives/`, `src/styles/`. `pnpm --filter @linkshell/desktop start` runs it in a development window (set `LINKSHELL_HOME`). `apps/web` is the gateway's browser client only. Read `apps/desktop-ui/AGENTS.md` first. - `docs/site` — the website (served at `https://linkshell.itool.tech/`), plus `install.sh` and the desktop update feeds, which stay on GitHub Pages because shipped software points there. Edit `index.src.html`, then run `python3 scripts/build-site-pages.py`; never edit the generated `index.html` files. `~/seos/deploy.sh linkshell` copies the site and deploys it with Luma. - `docs/v2/architecture.md` (design), `docs/v2/screen-realtime.md` (current screen architecture, diagrams, fallback and validation), `docs/deploy.md` (self-hosting), `docs/release-sop.md`. - `docs/v2/session-recovery.md` — current session status, native archive and history recovery rules, ACP version compatibility, and validation boundaries. ## Architecture ### The host and its files `linkshell host --daemon` starts the host detached; local clients (the CLI, `linkshell claude` / `codex`) reach it over a unix socket. State is in `~/.linkshell` (`LINKSHELL_HOME` moves it): | File | What | | --- | --- | | `state.db` | sessions and their event logs (SQLite) | | `identity.json` | this computer's keys (0600); its id derives from the signing key | | `machine.json` | the machine id shown in `machine.info` | | `paired-devices.json` | phones paired with it, with their keys (0600) | | `config.json` | the chosen gateway (`off` is a choice), whether setup has run | | `auth.json` | the account from `linkshell login` (0600) | | `access.json` | the optional access password: scrypt hash and the secret unlock tokens are signed with (0600); absent = no password | | `run/host.sock`, `run/codex.sock` | the host's API; the shared Codex app-server | | `host.pid`, `host.log`, `gateway.pid`, `gateway.log` | background processes | | `relay.db` | pairings, when this computer runs `linkshell gateway` | | `worktrees/` | git worktrees made for sessions | | `LinkShell.app` | unpacked from `@linkshell/mac` for CLI installs; standalone installs use their own signed bundle | Agents run as the user with the login shell's environment; LinkShell never handles their credentials. ### From phone to host 1. **Relay auth.** Host (role `machine`) and app (role `device`) each open a WebSocket to `/v2/connect`. The gateway sends a nonce; the peer signs `linkshell-gateway-v2:${nonce}` with its Ed25519 key, and may add an account token. 2. **Who may reach whom.** A device reaches a machine it is **paired** with, or one on the same **account**. Pairing: `linkshell pair` asks the gateway for a 6-digit code (10 minutes) and shows a QR code (`linkshell://pair?…`: gateway, the machine's signing key, a one-time secret, the code); the app claims by scan or by code; the host checks the proof and decides. Account: both sides signed in (`linkshell login`, and in the app) — no pairing. 3. **End-to-end channel.** The device opens a tunnel (`hello` / `welcome`, ephemeral X25519 keys signed by the long-term keys); after that every frame is sealed with XChaCha20-Poly1305. The gateway sees only ciphertext. The host accepts a `hello` only from a device in `paired-devices.json` with the same keys, or, when signed in, one the gateway says shares its account. 4. **RPC.** Inside the tunnel: JSON-RPC (`packages/wire/src/rpc.ts`) — `sessions.*`, `terminals.*`, `fs.*`, `ports.list` / `proxy.*`, `screen.*`, `direct.offer`, …; the host pushes `session.event` (per-session `seq`, resumable). **Access password (optional).** With `access.json` present, a remote connection gets only `machine.info` (trimmed, `locked: true`) and `access.unlock` until it gives the password; nothing is pushed to it. A correct one returns a device-bound token (7 days) the client keeps, so reconnects don't ask. Local connections never ask. Set on the computer only (`linkshell password`, or the desktop's 电脑 page). The host tells the gateway `locked` in its `auth` frame (memory only, no schema change) so devices show a lock; older gateways and apps ignore it, and an older app on a locked computer sees the error message. 5. **Direct data channel.** For bulk streams (port previews, the viewer's HTTP/WebSocket and compatible screen bytes) the device sends a WebRTC offer over RPC (`direct.offer`). This is a separate connection between the Node host (werift) and client; its `direct` status does not prove that a screen video track is connected. `LINKSHELL_ICE_SERVERS` sets STUN servers; `off` disables this bulk channel and removes STUN from screen media, but the latter can still try LAN candidates. **TURN.** A gateway with `TURN_SECRET` + `TURN_URLS` lends computers short-lived coturn credentials (`turn.credentials`, machines only; the host fetches them on sign-in and keeps them for half their life). The screen's video then tries, in ICE's own order, direct paths first, the TURN relay next (held to `TURN_MAX_KBPS`, 3000 by default), and only when no video track connects the byte relay through the gateway. All of this is only for a viewer that says `turn=1` (the viewer page says it in a browser, or inside an app that asked for it): an older receiver drops the TURN login, WebRTC then refuses the whole configuration, and an older app takes an idle end for a failure, so an older viewer gets the screen exactly as before, with no TURN on either side and no idle end. For a new viewer, a picture that costs relay traffic, through TURN or through the gateway, is ended after 3 minutes no one uses it (`LINKSHELL_SCREEN_IDLE_SECONDS`); reconnecting goes straight back to the way that worked. `LINKSHELL_TURN=off` keeps a host off TURN. coturn's deployment: `deploy/turn/`. 6. **The screen.** `screen.start` returns a loopback viewer port, token and displays. A desktop viewer may add `match=WxH@scale` (its own screen): a Mac being watched then makes a virtual display of that size and has the watched display mirror it for as long as the viewer watches (`ScreenMatch.swift`; not while the Mac is a Fusion remote; `docs/v2/screen-realtime.md` §5.1). The phone forwards that port; the web client loads the same page in an isolated iframe. The viewer/native receiver's socket carries SDP/ICE via the host to LinkShell.app. On a Mac, ScreenCaptureKit → low-latency VideoToolbox H.264 → libwebrtc sends a **video track directly to the receiver**, with four DataChannels for input and cursor. The host and gateway do not carry that media. The default encoder is `own`, with stock H.264 fallback; FlexFEC is offered but requires receiver negotiation. 7. **iOS reception and fallback.** `apps/client/modules/link-screen` defaults to native WebRTC decode → latest decoded-frame mailbox → Metal presentation, requesting up to 120 fps subject to source/receiver displays, power, thermal state and adaptation. The transparent WebView retains controls, gestures and cursor; WebKit sends input directly to Swift, bypassing RN JS, and frames never enter JS. Failure tries standard WebView WebRTC, then forces that screen's bytes onto RPC (`direct:false`); retry starts native again. Android/Web retain the standard viewer and its byte-stream fallback. On Mac the fallback is also captured/encoded by LinkShell.app, paced by `screen-pacer.ts` and decoded with WebCodecs/Canvas. Linux uses ffmpeg/X11 for this path and has no control. The universal Mac app supports Apple silicon and Intel on macOS 13+; Intel capture, hardware encoding and end-to-end performance still require real-hardware validation. Windows screen capture is unsupported. A new iOS binary is required for native module changes; stable 120 fps, stable 4K/60 and real-device weak-network gains remain unproven. See `docs/v2/screen-realtime.md` for the current route and known periodic stutter. 8. **Fusion (融合模式, desktop only: Mac and Windows, either side).** One remote app's windows shown as local windows, each remote app as its own app in the local Dock and ⌘Tab. Spec: [docs/v2/fusion.md](docs/v2/fusion.md) (protocol v2; schema `packages/wire/src/fusion.ts`, fixtures shared by the Swift and TS tests; not compatible with 0.10.10x). `fusion.start` (the host checks Screen Recording and Accessibility, returns port, single-use token, `proto`, `platform`) launches `LinkShell --fusion-remote` on the remote Mac: it copies the local displays as virtual displays and sends every window, plus each display's popup layer, as one video transceiver on **one** WebRTC peer connection (`Fusion/Remote/FusionMedia.swift`), with geometry stamped on the frames; input names its window (`stream`; `k` is a key's name). On the local Mac the desktop's main process starts `LinkShell --fusion-local` (one hub per computer, `~/.linkshell/fusion-.sock`; the hash is 12 hex of the computer key, the same on both sides) and the hub generates one stub app per remote app under `~/Applications/LinkShell//`, which draws the windows and sends input back. The control connection (hello/welcome handshake, window lists, launches, clipboard, SDP) is TLS 1.2 with a pre-shared key derived from the token, which travels inside the end-to-end tunnel and through the environment or a 0600 socket, never argv; it goes directly over LAN / Tailscale when a probe reaches the remote, otherwise through the tunnel. A drop without `bye` is resumed within 30 s (the remote keeps displays and windows, the hub keeps its stubs); ending sends `bye`, and the remote puts every moved window back, removes the virtual displays and restores the Dock. The remote Mac shows a menu bar item with 结束融合. Viewing the page never starts Fusion; Disconnect sticks. Windows: the local half is the desktop app itself (`apps/desktop/src/main/fusion/electron-hub.ts` + the hidden page `apps/desktop-ui/fusion.html`: one peer connection, windows it opens with `window.open`, crop metadata read from the SEI through encoded insertable streams, AppUserModelID per remote app for the taskbar); the remote half is the host itself (`packages/host/src/fusion/`: `FusionNodeRemote`, werift media, `LinkShell.Screen.exe --fusion` / `--fusion-video` with FFmpeg's gfxcapture). `LINKSHELL_FUSION_HUB=electron` runs the Windows local half on a Mac and `LINKSHELL_FUSION_SIMULATED=1` makes any host a remote with a test-picture app, so `apps/desktop/scripts/fusion-e2e.mjs` runs both on one Mac. TLS suites must stay ones Electron's BoringSSL has (no PSK-AES-GCM there). Not built yet: cursor shapes from a Windows remote, files on the clipboard (text and pictures are shared on every pair; RTF between Macs only), audio, drag and drop, notification mirroring. Two computers are needed for the real thing: unit tests and the one-Mac E2E cover the wire, the media path with a simulated remote, the store and the pure logic. ### Gateway (`packages/gateway`) - WebSocket `/v2/connect`, `GET /healthz` → `{ ok, version, relay, memoryMb }` (`relay`: connected peers), and the bundled current-protocol web client at `/`. `/config.js` selects account or pairing-only mode from gateway settings; unknown paths remain 404. - Data: one SQLite file (peers' public keys and account, machine↔device links). `RELAY_DATA_PATH`, default `./data/relay.db`; the Docker image uses `/data/relay.db`; `linkshell gateway` uses `~/.linkshell/relay.db`. Losing it unpairs every phone. - Env: `PORT` (8787), `LOG_LEVEL`, `RELAY_DATA_PATH`, `TRUSTED_PROXIES` (IPs or IPv4 ranges whose `X-Forwarded-For` is believed), `WS_CONNECT_RATE_LIMIT_MAX` / `WS_CONNECT_RATE_LIMIT_WINDOW_MS` (20 connects a minute per IP, loopback exempt), `SUPABASE_URL` + `SUPABASE_ANON_KEY` (account tokens are verified), `AUTH_REQUIRED` + `SUPABASE_SERVICE_ROLE_KEY` (a computer needs an active iTool membership), `TURN_SECRET` + `TURN_URLS` (coturn's static-auth-secret and its `stun:`/`turn:` URLs; `TURN_TTL_SECONDS`, `TURN_MAX_KBPS`). - Official vs self-hosted: the same code. A self-hosted gateway has no Supabase variables: pairing only. The official one (`gateway.itool.tech`, `luma-gateway.yml`) adds account verification and, through `admit`, the membership check for computers — at connect only; a failed lookup admits. ### CLI commands `setup` (host, screen permissions, phone — once), `host [--daemon] [--gateway ] [--dev-port ]` with `host status` / `host stop`, `pair`, `devices` / `devices remove `, `password` / `password set` / `password remove`, `claude` / `codex` (the agent's own UI attached to the host; arguments pass through), `screen [--check]`, `doctor [--gateway ]`, `login`, `logout`, `upgrade`, `status`, `stop`, `gateway [--port] [--daemon]` with `gateway status` / `gateway stop`. Bare `linkshell` runs the setup on a computer that has never had it. ## Never rename Every paired phone and every installed host depends on these. Changing one silently breaks or unpairs users. - `RELAY_PATH = "/v2/connect"` (`packages/wire/src/relay.ts`). - The challenge string `linkshell-gateway-v2:${nonce}` (`packages/wire/src/crypto.ts`). The "v2" in both is part of the protocol, not a version to tidy up. - The relay's SQLite schema (`packages/gateway/src/store.ts`: tables `peers`, `links`) and production's data file `/data/relay.db` on the volume in `luma-gateway.yml`. - LinkShell.app's bundle id `com.bd.linkshell.host` and its Developer ID signing identity: macOS keeps the Screen Recording and Accessibility grants against the pair. ## Release Checklist: [docs/release-sop.md](docs/release-sop.md). When the user asks to release LinkShell, execute the full release workflow, including publication and deployment. The user explicitly exempts LinkShell from the preparation-only rule used for other projects. Use the preparation-only lane only when the user explicitly requests it. - npm, always `pnpm publish` (it rewrites `workspace:*`), in dependency order: wire → mac → host → gateway → cli; skip what didn't change. - `@linkshell/mac` must be published from a Mac with the Developer ID Application certificate (`prepack` refuses to build unsigned). - Tag `gateway-vX.Y.Z` → CI builds and pushes `nickname4th/linkshell-gateway` (`.github/workflows/docker-publish.yml`). That only publishes the public image. Deploy the official gateway from a pushed commit with `bash scripts/deploy-luma.sh`; the independent Builder publishes to ACR. - Standalone desktop: `desktop-vX.Y.Z` ships notarized architecture-specific DMGs, then publishes Sparkle feeds to Pages. Bundle CLI/Host changes in a new desktop release too; do not make users run npm updates inside the app. See `docs/release-sop.md`. - Tag `cli-vX.Y.Z` marks a CLI release (no CI). `./scripts/update-brew.sh` updates the Homebrew tap. - Mobile app (`vX.Y.Z`) → built and released locally on macOS (`./scripts/release-mobile.sh X.Y.Z --yes`, or `node scripts/release.mjs ios|android X.Y.Z` + `gh release create vX.Y.Z`): iOS to TestFlight, Android AAB + APK to a GitHub release. There is no GitHub Actions runner for mobile builds. - `docs/site/` deploys to GitHub Pages on push to main (`.github/workflows/pages.yml`). Install channels: `npm i -g linkshell-cli`, `brew install LiuTianjie/linkshell/linkshell`, `curl -fsSL https://liutianjie.github.io/LinkShell/install.sh | sh`. ## Auth & Backend - Supabase project `mkbeusztkzffnzjdwmqk`, shared with iTool. Sign-in happens at `https://itool.tech/en/auth/linkshell`; the CLI keeps the tokens in `~/.linkshell/auth.json`, the app in the Keychain. - Membership: one iTool membership, bought with Alipay at `https://itool.tech/pro?from=linkshell` only (monthly ¥9.9 = iTool site + LinkShell, yearly ¥99 = every product). LinkShell's product key is `linkshell` (required tier `monthly`). Clients read `itool_entitlement('linkshell')` with the user's token, through `GET https://itool.tech/api/membership/entitlement?product=linkshell` (bearer; for networks that block supabase.co) or the RPC directly; the official gateway calls `itool_entitlement_for(uid, 'linkshell')` with the service-role key, and its answer is the one that counts. No activation codes; the phone app and the watch never link to the buy page (App Store rules), they only say to open itool.tech/pro on a computer. - The gateway verifies an account token against `${SUPABASE_URL}/auth/v1/user`. - The `linkshell_*` tables in that project are left from 1.x. No code reads them; don't drop them. ## Conventions - Commit style: `feat:`, `fix:`, `docs:`, `release:` - Chinese UI text in the app and in the screen's viewer page (`packages/host/src/screen-viewer.ts`); errors the phone shows are Chinese too - English in README.md, Chinese in README_CN.md; keep the two saying the same - Comments say why, not what - Every surface (app, desktop, web console, site) follows one visual system: [docs/design/visual-system.md](docs/design/visual-system.md), with brand and status colours in `apps/client/src/theme/brand-colors.json`. Change those first, then all surfaces together; never restyle one end alone