One mobile interface for Claude Code, Codex CLI, and Gemini CLI. Real-time sync. Cross-AI review. Push notifications.
Quick Start · Adapters · Cross-AI Review · CLI · PWA & Notifications · Architecture
Walk away from your desk while your AI is working. Get a push notification when it finishes. Approve a file edit from the couch. Send Claude's code to Gemini for a second opinion. Start a task on the train. Your phone and terminal share the exact same AI session — no duplicates, no sync issues, no matter which AI you're using.
📱 Phone (PWA) ◄── WebSocket ──► 🖥 Server ◄── tmux ──► 🤖 Claude / Codex / Gemini
▲ │ ▲
Push Notify HTTPS 💻 Terminal
(Web Push) (Tailscale)
npm install -g @kuannnn/clawtap
export CLAWTAP_PASSWORD=your-password
clawtapOpen the URL on your phone. That's it.
Mobile access? ClawTap needs HTTPS for PWA install and push notifications. The easiest way is Tailscale:
tailscale serve --bg 3456gives you a trusted HTTPS URL instantly. See PWA & Push Notifications for details.
ClawTap auto-detects which AI CLIs you have installed (claude, codex, gemini) and enables them automatically.
📦 Install from source
git clone https://github.com/kuan0808/clawtap.git
cd clawtap && npm install && npm run build && npm linkClawTap works with three AI coding assistants through a unified interface:
| Adapter | CLI | Models | Context | Permission Modes |
|---|---|---|---|---|
| Claude Code | claude |
Sonnet, Opus, Haiku, Opus 1M, Sonnet 1M | 200K–1M | Normal, Auto-edit, Plan, YOLO |
| Codex CLI | codex |
GPT-5.4, GPT-5.3 Codex, GPT-5.2 series, and more | 258K | Suggest, Full Auto, Untrusted, YOLO |
| Gemini CLI | gemini |
Auto, Gemini Pro, Gemini Flash, Flash Lite | 1M | Default, Auto Edit, Plan, YOLO |
Each adapter auto-detects at startup. Start a session from your phone's New Chat screen — tap the adapter icon to switch between available AIs, pick a model, and go. Or from the terminal:
clawtap new # Claude (default)
clawtap new --adapter codex # Codex
clawtap new --adapter gemini # GeminiThe UI adapts to each adapter — different models, permission modes, effort levels, and branding. But the workflow is identical: send a message, see the response stream in, approve or deny tool calls, switch modes.
Send any AI's response to a different AI for a second opinion — the killer feature that makes multi-adapter worth it.
How it works:
- Tap ↗ Send to on any assistant message
- Pick a target adapter (e.g., send Claude's code to Codex)
- Choose a model and optionally attach instructions ("Review for security issues")
- A review panel slides up with the child AI's conversation
- The child AI can send back its findings to the parent chat
Multi-review tabs: Run multiple reviews simultaneously. Each review gets its own tab in the floating panel — switch between them, minimize to a compact bar, or expand to see the full conversation. Each tab maintains its own independent WebSocket connection.
Send to existing review: When reviews are already active, tapping Send to shows a shortcut sheet — send directly to a running review or start a new one.
Review markers: Visual timeline markers show exactly where each review started in the parent chat, with a collapsed card to tap and view the review history. "Review ended" appears at the position in the chat where you pressed End.
See AI responses as they're being written — not after they finish. Thinking indicators update in real-time. Tool calls appear as inline cards with live status transitions. Context usage and cost stream to your status bar.
Unified overlay for all AI interactions that need your input — permissions, questions, and plan approvals. Shows the exact tool name, options, or free-text input with a 120-second countdown. Works across all three adapters. Switch permission modes mid-session with a single tap on the status bar.
Every tool call renders as an expandable card:
| Tool | What You See |
|---|---|
| Edit | Inline red/green diff preview → full-screen diff viewer |
| Write | File path + content preview with line count |
| Read / Bash / Grep | Input/output with syntax highlighting |
| Agent | Collapsible group with progress indicators |
| AskUserQuestion | Question + options (selected/unselected) or quoted free-text answer |
Send follow-up messages while the AI is still responding. They appear as "Queued" with Edit/Cancel and auto-send when the AI finishes. Paste images from clipboard with thumbnail preview.
When your AI creates tasks (via TaskCreate/TaskUpdate), a floating progress ring appears in the bottom-right corner showing completion (e.g., 2/5). Tap it to expand a bottom sheet with full task details. Tasks are grouped by rounds — a new round starts when all previous tasks complete. The ring auto-fades 3 seconds after all tasks finish.
Tap the mic icon to dictate coding instructions. Supports two backends:
- Web Speech API (default) — real-time interim transcription, currently configured for Traditional Chinese (
zh-TW) - OpenAI Whisper — higher accuracy, requires
OPENAI_API_KEY(see Configuration)
Type ultrathink or megathink and watch the rainbow shimmer animation. Drafts auto-save to localStorage. Images can be attached from gallery or clipboard.
Browse projects by directory. Filter by adapter (Claude / Codex / Gemini tabs). See session previews with first message, timestamps, and active indicators. The Active tab shows running sessions across all projects with real-time refresh, client count, and notification badges.
clawtap # Start server, show URLs
clawtap new [--adapter codex|gemini] # New session
clawtap --continue [--adapter gemini] # Resume most recent session
clawtap --resume <session-id> # Resume specific session
clawtap -a [--adapter codex] # Active sessions (current project)
clawtap -A [--adapter gemini] # Active sessions (all projects)
clawtap hooks install [--adapter claude] # Install hooks (all or one adapter)
clawtap hooks uninstall [--adapter gemini] # Remove hooks
clawtap cert # Generate HTTPS certificate
clawtap stop # Graceful shutdown
clawtap --version # Show version
clawtap --help # Show helpThe --adapter flag works with every command. Session lists show colored [Claude]/[Codex]/[Gemini] labels with first-prompt previews.
Auto-starts the server on first use. Sessions are instantly visible on mobile.
1. Enable HTTPS (required for push):
# Option A: Tailscale (recommended — zero cert management)
tailscale serve --bg 3456
# Option B: Self-signed certificate
clawtap cert2. Install PWA: Open the URL in Safari → Share → Add to Home Screen.
3. Enable notifications: On first login in standalone mode, ClawTap automatically prompts for notification permission. You can also toggle notifications manually in Settings.
| Event | When | Notification |
|---|---|---|
| AI finishes | Only if you're NOT viewing that session | "Turn complete in project-name" |
| Permission needed | Only if you're NOT viewing that session | Tool name + project |
| Question asked | Only if you're NOT viewing that session | "Waiting for answer" |
The app icon badge shows how many sessions have unread notifications. Entering a session clears its count.
| Variable | Default | Description |
|---|---|---|
CLAWTAP_PASSWORD |
(required) | Login password |
PORT |
3456 |
Server port |
OPENAI_API_KEY |
(optional) | Enables Whisper voice transcription (higher accuracy than Web Speech API) |
VAPID_EMAIL |
noreply@clawtap.local |
Contact email for Web Push VAPID identification |
HTTPS is enabled automatically when ~/.clawtap/cert.pem and ~/.clawtap/key.pem exist. Otherwise the server runs on HTTP. Tailscale Serve is the easiest path to HTTPS.
Hooks auto-configure on startup and clean up on clawtap stop. If you have existing hooks (e.g., custom statusLine), ClawTap wraps them — both coexist.
Each adapter feeds the UI through three independent, non-blocking channels:
| Channel | Latency | Role |
|---|---|---|
| Hooks | ~1ms | Tool events, permissions, session lifecycle — fire-and-forget, never blocks the AI |
| File Watcher | ~2s | Message transcripts (JSONL for Claude/Codex, JSON for Gemini) — single source of truth |
| Pane Monitor | 500ms | Streaming text preview, thinking detection — ephemeral UX signals via tmux |
IAdapter (EventEmitter)
├── ClaudeAdapter ← HTTP hooks, JSONL watcher, pane monitor
├── CodexAdapter ← Command hooks, JSONL watcher, pane monitor
└── GeminiAdapter ← Shell bridge hooks, JSON watcher, pane monitor
Each adapter is self-contained: hook configuration, session file discovery, transcript parsing, tmux lifecycle, permission management. Adding a new AI CLI means implementing one class — the server, WebSocket protocol, and frontend work unchanged.
AI CLI (Claude/Codex/Gemini)
│
├── Hooks → POST /api/hooks/:adapter/:event → SessionManager → WebSocket → Phone
├── Session Files → Watcher → new-messages event → WebSocket → Phone
└── tmux pane → PaneMonitor → text-delta/thinking → WebSocket → Phone
Phone
└── Send message → WebSocket → SessionManager → tmux sendKeys → AI CLI
SQLite with WAL mode. Stores review history, push subscriptions, rate limiting, saved instructions, and session stats. Session messages live in the AI CLI's own files — ClawTap reads them, never writes.
| Problem | Solution |
|---|---|
| No response after sending | tmux list-windows -t clawtap — check if the AI process is alive |
clawtap not found |
npm install -g @kuannnn/clawtap |
| Stale sessions | tmux kill-session -t clawtap |
| Port in use | lsof -i :3456 then kill <PID> |
| Hooks not cleaned after crash | clawtap hooks uninstall or clawtap stop |
| Push notifications not working | Ensure HTTPS + PWA installed from home screen |
| Adapter not showing | Check that the CLI is installed: which claude, which codex, which gemini |
| Gemini hooks failing | Verify timeout is in milliseconds (5000, not 5) |
MIT