Claude Workbench

A desktop app that gives Claude Code a visual development environment. Terminal on the left, real browser on the right. Claude can control both sides programmatically.

cd ~/my-project
workbench

The window opens. Claude Code starts in the terminal. The browser pane waits. You tell Claude what to do.

"Get this project running and show me the app."

Claude reads your project, installs dependencies, starts the dev server (you see the tab appear), navigates the browser to localhost, takes a screenshot to verify, and reports back. You watch it happen.

How It Works

+---------------------------------+--------------------------------------+
|                                 |                                      |
|  PRIMARY TERMINAL               |  BROWSER PANE                        |
|  (Claude Code session)          |                                      |
|                                 |  +----------------------------------+|
|  Talk to Claude here.           |  |  < > R   http://localhost:5173   ||
|  It runs your project,          |  +----------------------------------+|
|  fixes bugs, inspects           |  |                                  ||
|  the browser — all from         |  |     Your app renders here        ||
|  this terminal.                 |  |     (real Chromium)              ||
|                                 |  |                                  ||
+---------------------------------+  |                                  ||
| > dev (5173)  > tests  > db    |  |                                  ||
+---------------------------------+  +----------------------------------+|
|  $ npm run dev                  |                                      |
|  > ready in 423ms               |                                      |
+---------------------------------+--------------------------------------+

Claude has 11 MCP tools to control the environment:

Terminal tools — spawn visible sub-terminal tabs for dev servers, test runners, databases:

• terminal_create / terminal_read / terminal_write / terminal_kill / terminal_list

Browser tools — navigate, inspect, screenshot the browser pane:

• browser_navigate / browser_snapshot / browser_screenshot
• browser_console / browser_network / browser_evaluate

Install

Requires Node.js 18+ and Claude Code.

npm install -g claude-workbench

This installs Electron and builds the native terminal module. It takes a minute.

Usage

# Open workbench in the current directory
workbench

# Open workbench in a specific project
workbench --cwd ~/projects/my-app

# Hint a port for Claude to use
workbench --port 3000

# Custom Chrome DevTools Protocol port (default: 9222)
workbench --cdp-port 9333

What Claude Sees

When Claude runs inside the workbench, it gets a system prompt explaining the available tools and a recommended workflow:

1. Use terminal_create to start dev servers (tabs appear in the UI)
2. Use terminal_read to check when services are ready
3. Use browser_navigate to open the app in the browser pane
4. Use browser_screenshot or browser_snapshot to verify the page
5. Use browser_console and browser_network to debug issues

Claude prefers terminal_create over background Bash for long-running processes because the user can see and interact with the tabs.

Keyboard Shortcuts

| Shortcut | Action | |----------|--------| | Cmd/Ctrl + 1 | Focus primary terminal | | Cmd/Ctrl + 2 | Focus sub-terminal area | | Cmd/Ctrl + 3 | Focus browser URL bar | | Cmd/Ctrl + Shift + [ | Previous sub-terminal tab | | Cmd/Ctrl + Shift + ] | Next sub-terminal tab | | Cmd/Ctrl + R | Reload browser pane | | Cmd/Ctrl + Shift + I | Open DevTools for browser pane | | Cmd/Ctrl + W | Close active sub-terminal tab | | Cmd/Ctrl + \ | Toggle browser pane (full-width terminal) |

Architecture

The app is a single Electron window with three layers:

• Main process — manages PTY terminals, BrowserView, CDP debugger bridge, MCP IPC server
• Renderer — xterm.js terminals, split pane layout, browser toolbar (plain HTML/CSS/JS, no framework)
• MCP server — standalone Node.js process that bridges Claude Code (stdio) to Electron (Unix socket)

Claude Code <--stdio--> mcp-server.js <--Unix socket--> Electron main process
                                                          |           |
                                                      PtyManager  BrowserView
                                                          |           |
                                                       xterm.js    Chromium

See claude-workbench-architecture.md for the full 950-line specification.

Development

git clone https://github.com/nicobailon/claude-workbench.git
cd claude-workbench
npm install
npm start

If you get native module errors:

npx electron-rebuild -w node-pty

Building Distributables

npm run build:mac     # .dmg
npm run build:linux   # .AppImage + .deb
npm run build:win     # .exe (NSIS)

Requirements

• Node.js 18+
• Claude Code CLI installed and authenticated
• macOS, Linux, or Windows

License

MIT