clsh

clsh is an open-source tool that turns your Mac into a pocket-sized terminal server. Run npx clsh-dev, scan the QR code on your phone, and you have a real PTY session — not SSH emulation, not a simulation — streamed securely to your mobile browser or installed PWA. The project is MIT-licensed and hosted on GitHub under the my-claude-utils organization.

What It Is

clsh is a phone-first remote terminal client for macOS (and Linux). It spawns real shell sessions using node-pty on your local machine, wraps them optionally in tmux for persistence, and exposes them over HTTPS via a 3-tier tunnel system (ngrok → localhost.run SSH → local Wi-Fi). A custom React + xterm.js frontend renders the terminal with full color, vim support, and a purpose-built mobile keyboard. The project is particularly aimed at developers who want to run AI coding agents like Claude Code from their phone and watch them work in real time.

How the Tunnel Architecture Works

clsh uses a layered fallback approach so it works in almost any network environment:

• ngrok (static domain) — recommended for PWA home screen use; same URL survives restarts
• localhost.run SSH tunnel — zero signup, works anywhere, auto-fallback
• Local Wi-Fi — zero dependencies, LAN-only

The tunnel can be forced via environment variables (TUNNEL=ssh, TUNNEL=local). A one-time bootstrap token with a 5-minute TTL and QR code delivery authenticates the phone on first connect; subsequent connections use JWT.

Security Model

Because clsh grants remote shell access to your machine, the project treats security as a first-class concern. Key protections include:

• One-time bootstrap tokens (single-use, 5-min TTL) passed in the URL hash fragment (never sent to servers)
• scrypt password hashing (N=16384, 64-byte key, random salt) with constant-time comparison
• WebAuthn / Face ID biometric auth for PWA lock screen
• HTTPS enforced via tunnel, CORS restricted to known origins, security headers (CSP, X-Frame-Options, X-Content-Type-Options)
• Auth endpoint rate limiting (5–10 requests per 15 minutes)
• WebSocket origin validation, 64KB max payload, resize dimension bounds checking
• Responsible disclosure policy at security@clsh.dev with a stated 48-hour response time

Mobile-First Terminal Experience

The frontend is built specifically for phone use, not adapted from a desktop UI:

• Custom keyboard with two layouts: iOS Terminal (6-row, large keys) and MacBook (5-row, compact)
• Sticky modifiers — tap Shift/Ctrl/Opt/Cmd once, it latches for the next key
• Key repeat — hold any key for auto-repeat (400ms delay, 60ms interval)
• Context strip — quick-access row for Esc, F1–F5, commit, diff, plan, Ctrl+C
• 6 keyboard skins — iOS Terminal, MacBook Silver, Gamer RGB, Custom Painted, Amber Retro, Ice White
• PWA install — fullscreen standalone mode, iOS keyboard suppressed, safe-area insets for Dynamic Island and notch devices
• Session grid — up to 8 concurrent PTY sessions with live 2-column card previews

Tech Stack

The project is a TypeScript monorepo managed with Turborepo and npm workspaces:

Update: v0.1.9 — Native Keyboard Support

The latest release is v0.1.9, published in March 2026 and titled "Native Keyboard Support." The repository was last updated in September 2026 and has accumulated 526 stars and 54 forks since its creation in March 2026. The roadmap lists upcoming features including remote cloud containers, team session sharing with presence, native iOS/Android apps, and Claude Code tool extensions.