Browser

Overview#

Agentastic includes a built-in web browser for previewing web applications, testing APIs, and debugging frontend code without leaving the editor. The browser runs on WebKit (the same engine as Safari) and includes developer tools.

The pane's background follows your theme: blank tabs, pages still loading, and the detached browser window all paint the theme's editor background, so the browser matches the surrounding chrome instead of standing out as a system-colored rectangle.

Opening a Browser Tab#

Open a browser tab with File > New Browser Tab. New tabs start at localhost:3000 and add http:// automatically.

Detected web links opened from the Terminal normally follow Settings > General > Default Browser. Use a modifier to override their placement:

Gesture	Opens in
Click	Your configured default; the built-in browser creates a trailing split when the editor has a single pane
Option+click	The built-in browser as a tab in the source editor without creating a split
Cmd+click	Your external browser

Features#

The browser toolbar provides standard navigation, beside that we provide four debugging capabilities:

• inspect element
• console
• take screenshot
• open in safari

Developer Tools#

Design Mode#

Turn what you see in the browser directly into an agent task:

1. Click the cursor button in the toolbar to enable Design Mode
2. Hover over elements on the page — React components resolve down to the exact source file, line, and column
3. Click an element to open a small composer right there in the browser, pre-loaded with that element's context
4. Describe the change you want and submit — it's dispatched straight to your agent, with the element's tag, selector, classes, and source location attached automatically

Prefer to just grab the reference without opening the composer? Hold Option while clicking to copy the element's info to your clipboard instead — the same "component at file:line:column" format Design Mode always captured, ready to paste into any prompt.

Console#

View JavaScript console output:

• Click the </> button in the toolbar to toggle the console
• See console.log, warnings, and errors
• Errors are highlighted in red

The console captures:

• console.log() - Standard output
• console.info() - Information messages
• console.warn() - Warnings (yellow)
• console.error() - Errors (red)
• Uncaught exceptions
• Unhandled promise rejections

Screenshot#

Capture the current page:

1. Click the camera button in the toolbar
2. Screenshot is copied to your clipboard
3. Paste into Agent Home, or the terminals

Useful for:

• Sharing bugs with AI agents
• Documenting UI states
• Creating visual references

Tip: if you don't like the element in the website, take a screenshot, and then inspect the element. Provide both the screenshot and the element to the agent, then tell the agent to fix that particular element.

Open in Safari#

Click the Safari button to open the current URL in your default browser. Useful when you need:

• Full browser DevTools
• Browser extensions
• Testing in a different engine

Live Preview#

Share whatever is open in the built-in browser — including a local dev server — with anyone, over a temporary public URL. Click Share Live Preview in the toolbar and Agentastic opens a secure Cloudflare tunnel to the page and hands you a link to send; stop sharing and the tunnel closes. The tunnel helper now ships inside the app, so Live Preview works out of the box with nothing to install.

Both Design Mode and Share Live Preview appear as icon-only buttons while inactive and expand into labeled, highlighted controls once you turn them on.

Browser Options#

The toolbar's options menu collects the housekeeping commands you reach for while iterating on a page:

Action	What it does
Hard Reload	Reload the page, bypassing the cache
Clear Browsing History	Forget the pages you've visited in the built-in browser
Clear Cookies	Remove cookies set for the current site
Clear Cache	Empty the browser's cache

Browser Automation for Agents#

Agentastic exposes the built-in browser to AI coding agents via the dev browser CLI. Agents running in the terminal can programmatically control browser tabs — navigate pages, snapshot the DOM, click elements, fill forms, and read console output — all without leaving the terminal.

How It Works#

When you open a terminal in Agentastic, two environment variables are injected automatically:

Variable	Purpose
AGENTASTIC_SOCKET_PATH	Unix socket for IPC communication
AGENTASTIC_BROWSER_ID	ID of the browser tab in the current editor

The dev browser command communicates with the app over this socket using JSON-RPC. Agents like Claude Code can call these commands directly from their terminal sessions.

Quick Start#

Open a browser tab, then from the terminal:

Element References (@eN)#

When you run dev browser snapshot, the DOM tree is returned with @eN references assigned to each interactive element:

Use these refs in subsequent commands instead of CSS selectors:

Refs are stable within a snapshot but reset when you take a new snapshot.

What Agents Can Do#

Category	Examples
Navigate	navigate, back, forward, reload
Inspect	snapshot, screenshot, get title, get text, highlight
Interact	click, fill, type, press, keydown, keyup, check, select, hover
Wait	wait selector, wait text, wait url, wait load
Query	is visible, is enabled, get attr, get count, get styles
Find	find role, find text, find label, find alt, find title, find first/last/nth
Console	console list, console errors, console clear, errors list
Dialogs	dialog accept, dialog dismiss
Cookies	cookies get, cookies set, cookies clear
Storage	storage get, storage set, storage clear
State	state save, state load
Frames	frame select, frame main
Tabs	list, open, close, focus_tab, tab new/list/switch/close
Injection	addinitscript, addscript, addstyle

See the full Browser CLI Reference for all commands, or read the Browser Use Skill Guide to set up agent access.

Example: Agent Testing a Login Flow#

An AI agent can test a login page end-to-end:

Security#

The socket only accepts connections from your user (verified via peer UID). No other users on the system can access the browser automation API.

Limitations#

The built-in browser:

• Uses WebKit (Safari's engine), not Chrome
• Doesn't support browser extensions
• Has simplified DevTools (console only)
• May render differently than Chrome/Firefox

For full compatibility testing, use the "Open in Safari" button or test in multiple browsers.

Tips#

Local Development#

Keep a browser tab open to your dev server for quick previewing.

Use Design Mode#

Click an element and describe the fix instead of searching through files — the source location and component context are attached for you.

Screenshot for Context#

Capture screenshots to include in AI agent prompts for visual context.

Console for Quick Debug#

Use the console view for quick JavaScript debugging without opening Safari DevTools.

Browser + Agent Workflow#

Open a browser tab to your dev server, then tell your agent to use dev browser commands to verify its changes visually. This closes the loop between code changes and UI verification.