TailClaude

Claude Code from any browser. No SSH. No terminal. Just a URL.

TailClaude publishes a full Claude Code web interface to every device on your Tailscale tailnet — or the public internet via Tailscale Funnel. Powered by the iii engine.

Scan a QR code from your phone, open the link, and start coding with Claude — streaming responses, full session history, model switching, real-time cost & usage dashboards, system metrics, request traces, live activity feed, and every Claude Code control in a touch-optimized UI styled with Anthropic's brand guidelines.

Why TailClaude?

Every "doom coding" setup — SSH, mosh, tmux, Termius, Moshi — still puts you in a terminal. You're still typing on a tiny keyboard, memorizing shortcuts, and managing connections.

TailClaude removes the terminal entirely.

| | Terminal (SSH/mosh + tmux) | TailClaude | |---|---|---| | Client | Terminal app + SSH/mosh + tmux | Any browser | | Phone setup | Install app, configure keys/auth | Scan QR code | | Network switch | mosh helps, SSH drops | Browser reconnects automatically | | Interface | Terminal emulator | Web chat UI with Markdown rendering | | Streaming | Raw terminal output | Real-time SSE, token-by-token | | Session history | tmux attach (terminal only) | Browse ALL sessions (terminal + web) | | Model switching | Edit CLI flags, restart | Dropdown: Opus, Sonnet, Haiku | | Permission modes | CLI flags | One-click: default, plan, acceptEdits, bypassPermissions | | Cost tracking | None | Live tokens + per-message cost ($0.01 · 4.5K in / 892 out) | | Stop mid-response | Ctrl+C in terminal | Stop button with instant feedback | | Mobile UX | Tiny terminal, keyboard shortcuts | Touch-optimized, responsive, dark theme | | Setup time | ~15 minutes | npm install && iii -c iii-config.yaml |

Tailscale handles the secure connection. TailClaude handles everything else.

Architecture

+-----------------------------------------------------------------+
|  Browser (any device — phone, tablet, laptop)                   |
|  https://your-machine.tail-abc.ts.net                           |
+---------------------------------+-------------------------------+
                                  | HTTPS (auto-cert via Tailscale)
                                  v
+-----------------------------------------------------------------+
|  tailscale serve/funnel :443 -> http://127.0.0.1:3110           |
+---------------------------------+-------------------------------+
                                  |
                                  v
+-----------------------------------------------------------------+
|  Node.js Proxy (port 3110)                                      |
|                                                                 |
|  GET  /                  -> Chat UI (Anthropic brand, tabs)     |
|  GET  /health            -> Engine state + worker metrics        |
|  POST /chat              -> OTel-traced SSE streaming chat       |
|  POST /chat/stop         -> Kill active process + lifecycle      |
|  GET  /chat/active       -> Active streaming request IDs         |
|  GET  /chat/replay/:id   -> Replay buffered chat events          |
|  GET  /sessions          -> State-indexed sessions (sub-ms)      |
|  GET  /sessions/:id      -> Full conversation history            |
|  GET  /activity          -> SSE live activity feed               |
|  GET  /usage             -> 7-day cost & token usage stats       |
|  GET  /metrics           -> System metrics timeline + alerts     |
|  GET  /traces            -> Request traces (cost/tokens/model)   |
|  GET  /qr                -> QR code SVG                          |
|  GET  /settings          -> MCP servers list                     |
|  *                       -> Proxy to iii engine (port 3111)      |
+---------------------------------+-------------------------------+
                                  |
                                  v
+-----------------------------------------------------------------+
|  iii engine (port 3111)                                         |
|                                                                 |
|  State    -> session_index, usage_daily, traces, metrics,       |
|             alert_cooldowns, alerts, backfill_state, config      |
|  Streams  -> chat event replay buffer (LRU, 100 groups max)    |
|  PubSub   -> chat::started/completed/stopped, session::indexed, |
|             cleanup::completed, alert::*                         |
|  Cron     -> */1 metrics snapshot, */5 session re-index +       |
|             backfill, */30 cleanup, */6h data retention          |
|  OTel     -> distributed tracing on every chat request          |
|  Logger   -> structured logging with trace correlation          |
|  Event: engine::started  -> auto-publish to Tailscale + QR      |
|  Signal: SIGINT/SIGTERM  -> unpublish Tailscale + clean exit    |
+---------------------------------+-------------------------------+
                                  |
                                  v
+-----------------------------------------------------------------+
|  claude -p --output-format stream-json --verbose                |
|  (Claude Code CLI — works with Pro/Max plans)                   |
+-----------------------------------------------------------------+

How It Works

iii engine runs the state store, event bus, stream layer, and cron scheduler
TailClaude worker connects via WebSocket and registers functions, triggers, streams, and PubSub subscriptions
Node.js proxy (port 3110) serves the UI and handles all endpoints with OTel tracing
POST /chat spawns claude -p --output-format stream-json --verbose, wraps the request in an OTel span (model, cost, tokens, duration), writes events to the iii chat stream for replay, and emits lifecycle events via PubSub
PubSub subscribers react to chat events: increment daily usage stats, write request traces, push to the SSE activity feed, and update the session index
Cron jobs snapshot system metrics every minute (with overload alert detection), re-index sessions every 5 minutes (including backfilling real costs from Claude Code JSONL files), cleanup stale data every 30 minutes, and purge old usage/traces every 6 hours
Session cost backfill parses Claude Code's native JSONL session files (~/.claude/projects/) to extract real token counts, model names, and cache usage — then calculates accurate costs using Claude API pricing
On engine start, auto-publishes to your tailnet via tailscale serve and prints a terminal QR code
On shutdown (Ctrl+C), unpublishes from Tailscale, unsubscribes engine listeners, and exits cleanly

Prerequisites

iii engine installed and on your PATH
Claude Code CLI installed and authenticated
Tailscale installed (optional — works locally without it)
Node.js 20+

Quick Start

3 commands. Under 60 seconds.

git clone https://github.com/rohitg00/tailclaude.git
cd tailclaude
npm install
iii -c iii-config.yaml

That's it. Open the URL printed in your terminal (or scan the QR code from your phone).

If Tailscale is running, TailClaude auto-publishes to your tailnet with HTTPS. No config needed.

Other Ways to Run

Run worker separately (if iii engine is already running):

npm run dev

Proxy only (quick testing, no iii engine):

npx tsx -e 'import{startProxy}from"./src/proxy.ts";startProxy()'

Verify

curl http://localhost:3110/health    # Proxy health + Tailscale URL + sessions
open http://localhost:3110           # Open the chat UI
curl http://localhost:3110/sessions  # List all sessions with metadata
curl http://localhost:3110/usage     # 7-day cost & usage stats
curl http://localhost:3110/metrics   # System metrics timeline + alerts
curl http://localhost:3110/traces    # Request traces with cost/tokens/model
curl http://localhost:3110/qr        # QR code SVG

Chat UI Features

Streaming & Chat

Real-time SSE streaming — tokens appear as Claude generates them
Stop button — abort mid-response with visual feedback (kills the claude process)
Inline Markdown rendering (code blocks, bold, italic, lists)
Live token counter — input/output tokens update as Claude streams (4,521 in / 892 out)
Cost tracking — per-message cost displayed on completion ($0.0123 · 4,521 in / 892 out)
Tool use badges — appear in real-time as Claude invokes tools, even before text arrives

Session Management

Session discovery — browse ALL Claude Code sessions (terminal + web)
Conversation history — click any session to load full chat history
Session naming — double-click (or long-press on mobile) to rename
Auto-restore — reopening the browser resumes your last session
Relative timestamps — "2h ago", "3d ago" on each session
Slug names — sessions display their Claude Code slug for identification

Claude Code Controls

Model selector — Opus (default), Sonnet, Haiku
Permission modes — default, plan, acceptEdits, bypassPermissions, dontAsk
Effort levels — low, medium, high
Budget control — set max spend per message
System prompt — append instructions to every message
MCP servers — view configured MCP servers in settings

Activity Feed (Live SSE)

Real-time events — chat started, completed, stopped, session indexed, cleanup, alerts
SSE stream at GET /activity —

Tailclaude

Install / Use

README