ClawTap  ClawTap

### 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. [![npm version](https://img.shields.io/npm/v/@kuannnn/clawtap.svg)](https://www.npmjs.com/package/@kuannnn/clawtap) [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE) [![Node.js](https://img.shields.io/badge/Node.js-18+-339933.svg)](https://nodejs.org/) --- **[Quick Start](#-quick-start)** · **[Adapters](#-multi-adapter-support)** · **[Cross-AI Review](#-cross-ai-review)** · **[CLI](#-cli)** · **[PWA & Notifications](#-pwa--push-notifications)** · **[Architecture](#-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 ```bash 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](https://tailscale.com): `tailscale serve --bg 3456` gives you a trusted HTTPS URL instantly. See [PWA & Push Notifications](#-pwa--push-notifications) for details. ClawTap auto-detects which AI CLIs you have installed (`claude`, `codex`, `gemini`) and enables them automatically.
📦 Install from source
```bash 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: ```bash 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](#-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 ```bash clawtap # Start server, show URLs clawtap new [--adapter codex|gemini] # New session clawtap --continue [--adapter gemini] # Resume most recent session clawtap --resume # 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): ```bash # 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` | `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.
## 🏗 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 ` | | 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