openclaude-web

A local web mirror for openclaude sessions. Runs a small server on your machine; opens the TUI live in any browser on your LAN. Inspired by claude.ai/code's /remote-control flow, only your TUI never leaves your network.

┌──────────────── Browser (LAN device) ────────────────┐
│  React SPA — chat thread, tool cards, todo panel,    │
│  permission prompts, mode picker, mascot              │
└─────────────────────────┬────────────────────────────┘
                          │  WebSocket
┌─────────────────────────▼────────────────────────────┐
│  openclaude-web (Fastify + ws)                        │
│  Relays events between an openclaude TUI publisher    │
│  and any subscribed browser tab — strict mirror only. │
└──────────────────────────────────────────────────────┘

What it does

• Mirrors an active openclaude TUI session in any browser on the LAN.
• Two-way control. Type from the browser; the TUI replies. Hit Stop in either; both interrupt.
• Permission prompts in the browser. When the TUI asks for permission (Bash, file write, etc.), the prompt pops up in both places. Answer in either; both dismiss.
• Mode picker to flip Ask / Accept edits / Plan / Auto / Bypass without leaving the browser.
• Live todo panel that mirrors the TUI's task list (TaskCreate / TaskUpdate / TaskList) as a clean checklist above the composer.
• Follow-mode scroll with a "jump to latest" button — like a chat client.
• PATH-mode attachments for non-Anthropic backends — uploads land on disk and the TUI sees a path, bypassing per-message image caps.

Install

npm install -g openclaude-web

This auto-patches your local @gitlawb/openclaude bundle so the TUI's existing /remote-control plumbing redirects to your local server. The patch is idempotent and version-marked; future installs upgrade in place. A backup is kept at cli.mjs.ocw-bak next to the bundle.

Works on Linux, macOS, Windows, and Termux. On Termux the postinstall step rewrites the bin shebang to the Termux node path automatically.

Use

openclaude-web                 # start in background, exits to your prompt
openclaude-web status          # show pid, URL, uptime
openclaude-web logs            # last 200 lines of server log
openclaude-web logs -f         # follow live
openclaude-web stop            # stop the daemon
openclaude-web restart         # stop + start
openclaude-web --foreground    # run attached (debugging)

After openclaude-web you'll see something like:

openclaude-web started — http://localhost:3009 (pid 12104)
  status    openclaude-web status
  logs      openclaude-web logs
  stop      openclaude-web stop

State (pid file, log file, metadata) lives in ~/.openclaude-web/ — cross-platform; survives shell exits.

In another terminal:

openclaude --resume <some-session>
> /web-control

The TUI prints a clickable URL like http://127.0.0.1:3009/?session=…. Open it in any browser on your LAN — you get a live two-way mirror of that session. Visiting http://localhost:3009/ directly (without ?session=) shows a usage page; the mirror only opens through /web-control.

That's the whole flow: install → run server → /web-control → open URL. No standalone chat, no cloud, no auth, no config.

Options

openclaude-web                     # default: 0.0.0.0:3009
openclaude-web --port 8080
openclaude-web --host 127.0.0.1    # bind only loopback
openclaude-web --help

| Env var | Default | What | |---|---|---| | PORT | 3009 | Server listen port | | HOST | 0.0.0.0 | Server bind host | | OPENCLAUDE_BRIDGE_URL | ws://127.0.0.1:3009 | WS URL the TUI's /web-control connects to | | OPENCLAUDE_NO_BRIDGE | unset | Set to 1 to opt a TUI run out of bridging | | OPENCLAUDE_WEB_UPLOADS_DIR | ~/openclaude-web-uploads (or /sdcard/Download/openclaude-web-uploads on Termux) | Where browser-uploaded attachments land for PATH-mode |

How the bridge works

The TUI's useReplBridge React hook (originally for cloud /remote-control) opens a WebSocket. Our patch repoints that WebSocket at ws://127.0.0.1:3009 instead of wss://api.anthropic.com, and the local server runs a relay that fans events between the TUI publisher and any subscribed browser tabs. Wire envelopes for permission requests, mode changes, interrupts, and the bridge dialog all flow through the same WebSocket. Every patch is idempotent and the patcher keeps a versioned marker in the bundle so it auto-upgrades cleanly across openclaude-web releases.

openclaude-web patch-openclaude            # manually re-patch
openclaude-web patch-openclaude --check    # report patch status (exit 0 if patched)
openclaude-web patch-openclaude --unpatch  # restore the original bundle from backup

Requirements

• Node.js ≥ 20
• openclaude installed (any session in ~/.openclaude/projects/)
• The TUI authenticated once interactively

License

MIT