Package Exports

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (remote-iterm2) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

remote-iterm2

Control your macOS iTerm2 from your phone over local network.

Fork of remote-iterm with mobile Safari fixes and key handling improvements.

Install

npm install -g remote-iterm2

Usage

remote-iterm2          # start
remote-iterm2 stop     # stop
remote-iterm2 restart  # restart

Open the printed URL on your phone (same Wi-Fi network).

Configuration

Create ~/.remote-iterm2.json to customize behavior:

{ "tabColor": false }

Option	Default	Description
`tabColor`	`true`	Automatically set tab background color when focusing a window. Set to `false` to preserve manually set tab colors.

What's Changed (v1.1.0)

Mobile Safari white screen fix — Built frontend as static files served by Express on a single port, eliminating the socket.io-client ESM incompatibility with Vite dev server
Key sending overhaul — Control chars (DEL, ESC, ^C, ^D, etc.) now sent via iTerm AppleScript write text (character id N), Enter uses write text "" with default newline. Fixes DEL printing garbage and Enter not executing in apps like Claude Code
osascript path fix — Uses full path /usr/bin/osascript to avoid "not found" errors in Node.js subprocesses
Quick Actions reorder — Enter button moved to the front: Enter → ESC → ^C → ^D → ^Z → ^L
Single port mode — Only port 7291 needed (no separate Vite dev server)

Features

Real-time terminal output with syntax coloring
Tab management (create, close, rename via long-press)
Multi-window support with spatial map
Broadcast commands to multiple windows
Command history with arrow navigation
Virtual keyboard with terminal keys
Quick action buttons (Enter, ESC, ^C, ^D, ^Z, ^L, etc.)
Clipboard paste/copy
Landscape mode optimized for iPhone
Dynamic Island / notch safe area handling
Connection latency indicator
Screen wake lock
Long-running command alert
Scroll lock
Split pane view
PWA — add to home screen

Requirements

macOS with iTerm2
Node.js >= 18
Phone on the same Wi-Fi

Documentation

User Guide — Full-featured bilingual (Chinese / English) manual with dark theme, sidebar navigation, and responsive design.

Manual Setup

git clone https://github.com/richardhuang/remote-iterm2.git
cd remote-iterm2
cd server && npm install && cd ../client && npm install
cd client && npx vite build && cd ..
./iterm-server

Ports

7291 — HTTP server + WebSocket (single port)

License

MIT