A mobile-first PWA terminal client for running Claude Code via SSH from your smartphone.
Perfect for coding on the couch! 🛋️
- Mobile-optimized terminal with xterm.js
- Shortcut button bar for keys difficult to type on mobile (↑, ↓, Tab, Esc, Ctrl-C, Backspace, Enter)
- Keyboard-aware UI - button bar moves above the iOS keyboard
- Auto-reconnect when returning from background
- Keep-alive pings to maintain connection stability
- PWA support - install on your home screen for app-like experience
┌─────────────────┐ WebSocket ┌─────────────────┐ SSH ┌─────────────────┐
│ iPhone/iPad │◄──────────────────►│ Proxy Server │◄──────────────►│ Your Mac/PC │
│ (PWA Client) │ Port 3001 │ (Bun/Node) │ Port 22 │ (Claude Code) │
└─────────────────┘ └─────────────────┘ └─────────────────┘
Since browsers cannot make direct SSH connections, the proxy server bridges WebSocket and SSH protocols.
- Bun runtime installed
- SSH access to your development machine
- Both devices on the same network (or use port forwarding)
# Clone the repository
git clone https://github.com/TSJim/CCterm.git
cd CCterm
# Install dependencies
bun install# Start the development server (runs both PWA and WebSocket proxy)
bun devThis starts:
- PWA: http://localhost:3000
- WebSocket Proxy: ws://localhost:3001/ws
- Find your computer's local IP address (e.g.,
192.168.1.100) - Open
http://192.168.1.100:3000on your mobile browser - Add a server with your SSH credentials
- Tap "Connect" and start using Claude Code!
Servers are stored in your browser's localStorage. You can:
- Use the "Manage Servers" button in the UI
- Or edit
src/utils/sshServerStorage.tsfor default servers
Edit server/index.ts to change the default port (3001):
const PORT = 3001The shortcut button bar provides easy access to keys that are difficult to type on iOS:
| Button | Action |
|---|---|
| ↑ | Previous command (history) |
| ↓ | Next command (history) |
| Tab | Auto-complete |
| Esc | Cancel/Exit |
| Ctrl-C | Interrupt running process |
| ⌫ | Backspace |
| Enter | Execute command |
Due to iOS PWA limitations, the connection may drop when switching apps. The app will automatically reconnect when you return. For longer sessions, consider keeping the app in foreground.
├── server/
│ ├── index.ts # WebSocket proxy server (Bun)
│ └── ssh-handler.ts # SSH connection management (ssh2)
├── src/
│ ├── app/
│ │ ├── page.tsx # Home page with server list
│ │ └── terminal/ # Terminal page
│ ├── components/
│ │ └── organisms/
│ │ └── CoTerminal.tsx # Terminal component (xterm.js)
│ └── utils/
│ ├── websocketClient.ts # WebSocket client
│ └── sshServerStorage.ts # Server storage (localStorage)
└── package.json
- Frontend: Next.js 15, React, TypeScript
- Terminal: xterm.js with fit and web-links addons
- Styling: vanilla-extract (CSS-in-JS)
- Backend: Bun with native WebSocket support
- SSH: ssh2 library
# Start dev server with hot reload
bun dev
# Run type checking
bun typecheck
# Run linting
bun lint
# Build for production
bun run build-
iOS Background: PWAs on iOS cannot maintain WebSocket connections in the background. The app auto-reconnects when foregrounded.
-
Native vs PWA: For the best experience with long-running sessions, consider native terminal apps (Prompt, Termius, Blink). This PWA is ideal for quick interactions.
Contributions are welcome! Please see CONTRIBUTING.md for guidelines.
The best experience for using Claude Code remotely from your smartphone. Perfect for:
- Quick code reviews while away from your desk
- Approving Claude Code's suggestions on the go
- Monitoring long-running tasks
- Coding from the couch! 🛋️
MIT