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 — browser EventSource with auto-reconnect
• Ring buffer — last 200 events stored in memory, last 50 replayed on connect
• PubSub bridge — every iii PubSub event is bridged to the browser via SSE

Cost & Usage Dashboard

• Today's stats — cost, requests, input tokens, output tokens
• 7-day cost trend — CSS bar chart showing daily cost
• Total accumulated cost across all tracked days
• Real pricing — uses Claude API rates (Opus $15/$75, Sonnet $3/$15, Haiku $0.80/$4 per M tokens, plus cache read/write rates)
• Session backfill — parses Claude Code JSONL files for historical costs with real model and token data

System Metrics

• Gradient area charts — memory RSS, CPU, event loop lag, worker uptime
• Per-metric colors — orange (memory), blue (CPU), gray (lag), green (uptime) using Anthropic brand palette
• Min/Max/Avg stats on each metric card
• Time axis labels and grid lines
• 30-second auto-refresh
• Overload alerts — threshold-based detection for CPU >80%, memory >500MB, lag >100ms with 5-minute cooldown

Request Traces

• Full trace table — timestamp, model, duration, cost, tokens in/out, exit status
• Color-coded status — green (success), orange (error), gray (stopped)
• Summary stats — average duration, average cost, today's request count
• 30-day retention with automatic cleanup

Access & Mobile

• QR code — scan from phone to instantly access TailClaude
• Tailscale Funnel — public HTTPS access (no Tailscale app needed on phone)
• Mobile-first — hamburger menu, touch-optimized, responsive layout
• Anthropic brand design — Dark #141413, Light #faf9f5, Orange #d97757 accent, Poppins/Lora typography
• Blurred Tailscale URL — hover to reveal, keeps the URL private by default
• Connection status with auto-reconnect polling
• Auth support — set TAILCLAUDE_TOKEN env var to require bearer token (?token= query param for EventSource)

Project Structure

tailclaude/
├── iii-config.yaml              # iii engine configuration (180s timeout)
├── package.json                 # dependencies (iii-sdk ^0.3.0, qrcode)
├── tsconfig.json
└── src/
    ├── iii.ts                   # SDK init + connection state helpers
    ├── hooks.ts                 # useApi, useEvent, useCron, emit (PubSub publish)
    ├── state.ts                 # State wrapper (scope/key API via iii.trigger)
    ├── streams.ts               # Chat event stream (LRU replay buffer)
    ├── sessions.ts              # State-backed session index with filesystem scan
    ├── metrics.ts               # WorkerMetricsCollector with 5s cached snapshots
    ├── activity.ts              # SSE activity feed — ring buffer + PubSub→SSE bridge
    ├── usage.ts                 # Daily usage aggregation (cost, tokens, requests)
    ├── traces.ts                # Request traces — write/query/cleanup (30-day retention)
    ├── metrics-timeline.ts      # 1-minute metric snapshots + overload alert detection
    ├── session-costs.ts         # JSONL parser — backfill real costs from Claude Code sessions
    ├── proxy.ts                 # HTTP proxy with OTel tracing (14 endpoints)
    ├── index.ts                 # Register all functions, streams, PubSub, crons, proxy
    ├── ui.html                  # Full UI — 4 tabs, activity sidebar, Anthropic brand (~1500 lines)
    └── handlers/
        ├── health.ts            # GET /health (engine state + worker metrics)
        ├── setup.ts             # Tailscale auto-publish with terminal QR code
        ├── shutdown.ts          # Graceful shutdown (SIGINT/SIGTERM + unpublish)
        └── cleanup.ts           # Multi-scope cleanup (sessions, chats, index, streams)

Configuration

Environment Variables

iii Modules

The iii-config.yaml enables these modules:

Tailscale Integration

TailClaude supports two Tailscale modes:

Tailscale Serve (tailnet only)

Accessible only from devices on your tailnet:

tailscale serve --bg --yes --https=443 http://127.0.0.1:3110

Tailscale Funnel (public internet)

Accessible from any device — ideal for phone access without installing Tailscale:

tailscale funnel --bg --yes --https=443 http://127.0.0.1:3110

When using Funnel, set TAILCLAUDE_TOKEN to prevent unauthorized access.

Auto-publish on Engine Start

When Tailscale is available, TailClaude automatically:

1. Detects your Tailscale IP and DNS name
2. Checks for existing serve listeners (reuses if already active)
3. Publishes via tailscale serve with HTTPS on port 443
4. Verifies the proxy registered via status check (retries up to 3 times)
5. Prints a QR code to the terminal for instant mobile access
6. On shutdown, runs tailscale serve --https=443 off to unpublish

If Tailscale is not installed, it runs in local-only mode at http://127.0.0.1:3110.

API Reference

POST /chat Body

{
  "message": "Hello Claude",
  "model": "opus",
  "mode": "default",
  "effort": "high",
  "sessionId": "optional-uuid-to-resume",
  "maxBudget": 5.00,
  "systemPrompt": "You are a helpful assistant"
}

iii Integration

TailClaude deeply integrates every iii engine primitive, making it a real-world reference app for the iii SDK.

Background

The "doom coding" movement proved that coding from a phone is real — Pete Sena, Emre Isik, and Ryan Bergamini's doom-coding repo showed what's possible with SSH + tmux + Termius. Others improved the connection layer with mosh and Moshi for persistent sessions through network switches.

But every approach still required a terminal client, key management, and tiny-keyboard typing.

TailClaude asks: what if you didn't need a terminal at all? One URL, any browser, full Claude Code — with streaming, session history, model switching, and cost tracking that no terminal setup can match.

License

MIT