CODEMUXManual

Browser

Embedded browser pane with screenshot-based rendering, agent automation, and viewport sync.

Browser

Codemux includes an embedded browser pane for viewing web apps, running tests, and letting AI agents interact with pages programmatically.

How It Works

The browser uses screenshot-based rendering with a 1-second refresh cycle. A Chromium instance runs in the background, captures screenshots, and streams them to the pane via WebSocket. User clicks are mapped from display coordinates to the actual viewport.

Stealth Mode

The browser launches with anti-detection flags to avoid triggering bot protection on sites like Cloudflare:

  • Removes navigator.webdriver detection
  • Spoofs user-agent to match the installed Chrome version
  • Disables automation-related Blink features and infobars
  • Disables background throttling for consistent behavior

Browser Toolbar

The toolbar at the top of every browser pane includes:

  • URL bar — Type a URL and press Enter to navigate. Bare domains auto-prefix with https://.
  • Back / Forward — Standard navigation history
  • Refresh — Reload the current page
  • Home — Reset to about:blank
  • External link — Open the current URL in your system browser

Creating a Browser Pane

  • Click the + dropdown in the tab bar and select "Browser"
  • Or open the command palette (Ctrl+K) and choose Open Browser
  • Or use the Shell + Browser workspace preset

Manual Interaction

Even though the pane is screenshot-driven, it behaves like a real browser when you use it by hand:

  • Drag to select text — press and drag across the page; selections that finish outside the pane still complete.
  • Hover effects — :hover styles and tooltips react as you move the cursor.
  • Double / triple-click — select a word or a whole paragraph.
  • Right / middle-click — web-app context menus and middle-click actions work (the host context menu stays out of the way).
  • Live cursor — the cursor mirrors the remote page (pointer over links, I-beam over text, resize cursors).
  • Clipboard bridge — Ctrl/Cmd+C and +X copy/cut the page selection to your system clipboard, and Ctrl/Cmd+V pastes system-clipboard text into the focused field. The headless browser's own clipboard is otherwise invisible to the OS, so this bridge is what makes copy/paste feel native.

Agent Automation

AI agents running in Codemux terminals can control the browser programmatically. See Browser Agent Commands for the full reference.

codemux browser open http://localhost:3000
codemux browser snapshot          # Get accessibility tree
codemux browser click "#submit"   # Click an element
codemux browser fill "#email" "test@example.com"
codemux browser screenshot        # Capture as base64 PNG
codemux browser console-logs      # Get console output

Background Browser (Agent Chat Beta)

With Agent Chat Beta on for a real (non-OpenFlow) workspace, an agent that opens a browser doesn't split your chat into a browser pane. The browser runs in the background so the conversation keeps full width, and Codemux surfaces it instead as:

  • An inline chip in the transcript ("Browser opened in background") with a LIVE badge and the current URL while the agent is navigating.
  • A matching indicator in the workspace context bar.

Click either to open a floating peek overlay that streams the live browser without resizing the chat, with an Open as pane button to promote it to the full split-pane view whenever you want it front and center. With Beta off (or on an OpenFlow workspace), an agent-opened browser splits into a pane exactly as before.

Viewport Sync

When the browser pane resizes, the viewport dimensions sync automatically. The rendered page adapts to the pane size.

Viewport Presets

You can also resize the viewport to a specific preset for responsive testing — mobile, tablet, desktop, desktop-large, or a custom WxH value. This is a real CDP-driven viewport resize, so CSS media queries fire and screenshots capture at the simulated dimensions.

codemux browser viewport mobile
codemux browser viewport tablet
codemux browser viewport 375x812
codemux browser viewport reset
codemux browser viewport-presets   # list available presets

See Browser Viewport Presets for the full reference.

Hybrid Input System

Browser automation uses a three-tier input architecture. Agents choose the appropriate tier based on the target:

Tier 1: Selector-based (fastest)

Standard CSS selector interaction via CDP. Best for regular web apps.

  • browser_click — Click element by CSS selector
  • browser_fill — Fill input by CSS selector

Tier 2: Coordinate-based CDP (vision-capable)

Pixel-coordinate interaction via Chrome DevTools Protocol. Works on iframes, shadow DOM, canvas, and protected form fields.

  • browser_click_at — Click at (x, y) coordinates
  • browser_type_at — Click at coordinates then type text
  • browser_scroll_at — Scroll at coordinates
  • browser_key_press — Send keyboard events
  • browser_drag — Drag from one point to another

Mouse movements use Bezier curve interpolation with randomized control points for human-like motion.

Tier 3: OS-level input (stealth)

Kernel-level input events via ydotool that are indistinguishable from real human interaction. Bypasses anti-bot detection (Cloudflare Turnstile, etc.).

  • browser_click_os — OS-level click at coordinates
  • browser_type_os — OS-level keyboard typing

Requires ydotool + ydotoold daemon, headed browser mode, and Hyprland window manager for window geometry.

Limitations

  • Screenshot-driven rendering (not a native embedded webview)
  • Console logs are captured but not a full live stream
  • OS-level input (Tier 3) requires ydotool and headed mode
  • Tier 3 input requires Hyprland for window geometry detection

On this page

BrowserHow It WorksStealth ModeBrowser ToolbarCreating a Browser PaneManual InteractionAgent AutomationBackground Browser (Agent Chat Beta)Viewport SyncViewport PresetsHybrid Input SystemTier 1: Selector-based (fastest)Tier 2: Coordinate-based CDP (vision-capable)Tier 3: OS-level input (stealth)Limitations