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.

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

1. iii engine runs the state store, event bus, stream layer, and cron scheduler
2. TailClaude worker connects via WebSocket and registers functions, triggers, streams, and PubSub subscriptions
3. Node.js proxy (port 3110) serves the UI and handles all endpoints with OTel tracing
4. 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
5. PubSub subscribers react to chat events: increment daily usage stats, write request traces, push to the SSE activity feed, and update the session index
6. 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
7. 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
8. On engine start, auto-publishes to your tailnet via tailscale serve and prints a terminal QR code
9. 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 —