Wezbridge

The install is 6 steps: WezTerm → AI CLI → clone → register MCP on Claude → register MCP on Codex → launch daemon.

1. Install WezTerm

Download from wezfurlong.org/wezterm. The mux server is built in. Verify with wezterm cli list — if it prints a header row, the mux is reachable.

2. Install your AI CLI(s)

You need at least one. wezbridge works with both side-by-side.

# Claude Code
npm install -g @anthropic-ai/claude-code

# Codex CLI (optional, for cross-LLM swarms)
npm install -g @openai/codex

You'll also need Node.js 20+.

3. Clone

git clone https://github.com/wolverin0/wezbridge.git
cd wezbridge

No npm install needed — wezbridge has zero npm dependencies (uses only Node built-ins).

4. Register wezbridge MCP on Claude Code

claude mcp add wezbridge --scope user -- node "$(pwd)/src/mcp-server.cjs"

--scope user makes it available in every Claude Code session you ever start. Verify with claude mcp list.

5. Register wezbridge MCP on Codex CLI

Codex uses TOML at ~/.codex/config.toml (create the file if it doesn't exist):

[mcp_servers.wezbridge]
command = "node"
args = ["/absolute/path/to/wezbridge/src/mcp-server.cjs"]

Restart any running Codex sessions.

6. Crash-prevention env var (Windows only)

WezTerm's internal 10054 mux-disconnect error category accumulates to MB-sized log files under sustained MCP load. Silence it:

[Environment]::SetEnvironmentVariable('WEZTERM_LOG','wezterm_mux_server_impl::local=off','User')

Restart WezTerm so the new instance inherits it. macOS / Linux can skip.

7. Launch the daemon

npm run dashboard

This is a headless backend, not a UI. It serves /api/panes, /api/events (SSE), /api/grades, etc. The core MCP tools do NOT need it — they drive the WezTerm CLI directly. Only auto_handoff and the background services (SSE, telegram-streamer, session-snapshot crash-restore, grades) require it. It binds 127.0.0.1 only; opening http://127.0.0.1:4200 in a browser returns 404 — that's intentional. Verify it's up with curl http://127.0.0.1:4200/api/panes, or call the bridge_health MCP tool from any session. To expose it on a LAN set WEZBRIDGE_BIND=0.0.0.0 — a WEZBRIDGE_API_TOKEN then becomes mandatory or the daemon refuses to start.

8. (Optional) Telegram + OmniClaude pattern

If you want phone control, follow docs/SETUP-omniclaude-telegram.md.

Quick pointer:

• Bot token + group ID at ~/.claude/channels/telegram/.env
• Per-project topic mapping at ~/.omniclaude/telegram-topics.json
• Streamer (outbound): npm run start-streamer
• OmniClaude pane (inbound): claude --channels plugin:telegram@claude-plugins-official

9. (Optional) v3.2 safety modules

All opt-in via env vars; default behavior unchanged.

node scripts/install-hooks.cjs                   # pre-push hook
export WEZBRIDGE_GUARD_SHIMS=1                   # PATH-based command guard
export PATH="$(pwd)/bin/guard-shims:$PATH"
export WEZBRIDGE_MM_INBOX=1                      # MemoryMaster Dreams inbox
export WEZBRIDGE_GRADER_BACKEND=claude           # outcome-grader backend

Bypass-once override env vars: WEZBRIDGE_GUARD_OVERRIDE, WEZBRIDGE_SAFETY_OVERRIDE, WEZBRIDGE_PREPUSH_OVERRIDE. See docs/USAGE-guard.md.

Network exposure: the daemon binds 127.0.0.1 by default. Set WEZBRIDGE_BIND=0.0.0.0 (or a specific interface) to reach it from another machine — a WEZBRIDGE_API_TOKEN is then required or startup aborts, since the pane-control API can type into (and spawn) sessions.

10. Session snapshot + crash recovery (default ON)

Captures every AI pane's launch state (cwd + cmdline + flags) on a 60s timer. After a WezTerm crash, recover with zero clicks — see step 11 for the wezterm-native UX.

Default ON since v3.4.1. Dashboard daemon arms the watcher automatically. Opt OUT with WEZBRIDGE_SESSION_SNAPSHOT=0.

npm run dashboard          # snapshot watcher arms automatically
npm run install-autostart  # one-time: dashboard auto-launches on user login (Windows)

# Manual restore from CLI (fallback if you skip step 11):
npm run restore-session

Only claude.exe and codex.exe panes are captured. Snapshots land at vault/_wezbridge/session-snapshot.jsonl.

11. (Recommended) Wezterm Lua plugin — zero-click recovery + launcher

Add the wezbridge.wezterm Lua plugin to your wezterm config for automatic crash recovery (no commands, no clicks) plus a fuzzy launcher menu for AI sessions with preset flag combos.

After a crash: just reopen wezterm. AI panes come back automatically if the snapshot is < 30 min old. Done.

Drop this into your ~/.wezterm.lua (C:\Users\<you>\.wezterm.lua on Windows):

local wezterm = require 'wezterm'
local config = wezterm.config_builder()

local wezbridge_dir = '/abs/path/to/your/wezbridge/clone'
package.path = package.path .. ';' .. wezbridge_dir .. '/wezterm/?.lua'

config.leader = { key = 'a', mods = 'CTRL', timeout_milliseconds = 2000 }
local wezbridge = require 'wezbridge'
wezbridge.apply(config, {
  wezbridge_dir = wezbridge_dir,
  auto_restore = true,                              -- silent auto-restore on cold boot
  restore_keybind = { mods = 'LEADER', key = 'r' }, -- LEADER+R: pick a snapshot manually
  launcher_keybind = { mods = 'LEADER', key = 'l' },-- LEADER+L: launcher menu (preset AI launches)
})

return config

See wezterm/example-wezterm.lua in this repo for a fuller example.