Your AI coding sessions, in your pocket.

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)

🚀 Quick Start

npm install -g @kuannnn/clawtap

export CLAWTAP_PASSWORD=your-password
clawtap

Open 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 3456 gives 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.

git clone https://github.com/kuan0808/clawtap.git
cd clawtap && npm install && npm run build && npm link

🤖 Multi-Adapter Support

ClawTap 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      # Gemini

The 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.

🔀 Cross-AI Review

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:

1. Tap ↗ Send to on any assistant message
2. Pick a target adapter (e.g., send Claude's code to Codex)
3. Choose a model and optionally attach instructions ("Review for security issues")
4. A review panel slides up with the child AI's conversation
5. 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.

✨ Features

Live Streaming

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.

Interactive Prompts

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.

Rich Tool Visualization

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 |

Queue & Continue

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.

Task Progress

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.

Voice Input

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)

Smart Input

Type ultrathink or megathink and watch the rainbow shimmer animation. Drafts auto-save to localStorage. Images can be attached from gallery or clipboard.

Session Management

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.

💻 CLI

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 help

The --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.

🔔 PWA & Push Notifications

Setup

1. Enable HTTPS (required for push):

# Option A: Tailscale (recommended — zero cert management)
tailscale serve --bg 3456

# Option B: Self-signed certificate
clawtap cert

2. 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.

Smart Notifications

| 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.

⚙️ Configuration

| 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 | [email protected] | 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.

🏗 Architecture

Three-Channel Event System

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 |

Adapter Plugin Architecture

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.

Data Flow

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

Storage

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.

🔧 Troubleshooting

| 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) |

📄 License

MIT