Browser use
Ghostex Browser Use lets coding agents inspect and control embedded CEF browser panes through a stdio MCP server. Agents get Chrome DevTools Protocol access without launching a second browser automation runtime.
MCPCEFDevTools
Requirements
- Ghostex must be running before the MCP server can attach to CEF.
- A browser pane does not need to exist yet — create one with ghostex browser open <url>.
- The Ghostex CLI is bundled with the macOS app and auto-linked on startup.
- Install the skill: ghostex browser install-skill (or from Settings → Integrations).
MCP configuration
Configure your agent to launch the MCP server over stdio:
[mcp_servers.ghostex-browser]
command = "ghostex"
args = ["browser", "mcp"]If the CEF remote debugging port is not one of Ghostex's default ports, pass it explicitly or set GHOSTEX_CEF_REMOTE_DEBUGGING_PORT:
args = ["browser", "mcp", "--port", "9333"]CLI commands
| Option | What it does |
|---|---|
ghostex browser mcp | Run the stdio MCP server for CEF DevTools control. Optional --port, --target, --page flags. |
ghostex browser install-skill | Install the $ghostex-browser-use skill into ~/agents/skills. |
ghostex browser open <url> | Open or reuse an embedded browser pane. Defaults to CLI cwd as project path and --reuse similar. |
ghostex browser open-pane | Alias for browser open. |
ghostex browser --help
gx browser open https://example.com --project-path "$PWD"
gx browser open https://docs.ghostex.dev --reuse exactMCP tools
| Option | What it does |
|---|---|
ghostex_list_pages | List CEF DevTools targets and current page ids. |
ghostex_select_page | Choose the target page when multiple panes are open. |
ghostex_navigate | Navigate the selected CEF page. |
ghostex_console_logs | Read console messages, Log entries, and exceptions captured after attach. |
ghostex_snapshot | Get an accessibility-like DOM snapshot with @e element refs. |
ghostex_click / ghostex_fill | Interact with @e refs or CSS selectors. |
ghostex_press_key | Send Enter, Tab, Escape, arrows, or printable keys. |
ghostex_evaluate | Run JavaScript in the selected page for inspection. |
ghostex_screenshot | Capture a PNG screenshot as base64 MCP image content. |
Recommended workflow
- Open or reuse a pane with ghostex browser open <url> when no suitable browser pane exists.
- List pages with ghostex_list_pages and select the intended pane with ghostex_select_page.
- Read ghostex_console_logs before and after interactions when debugging runtime errors.
- Take ghostex_snapshot for stable element refs, then operate with ghostex_click and ghostex_fill.
- Use ghostex_evaluate for focused inspection and ghostex_screenshot for visual evidence.
Opening panes
| Option | What it does |
|---|---|
--project-path | Scope the pane to a specific project/worktree. Defaults to the CLI process cwd. |
--project-id | Use when you already know the Ghostex project id from ghostex sessions --json. |
--reuse similar | Default. Reuse a same-origin pane in the project instead of creating a duplicate tab. |
--reuse exact | Reuse only when the exact URL matches. |
--reuse none / --new | Force a separate browser pane. |
Keep the returned browser session id and the MCP page id from ghostex_list_pages for follow-up work. Element refs from ghostex_snapshot are only valid for the current page state — re-run after navigation or major DOM changes.
Settings
Related browser settings in Ghostex:
| Option | What it does |
|---|---|
browserFeedbackTool | Agentation (default) or React Grab — launched from browser pane context menus for visual feedback. |
browserOpenMode | Always browser-pane — browser actions open in embedded CEF panes. |
autoSleepBrowserSessionsEnabled | Opt-in sleep for inactive browser panes (default idle: 30 minutes). |
hideBrowserFaviconUntilHover | Hide browser page favicons until a session row is hovered. |