What It Does — Your Terminal, In Your Pocket
clsh solves a specific problem for Claude Code users: you start a long refactor or multi-file task, then need to step away from your desk. Instead of hoping everything works, clsh gives you real terminal access to your Mac from your phone. It's not SSH with a painful mobile keyboard—it's a real PTY streamed to your browser with a custom 6-row developer keyboard that has ctrl, arrows, escape, and all the keys you actually need for terminal work.
The key innovation is the phone-first UX. The bottom half of your screen becomes a proper terminal keyboard while the top shows your actual terminal session. This means you can:
- Watch Claude Code execute commands in real time
- Scroll through diffs it generates
- Hit ctrl+c if something goes wrong
- Approve commits or continue prompts
- All from your phone while away from your desk
Setup — One Command, Zero Config
Installation is dead simple:
npx clsh-dev
That's it. The command starts a backend agent on your machine and prints a QR code to your console. Scan it with your phone's camera and you're connected. Your phone gets a real terminal session with your shell, aliases, and environment.
For persistent access (perfect for adding to your phone's home screen as a PWA):
npx clsh-dev setup
This configures a static URL via ngrok that survives restarts. The tunnel system supports three options: ngrok (static URL), SSH (localhost.run), or direct Wi-Fi connection.
When To Use It — Specific Claude Code Workflows
1. Long-Running Claude Code Tasks
When Claude Code is processing a large codebase refactor, database migration, or test suite run, you can monitor progress from anywhere. The real PTY means TUIs render correctly—you'll see exactly what you'd see on your desktop terminal.
2. Emergency Intervention
If Claude Code starts doing something unexpected (infinite loops, wrong file modifications), you can immediately hit ctrl+c from your phone. No more waiting to get back to your desk while it wreaks havoc.
3. Approval Workflows
Claude Code often needs human approval for commits, file overwrites, or destructive operations. With clsh, you can review diffs and approve from your phone instead of being tethered to your desk.
4. Multi-Session Monitoring
clsh supports up to 8 concurrent terminal sessions with a grid view showing live previews. You could have Claude Code running in one session, logs in another, and your regular shell in a third—all visible from your phone.
Technical Details That Matter
- Real PTY via node-pty: Not a simulation—actual terminal sessions with full color support
- tmux persistence: If tmux is installed, sessions survive server restarts automatically
- Custom keyboard features: Sticky modifiers (tap ctrl once, it stays active), key repeat, context strip with esc, F1-F5, commit, diff, plan, and ctrl+c shortcuts
- Multiple layouts: iOS Terminal (6-row, big keys) or MacBook (5-row, compact)
- PWA installable: Add to home screen for app-like experience
Security Considerations
The developers take security seriously—this gives remote terminal access to your machine. The system uses one-time bootstrap tokens and QR code authentication. All communication happens over HTTPS via WebSocket. The code is open source (MIT licensed) with no cloud dependencies beyond the tunnel provider.
Try It Now
- Make sure you have Node.js 20+ installed
- Run
npx clsh-devon your Mac - Scan the QR code with your phone
- Try running Claude Code from your phone:
# In your clsh terminal
cd ~/your-project
claude code --task "Refactor authentication module"
You'll see the exact same output as on your desktop, with the ability to interact when needed.
