Skip to main content

TubeMail for Claude Code

Claude Code workers on a wire.

TubeMail lets one Claude Code session drive another. Start a worker in any directory, and any other Claude Code session (or MCP-aware agent) can send it messages, receive replies, approve permission prompts remotely, restart it, and watch what it's doing — all over HTTP/SSE + WebSocket.

What this is

  • A hub service (FastAPI + FastMCP) that brokers events between workers and exposes a web UI on the same port.
  • A channel (Claude Code plugin) that relays events between a worker's claude session and the hub.
  • A process manager (tubemail.manager) that runs claude in a pty, handles restarts, idle detection, and harness commands (/compact, /clear, /exit, /mcp reconnects).
  • A bash wrapper (claude-tm) that sources env vars and keeps the manager alive across restarts.
  • A web UI (React + Vite) served alongside /mcp on the same port, with a live worker roster, a permission inbox, integrated browser terminals via WebSocket pty bridge, saved-message templates, and optional per-worker session recording.

What this is not

  • Not an orchestrator. TubeMail ships transport plus an operator surface; it does NOT implement orchestration policy (failure routing, retry, scheduling, load balancing). Build that on top.
  • Not a replacement for Claude Code's native tools. Workers are vanilla claude processes.

Architecture

                                                  ┌──────────────────┐
       browser ◀──── HTTPS + WSS pty bridge ─────▶│  TubeMail hub    │
                                                  │  FastMCP :8001   │
                                                  │  + web UI at /   │
       Orchestrator ◀── HTTP/SSE (MCP /mcp/) ────▶│                  │
       (any MCP client)                           └────────┬─────────┘
                                                           │
                                                           │  HTTP/SSE
                                                           ▼
                                              ┌─────────────────────────────┐
                                              │  Worker session             │
                                              │  claude-tm (bash wrapper)   │
                                              │  └─ tubemail.manager (pty)  │
                                              │     ├─ tubemail-channel     │
                                              │     └─ claude --name ...    │
                                              └─────────────────────────────┘

One container, one port, three protocols: HTTP/HTTPS for the JSON API and MCP, SSE for forwarder event streams, WebSocket for the browser terminal pty bridge.

Install

Two packages — one for each side.

Side Install Binary / tools
Worker pip install tubemail-channel claude-tm (Python launcher → tubemail.manager → claude)
Hub pip install tubemail MCP server at :8001; tm_* tools; web UI

For local development:

git clone git@github.com:Disciplin-run-org/tubemail.git
cd tubemail
pip install -e channel/ --no-build-isolation
pip install -e .[dev] --no-build-isolation
npm --prefix frontend ci
npm --prefix frontend run build

Dev mode — live reload

The hub container runs uvicorn --reload with the host src/ bind-mounted read-only over the image's editable-install path. Edits to src/tubemail_hub/ on the host auto-restart the server inside the container — no rebuild needed for Python changes.

docker compose up --build tubemail   # first run — builds the image
# from here on:
# edit src/tubemail_hub/…   → uvicorn reloads automatically
# edit frontend/src/…  →  npm --prefix frontend run build to ship the bundle
docker compose restart tubemail      # only needed for entrypoint / compose changes

VERSION and frontend/dist are mounted the same way, so a bump or a rebuild on the host is live without a container rebuild.

Quickstart

  1. Start the hub:

    echo 'TUBEMAIL_SECRET=change-me' > .env
    docker compose up -d tubemail
    
  2. Open the web UI at http://localhost:8001. On localhost the bearer is auto-loaded; remote browsers paste the TUBEMAIL_SECRET value into the auth gate. The Workers tab shows the (initially empty) roster.

  3. Start a worker in any project directory:

    pip install tubemail-channel
    cd /path/to/your/project && claude-tm
    

    pip install tubemail-channel puts claude-tm on your PATH. Export TUBEMAIL_SECRET in your shell, or drop a .env containing it in the project directory (or at ~/.config/tubemail/.env) — claude-tm auto-loads it. The worker registers as <dirname>-tm and appears in the roster. Use --role <name> to run multiple workers per project.

    On the first run in a project, claude-tm auto-creates a minimal ./.mcp.json containing a tubemail-channel entry so claude's --dangerously-load-development-channels flag can resolve the stdio channel. No secret is written to that file — it's a one-line {"command": "tubemail"} entry; TUBEMAIL_SECRET is inherited from claude-tm's env at spawn time. Set TM_SKIP_MCP_BOOTSTRAP=1 to manage .mcp.json yourself.

  4. From an orchestrator session (with the tubemail MCP server added to .mcp.json):

    tm_list_workers()
    tm_send(worker="your-project-tm", message="what's in this repo?")
    tm_wait_for_activity(worker="your-project-tm", since=<event_id>)
    tm_receive(worker="your-project-tm", since=<event_id>)
    

A step-by-step walkthrough lives in TUTORIAL.md.

Web UI

TubeMail Workers tab — live roster of connected sessions

The Workers tab. Color-coded status badges, manager indicator, context-%, recording toggle, integrated terminals — one view of every session.

Served on the same port as the MCP server.

  • Workers tab — live roster of every connected session, grouped by project. State badges (idle / busy · 47s / waiting_permission / offline / exited), manager-up indicator, version stamp, context-% column, recording toggle, sortable columns. Click a row to open the integrated terminal pane.
  • Permissions tab — every pending tool-approval prompt across every worker, in one inbox. Keyboard allow/deny, group-by-worker, bulk allow-by-tool-name (one-shot).
  • Saved Messages tab — named templates that can be sent to any worker by the operator (UI) or the orchestrator (MCP). Run logs are persisted on the hub.
  • Settings tab — recording defaults (global on/off, max file size, files kept per worker), session bearer management.
  • Integrated terminal pane — full xterm.js with a WebSocket pty bridge. Shift+Enter inserts a hard newline that Claude reads as "modifier held, do not submit." Ctrl+C copies a selection if one exists, otherwise SIGINT. Ctrl+V pastes. Ctrl+= / Ctrl+- / Ctrl+0 zoom (per-worker, persisted in localStorage). Pop-out windows tile multiple workers across the desktop.

Recording

Optional per-worker session recording, off by default. When enabled, the hub tees the worker's pty output to two parallel files:

  • <data>/recordings/<worker>/<ts>.cast — asciinema v2 format. Replay with asciinema play <file>.
  • <data>/recordings/<worker>/<ts>.frames.jsonl — one ANSI-stripped text frame per pty chunk; what tm_get_recording returns. Optimized for grep and time slicing.

Files rotate when the active .cast exceeds the configured size limit; the oldest are GC'd so total per-worker bytes stays under max_bytes_per_file * keep_files.

Toggle from the Workers tab (per-worker Rec column) or via MCP:

tm_recording_toggle(worker="iris-qa-tm", enabled=True)
tm_recording_status(worker="iris-qa-tm")
tm_get_recording(worker="iris-qa-tm", grep="permission", limit=50)

Global defaults live in the Settings tab and persist across hub restarts under <data>/hub-config.json.

Tool surface (hub MCP)

Tool What
State + flow
tm_list_workers Who is connected (color-coded table, project-grouped)
tm_status idle / busy / waiting_permission for one worker. Trailing-inbound older than 10 min decays to idle.
tm_send Deliver a message to a worker (or harness command to its manager)
tm_receive Read a worker's event timeline
tm_wait_for_activity Block until the worker produces an event
tm_my_inbox Worker-facing: what messages arrived while I was offline
tm_interrupt Pause a worker
tm_clear_and_send Atomic: /clear then send, avoids race on permission prompt
Permissions
tm_pending_permissions List tool-approval prompts across workers
tm_respond_permission Allow / deny a pending permission
Process control
tm_restart Clean restart via /exit + --continue
tm_stop Kill a worker
tm_purge_worker Remove a worker's registry entry
tm_keystroke Send raw keystrokes to a worker's pty
tm_screenshot Read recent stdout from a worker
tm_health CPU / memory / uptime — is the worker actually working?
tm_update_manager Re-exec the manager process to pick up new channel code
tm_reconnect_mcp Drive the worker's /mcp UI to reconnect a failed server
Recording
tm_recording_toggle Per-worker recording on/off
tm_recording_status Files on disk, active file, size
tm_get_recording Read frames filtered by time range and regex
Saved messages / flows
tm_save_flow / tm_list_flows / tm_delete_flow CRUD for named templates
tm_run_flow Send a saved flow to a worker, returns a run_id
tm_get_run_log / tm_finish_run Track flow runs
Meta
get_instructions Re-read the server's usage notes
refresh_tools Pick up new tools after a hub rebuild

Environment

Var Required Purpose
TUBEMAIL_SECRET yes Shared bearer secret between hub, channel, and browser
TUBEMAIL_HUB_URL no (default http://localhost:8001) Where channels connect
TM_WORKER_NAME no Override the auto-derived worker name
TUBEMAIL_LOG no (default WARNING) Channel log level
TUBEMAIL_LOG_FILE no Path to channel log file
TUBEMAIL_DATA_DIR no (default /data/tubemail) Hub state + recordings root
TUBEMAIL_DISABLE_DEV_BOOTSTRAP no If 1, the web UI never auto-loads the bearer over loopback
TUBEMAIL_WORKER_PURGE_MAX_AGE_S no (default 3600) Stale-worker purge threshold

Security

  • Bearer auth on every hub endpoint (TUBEMAIL_SECRET). Constant-time compare via hmac.compare_digest — no timing side-channel on the secret.
  • Single-use, 30s WebSocket tickets for the pty bridge. Browsers can't set custom headers on new WebSocket(), so the client POSTs a bearer-authed request to /api/pty-ticket, gets a single-use ticket, and opens wss:/ws/pty/<worker>?ticket=<t>. The ticket is consumed on use and expires in 30s.
  • Worker-name validation (^[A-Za-z0-9][A-Za-z0-9 _.-]{0,63}$) on every {worker} path parameter and in the engine, so a crafted name cannot escape the state directory. Files in the workers directory whose stem does not match the pattern are ignored on startup.
  • HTTPS auto-detect — drop server.crt + server.key into the data volume and the hub serves TLS. Without them it falls back to plain HTTP for localhost development.
  • Generate a strong TUBEMAIL_SECRET:
    python -c 'import secrets; print(secrets.token_urlsafe(32))'
    
    scripts/heal.py does this for you if .env is missing.

Findings from the most recent security review are kept at jjstack/security-review.md.

Planning and design docs

The jjstack/ directory holds design artifacts from planning sessions (office-hours, CEO review, engineering review, DX review, design review, investigations). They are checked into the repo so the decisions that shaped the code are traceable.

The current as-built design doc is jjstack/jesper-main-design-20260425-092030.md; its 2026-04-23 predecessor is preserved as superseded for history. The four review docs (CEO, eng, DX, design) live in jjstack/ceo-plans/.

License

MIT — see LICENSE.

Metadata

Release files for tubemail 1.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tubemail 1.2.0
File Size Uploaded Provenance Actions
tubemail-1.2.0.tar.gz 99.2 kB With provenance Details for tubemail-1.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tubemail 1.2.0
File Interpreter ABI Platform Actions
tubemail-1.2.0-py3-none-any.whl Python 3 none any Details for tubemail-1.2.0-py3-none-any.whl

Total release size: 177.8 kB

Release files / tubemail-1.2.0.tar.gz

Download URL tubemail-1.2.0.tar.gz
Size 99.2 kB
Tags Source
SHA-256 checksum
How to use checksums
d67dacf89dfa0a30645b3b2f85582231c72f4be8c1d3cd1acd2d467e34a3e2c9
BLAKE2b-256 checksum
How to use checksums
2da91048d0158f359f75d840eab41858e0cdb254c250f416a26b78e8dbb7a5ee
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 18, 2026.

Transparency log

Release files / tubemail-1.2.0-py3-none-any.whl

Download URL tubemail-1.2.0-py3-none-any.whl
Size 78.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
d209ad1f2fb03cb3149cfb4314f50ce15a7f365c50cc6803751fd13cac04adf9
BLAKE2b-256 checksum
How to use checksums
01e7adebfabf137841d2eca7cc2d6a542096d26afd630b465a60309596693ce1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.13.12

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 18, 2026.

Transparency log

Security for tubemail 1.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tubemail-1.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on May 18, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

1.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page