Control Claude Code CLI from your phone with a mobile-friendly web interface.
A lightweight DIY alternative to Claude's official Dispatch feature — runs entirely on your local machine with no external dependencies.
[Phone Browser/PWA] ←WebSocket→ [Node.js Server on Mac/PC] ←spawn→ [claude -p --stream-json]
- Real-time streaming — see tokens appear as Claude thinks
- Session management — multiple conversations with full context, rename, directory picker
- Model switching — change between Opus / Sonnet / Haiku mid-session
- Slash commands — autocomplete popup for
/command(skills, tools) - Image attachment — send photos for Claude to analyze
- Built-in terminal — run shell commands directly from your phone
- Tool status — see what Claude is doing (Reading file, Running command, etc.)
- Web search — Claude automatically searches the web when needed
- Project context — CLAUDE.md, memory, skills loaded per working directory
- Mobile-first PWA — add to home screen for app-like experience
- Token auth — secure access with auto-generated token
- Remote access — use from anywhere via Tailscale
- Slack bot — use Claude Code from Slack DMs or @mentions (optional)
- Auto-start — runs as background service on macOS / Windows
- Claude Code CLI installed and authenticated
- Node.js 18+
- Tailscale (free) — for remote access outside your local network
git clone https://github.com/nangman98/claude-dispatch.git
cd claude-dispatch
bash setup.shgit clone https://github.com/nangman98/claude-dispatch.git
cd claude-dispatch
setup.batRun as Administrator for auto-start registration.
That's it. The setup script will:
- Install dependencies
- Register a background service (macOS LaunchAgent / Windows Task Scheduler)
- Auto-start the server (and restart on crash)
- Print the URL to open on your phone
The server auto-starts on login — no manual steps after setup.
To access from outside your local network:
- Mac: Install Tailscale and sign in
- Phone: Install Tailscale from App Store or Google Play — sign in with the same account
- Use the Tailscale URL printed by
setup.shinstead of the local one
| Access | URL to open |
|---|---|
| Same Wi-Fi | http://<local-ip>:3456?token=<token> |
| Remote (Tailscale) | http://<tailscale-ip>:3456?token=<token> |
The auth token is saved in your phone's browser automatically after the first visit.
For an app-like experience without the browser address bar:
- iPhone (Safari): Tap Share (□↑) → Add to Home Screen
- Android (Chrome): Tap Menu (⋮) → Add to Home Screen
Use Claude Code from Slack — DMs or @mentions in channels.
- Create a Slack App at api.slack.com/apps
- Enable Socket Mode and get an App-Level Token (
xapp-...) - Add Bot Token Scopes:
chat:write,reactions:write,channels:history,im:history,app_mention:read - Subscribe to events:
message.im,app_mention - Install to workspace and copy Bot Token (
xoxb-...) - Create
.envin the project directory:SLACK_BOT_TOKEN=xoxb-your-token SLACK_APP_TOKEN=xapp-your-token - Restart the server
The bot will:
- Process DMs automatically
- Respond to @mentions in channels
- Show ⏳ while thinking, ✅ when done
- Maintain per-thread conversation sessions
macOS:
# Stop
launchctl unload ~/Library/LaunchAgents/com.claude-dispatch.plist
# Restart
launchctl unload ~/Library/LaunchAgents/com.claude-dispatch.plist && launchctl load ~/Library/LaunchAgents/com.claude-dispatch.plist
# Logs
tail -f ~/claude-dispatch/dispatch.logWindows (run as Administrator):
# Stop
schtasks /end /tn "ClaudeDispatch"
# Remove auto-start
schtasks /delete /tn "ClaudeDispatch" /f
# Logs
type dispatch.log- Tap + New in the top bar to create a chat session
- Type a message and tap Send (or press Enter)
- Claude's response streams in real-time, token by token
- Switch sessions: Use the dropdown in the top bar
- Delete a session: Select it, then tap Del
- Sessions persist across reconnections (backed by Claude Code's native session storage)
The dot in the top-left corner shows connection status:
| Color | Meaning |
|---|---|
| Red | Disconnected — will auto-reconnect |
| Green | Connected and ready |
| Blue (pulsing) | Claude is thinking |
- Shift+Enter for multi-line messages
- Abort: if Claude is taking too long, delete the session and create a new one
- The server must be running on your Mac/PC for the app to work
- Keep your computer awake (disable sleep) for reliable access
Phone (PWA) Mac (server.js) Claude Code CLI
│ │ │
├── WebSocket connect ────────►│ │
├── { type: "prompt" } ──────►│── spawn claude -p ────────────►│
│ │◄── stream-json (token) ────────┤
│◄── { type: "token" } ───────┤ │
│◄── { type: "token" } ───────┤◄── stream-json (token) ────────┤
│◄── { type: "complete" } ────┤◄── result ─────────────────────┤
│ │ │
- The Node.js server wraps Claude Code CLI (
claude -p) - Your phone connects via WebSocket for real-time streaming
- Claude Code's native session persistence (
--session-id/--resume) maintains conversation history - Streaming JSON output is parsed and forwarded token-by-token to the browser
| Environment Variable | Default | Description |
|---|---|---|
PORT |
3456 |
Server port |
- Auth token is generated on first run and stored in
~/.claude-dispatch-token - All HTTP and WebSocket connections require the token
- Server binds to
0.0.0.0(accessible on all interfaces) - Use Tailscale for encrypted remote access — no ports exposed to the public internet
- Claude CLI runs with your user permissions
| Problem | Solution |
|---|---|
| Red dot (disconnected) | Check if server is running (npm start) |
| Can't connect remotely | Ensure Tailscale is active on both devices |
| "Unauthorized" error | Token mismatch — revisit the full URL from the terminal output |
| Session not responding | Delete the session and create a new one |
| Server won't start | Check if port 3456 is in use: lsof -i :3456 |
MIT