Access your terminal and your AI agent from any device — phone, tablet, desktop.
# Add to your Claude Code skills
git clone https://github.com/my-claude-utils/clshYour Mac, in your pocket.
Real terminal access from your phone. Not SSH. Not a simulation. A real PTY on your machine, streamed to your pocket.
Live Demo · Getting Started · How It Works · Contributing
clsh gives you real terminal access to your Mac from your phone. One command, scan the QR code, and you're in. Multiple live terminal sessions, a custom keyboard built for terminal use, 6 keyboard skins, and session management. Open source, zero config.
Key highlights:
Requires Node.js 20+ and macOS or Linux.
npx clsh-dev
A QR code prints to the console. Scan it on your phone. That's it.
No comments yet. Be the first to share your thoughts!
For a static URL that survives restarts (perfect for PWA home screen):
npx clsh-dev setup
See the ngrok setup guide for details.
Phone / Tablet / Browser
│
│ HTTPS (WebSocket)
▼
┌──────────────┐
│ Tunnel │ ngrok (static URL) / SSH (localhost.run) / Wi-Fi
└──────┬───────┘
▼
┌──────────────────────┐
│ clsh agent │ ← runs on your machine
│ ├── PTY 0: zsh │
│ ├── PTY 1: claude │
│ ├── PTY 2: ... │
│ └── up to 8 sessions │
└──────────────────────┘
npx clsh-dev starts the backend agent + React frontendnode-ptySecurity is our top priority. clsh gives remote terminal access to your machine, so any vulnerability could mean full machine compromise. We take this extremely seriously.
| Layer | Protection |
|-------|-----------|
| Authentication | One-time bootstrap tokens (single-use, 5-min TTL), scrypt password hashing (N=16384, 64-byte key, random salt), WebAuthn/Face ID biometric auth |
| Token security | JWT issued via HS256, bootstrap token passed in URL hash fragment (never sent to servers), WebSocket auth via first message (not query string) |
| Transport | HTTPS enforced via ngrok/SSH tunnels, CORS restricted to known origins, security headers (X-Frame-Options, X-Content-Type-Options, CSP) |
| Rate limiting | Auth endpoints: 5-10 requests per 15 minutes, prevents brute force |
| WebSocket | Origin validation on upgrade, 64KB max payload, resize dimension bounds checking |
| Password storage | Server-side scrypt with crypto.timingSafeEqual (constant-time comparison prevents timing attacks) |
| PWA support | Lock screen with Face ID + password, biometric credentials synced server-side for cross-context restoration |
Found a vulnerability? Please report it. See SECURITY.md for our disclosure policy, or email security@clsh.dev directly. We respond within 48 hours.
We believe in transparency. If you find something, open a security advisory or email us. We will credit all responsible disclosures.
npx clsh-dev
Connects through localhost.run — a free SSH tunnel. No signup, no tokens. A QR code prints to the console with the HTTPS URL.
For a static domain that survives restarts — perfect for a home screen PWA:
brew install ngrok
ngrok config add-authtoken YOUR_TOKEN # free at ngrok.com
Create a free static domain at dashboard.ngrok.com/domains, then:
# .env (project root)
NGROK_AUTHTOKEN=your_token
NGROK_STATIC_DOMAIN=your-subdomain.ngrok-free.dev
If no tunnel works, clsh falls back to your local IP. Same LAN only.
TUNNEL=ssh npx clsh-dev # force SSH tunnel
TUNNEL=local npx clsh-dev # force local Wi-Fi only
When tmux is installed, clsh automatically wraps sessions in tmux using control mode (-CC). This means your terminal sessions survive server restarts — stop clsh, start it again, and your sessions are still there with full scrollback history.
# Install tmux (if not already installed)
brew install tmux # macOS
sudo apt install tmux # Ubuntu/Debian
No configuration needed. clsh auto-detects tmux and enables persistence. If tmux isn't installed, sessions work normally but are ephemeral (lost on restart).
To disable persistence even with tmux installed:
CLSH_NO_TMUX=1 npx clsh-dev
How it works under the hood: clsh uses tmux control mode (-CC) instead of normal tmux attachment. Control mode sends raw terminal output as structured notifications (%output) instead of screen redraws, which means xterm.js gets the original byte stream and scrollback works perfectly. User input is forwarded via send-keys -H (hex-encoded). On server restart, capture-pane recovers the existing scrollback and control mode resumes live streaming.
By default, macOS powers down Wi-Fi about 30 seconds after you close the lid, even if the CPU is still running. This kills the tunnel and your phone loses connection.
If you want clsh to stay reachable with the lid closed (while plugged in), run this once:
sudo pmset -c tcpkeepalive 1
This tells macOS to keep network connections alive during display sleep on AC power. It persists across reboots. clsh will print a reminder on startup if this isn't configured.
What it does: Keeps Wi-Fi and TCP connections alive when the lid is closed and the Mac is charging. Your phone stays connected to clsh without interruption.
What it doesn't do: This has no effect on battery. When unplugged with the lid closed, macOS forces full sleep regardless. There's no software workaround for that.
To undo:
sudo pmset -c tcpkeepalive 0
Note: Even without this setting, clsh auto-recovers when you open the lid. The tunnel recreates itself and your phone reconnects automatically.
With a permanent ngrok URL, add clsh as a PWA:
It runs fullscreen — no URL bar, no browser chrome. Looks like a native app.
| Skin | Vibe | |------|------| | iOS Terminal | Default — big letter keys, iOS-style, optimized for phone | | MacBook Silver | Traditional MacBook aluminum — compact 5-row