PoC: Embedded Claude Code terminal in the Agentic UI

[sejas]

Related issues

• Related to the Studio Code provider-cost exploration (WPcom AI proxy cost reduction). No Linear issue yet — companion issue can be opened if the direction lands.

How AI was used in this PR

AI-assisted throughout: architecture exploration of the local server/agentic UI, implementation, and browser-based verification of every flow described below. Reviewed and directed by @sejas.

Proposed Changes

⚠️ Draft Proof of Concept — directional guidance, not merge-ready. See docs/design-docs/claude-terminal-agentic-ui.md for the full decision log and trade-offs.

Lets Studio Code users run agent work on their own Claude Pro/Max subscription instead of the WPcom AI proxy, using the only Anthropic-sanctioned path that keeps full subscription limits: the official claude CLI running interactively in a terminal (Anthropic's announced billing change moves ACP/Agent-SDK/headless usage to a separate capped credit; Zed recommends the same terminal fallback to its users).

• New per-site embedded terminal in the Agentic UI (studio ui): right-click a site → "Open Claude Code terminal". The terminal replaces the chat pane; the live site preview stays alongside.
• Studio contributes what it uniquely knows: the terminal starts in the site directory, with the wordpress-studio MCP server pre-configured (--mcp-config, user's own MCP setup untouched), and a file watcher refreshes the site preview as Claude edits the site.
• Fallback CTAs: when the WPcom assistant is unusable — monthly usage cap, per-account AI kill switch, or login required — the chat error notice offers "Continue in the Claude Code terminal". The signed-out banner (Electron/hosted surfaces) gains the same escape hatch.
• Sessions persist per site across page reloads; closing the tab keeps the CLI session alive for reconnect.

Trade-offs called out in the design doc: terminal transcript lives in Claude Code (not Studio's session store), node-pty is a native dependency (fine under studio ui; Electron packaging deferred), and the terminal is currently reachable only from the local studio ui server.

Testing Instructions

Prereqs: Claude Code CLI installed and signed in (claude), a local site in ~/Studio.

1. npm run cli:build:ui && node apps/cli/dist/cli/main.mjs ui --no-open → http://localhost:8081
2. Right-click a site in the sidebar → Open Claude Code terminal. Expect the Claude Code header with your plan (e.g. "Claude Max") and the site path as cwd.
3. Run /mcp in the terminal → wordpress-studio listed as connected.
4. Ask Claude to edit the site (or touch wp-content/test.txt yourself) → the preview panel reloads.
5. Reload the browser tab → terminal reconnects to the same CLI session.
6. Usage-cap CTA: in a chat session that ended with the monthly-limit error, expect a "Continue in the Claude Code terminal" button under the notice.

⚠️ Visual change: needs human review in light + dark mode.

Pre-merge Checklist

• Have you checked for TypeScript, React or other console errors?