← index2026-04-19 11:51 (Beirut)(backfill from DOCUMENTATION/)

CC-V4 — archived

Last updated: 2026-04-19 (Brian)
Status: shut down, archived, restorable

What it was

CC-V4 was a parallel effort to build a tmux-backed true-mirror PWA for the real claude CLI, running sidecar to V3 at cli.jonahtebaa.com (V3 stayed at cc.jonahtebaa.com/v3/). Single tmux server was the source of truth; multiple clients (PWA Chat, PWA Terminal, xfce4-terminal, SSH+attach) would all mirror the same pane.

Shipped through Phase 3: backend, wrapper, WS bridge, Caddy routing, auth gate, xfce4 window, E2E-verified through the public URL.

Why it was shut down

Jonah called it on 2026-04-19. The cli.jonahtebaa.com DNS/routing needed to be freed for the V3 PWA (now the primary web UI — see cli_pwa_deployment.md). V4's tmux-hub architecture added complexity without a payoff against V3's chat+events design.

Where it lives now

Thing	Location
Full source tree	`/opt/agent/cli-pwa-v4.backup/` (188 MB — backend, frontend, wrap, data)
Systemd unit	`/opt/agent/cli-pwa-v4.backup/systemd/cli-pwa-v4-backend.service`
Original plan	`/opt/agent/data/plans/260419_cc_v4_plan.md`
Pre-shutdown handoff	`/opt/agent/data/session_handoffs/260419_0735_cc_v4_phases_1to3_live_handoff.md`

What was torn down

Systemd service cli-pwa-v4-backend — stopped, disabled, unit moved into the archive. systemctl status cli-pwa-v4-backend returns "not found".
Tmux server at /run/cc-v4/tmux.sock — killed.
Wrapper processes (wrap.js) — killed.
Port 8112 — free (no listener).
Caddy block cli.jonahtebaa.com { ... } — removed from /opt/agent/caddy/Caddyfile (via docker exec -i agent-caddy tee) and reloaded. Subdomain now returns connection-refused.
UFW rule allow from 172.16.0.0/12 to any port 8112 — deleted.
Runtime dir /run/cc-v4/ — removed.

V3 at cc.jonahtebaa.com/v3/ was untouched throughout.

How to restore (if ever)

# 1. Move the tree back
mv /opt/agent/cli-pwa-v4.backup /opt/agent/cli-pwa-v4

# 2. Restore the systemd unit
mv /opt/agent/cli-pwa-v4/systemd/cli-pwa-v4-backend.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable --now cli-pwa-v4-backend

# 3. Re-add the Caddy block (subdomain will need to be picked — not cli., since V3 owns that now)
#    Reference block in /opt/agent/cli-pwa-v4.backup/ (grep for cli.jonahtebaa.com in the old Caddyfile backup
#    at /tmp/caddyfile.before.* if still present, otherwise reconstruct from the plan doc).

# 4. Re-add UFW rule (if caddy is in Docker and backend binds 0.0.0.0:8112)
ufw allow from 172.16.0.0/12 to any port 8112 comment 'Docker to cc-v4 backend'

Gotchas if resurrected

Backend must bind 0.0.0.0:8112 (not 127.0.0.1) so Caddy-in-Docker can reach it via host.docker.internal.
Wrapper spawns claude inside a systemd-run --scope --unit=cc-v4-tmux.scope so claude + MCP subtree don't inherit the backend's MemoryMax cgroup limit (claude + MCP peaked 2.7 GB during testing).
Idle-pause logic (Phase 4 item #1) was completed and lives in wrap/wrap.js — 30 min inactivity SIGINTs claude, emits session_paused, respawns via --resume on next input. Configurable via CC_V4_IDLE_MS env var.
/api/recent-cwds must return a bare array [], not {cwds: []} — frontend crashes on .map.