Embedded browser
Ghostex embeds Chromium (not WebKit) as first-class workspace panes. Browser tabs live inside project groups with address navigation, profiles, DevTools, find-in-page, and agent-facing CLI control.
What it is
Every browser action in Ghostex opens an embedded browser pane inside the native AppKit workspace. Chrome Canary attachment and external Safari routing were removed; browserOpenMode always normalizes to browser-pane.
Browser sessions are macOS-local WKWebView/CEF panes even when gxserver owns terminal presentation. Sidebar cards show page titles, favicons, and URLs that persist across app restarts.
How it works
Browser panes render through bundled Chromium/CEF with native navigation chrome:
- Address bar navigation, back/forward, and reload from the pane title bar.
- DevTools toggle for inspecting the active CEF page.
- Profile picker backed by NativeBrowserProfileStore (default profile plus user-created profiles).
- Feedback tool injection (Agentation or React Grab) from pane menus and toolbar.
- Favicon and committed URL metadata synced back to sidebar session cards.
- Cookies and browser storage persist across restarts for CEF browser panes.
Browser panes participate in the same splitter layout as Ghostty terminals and T3 Code. Drag headers to reorder, split, merge, pop out, and sleep inactive tabs.
Opening browser panes
- Cmd+N (default): open a browser tab as the next tab in the focused workspace split.
- Project group header controls: create a scoped browser pane in the clicked project.
- Command palette / custom Actions with actionType browser.
- CLI: ghostex browser open <url> or gx browser open <url>.
- Middle-click or target=_blank links in CEF panes can open sibling browser tabs in the workspace.
Remote browser creation is not available in the current version — attempting it shows a toast: Browser panes are local-only in this version.
Profiles and storage
Each browser pane can use a browser profile with isolated storage. Ghostex remembers the last-used profile and applies it to new panes unless the pane is a managed T3 surface.
- Built-in Default profile ships with the app.
- Create additional named profiles from the profile picker in the pane chrome.
- Profile selection focuses the pane before showing the picker.
- Chromium CEF panes persist cookies and local storage per profile across restarts.
In-pane tools
| Option | What it does |
|---|---|
DevTools | Toggle Chromium DevTools for the focused browser pane. Also available to agents through Browser Use MCP. |
Find in page | Cmd+F opens Chromium page search. Cmd+G / Cmd+Shift+G move to next/previous match in the focused CEF pane only. |
Zoom | Cmd+Plus, Cmd+Minus, and Cmd+0 adjust CEF page zoom when a browser pane is focused. |
Feedback tool | Toolbar/menu action launches Agentation (default) or React Grab based on browserFeedbackTool. |
React Grab / Agentation | Agentation opens directly into feedback mode from the browser toolbar when selected. |
Options and settings
Settings → Browser:
| Option | What it does |
|---|---|
browserFeedbackTool | Label: "Feedback Tool". Agentation (default) or React Grab — launched from browser pane context menus. |
Related settings elsewhere:
| Option | What it does |
|---|---|
browserOpenMode | Always browser-pane (not exposed in UI; legacy values normalize here). |
autoSleepBrowserSessionsEnabled | Auto Sleep → Sleep inactive browser panes (opt-in, default off). Idle threshold default 30 minutes. |
autoSleepBrowserIdleMinutes | 5, 10, 15, 30, 60, 120, or 300 minutes when browser auto-sleep is enabled. |
hideBrowserFaviconUntilHover | Session Cards → hide browser page favicons until row hover. |
openBrowserPane hotkey | Settings → Hotkeys. Default Cmd+N (retired default Ctrl+Shift+B). |
Keyboard shortcuts
| Option | What it does |
|---|---|
Cmd+N | Open Browser Pane — new browser tab beside the focused tab (default). |
Cmd+F | Open find-in-page bar in the focused Chromium browser pane. |
Cmd+G / Cmd+Shift+G | Next / previous find match in the focused CEF pane. |
Alt+3 | Switch workarea to GitHub/Browser view (default hotkey name: GitHub). |
Ctrl+Shift+R | Reload the focused pane (browser, terminal, or T3). |
CLI commands
| Option | What it does |
|---|---|
ghostex browser open [url] | Open or reuse an embedded pane. Defaults to CLI cwd as --project-path and --reuse similar. |
ghostex browser open-pane | Alias for browser open. |
ghostex browser mcp | Stdio MCP server for agent DevTools control (see Browser use docs). |
ghostex browser install-skill | Install the $ghostex-browser-use agent skill. |
gx browser open https://example.com --project-path "$PWD"
gx browser open https://app.local --reuse exact
gx browser open https://docs.example.com --reuse noneProject scoping flags:
- --project-path — scope to a worktree path (defaults to CLI cwd).
- --project-id — use a known Ghostex project id from ghostex sessions --json.
- --group-id — place the browser in a specific project group.
- --active-project — intentionally target the currently focused Ghostex project.
Project and session integration
Browser panes are project-scoped workspace sessions:
- Cards live inside their project groups, not a separate Browsers sidebar section.
- Agent-created browser panes reuse same-origin or exact tabs when possible to avoid duplicates.
- CLI browser open defaults to --reuse similar: same project + same origin focuses and navigates instead of spawning another tab.
- Titlebar Resources → Browser Tabs counts only Ghostex embedded browser helpers.
- Bluetooth permission text is declared for websites requesting passkeys, security keys, or Bluetooth devices in CEF panes.
Tips
- Use separate browser profiles when you need isolated logins for staging vs production.
- Switch Feedback Tool to React Grab only when your workflow explicitly depends on it — Agentation is the structured default.
- Enable browser auto-sleep if you keep many tabs open but want idle panes to retire after 30+ minutes.
- For agent automation, pair embedded panes with ghostex browser mcp instead of external Playwright installs.
- When debugging layout, enable Debugging Mode — CEF layout and focus diagnostics help trace geometry drift during sidebar resize.