Browser Control

Tools for managing the Claudezilla browser window and tabs. All tabs live in a shared pool (max 12) across Claude agents, with tab ownership enforced per agent.

firefox_create_window

Open a URL in the shared Claudezilla browser. Creates a new tab in the shared 12-tab pool. When the limit is reached, returns a POOL_FULL error. Each tab tracks its creator for ownership enforcement.

Parameters

Parameter	Type	Default	Description
url	string	about:blank	URL to open in a new tab
private	boolean	(inherits)	Request private (incognito) or non-private window. Only takes effect when creating a new window. Omit to use the existing window’s mode.
timeout	number	150000	Request timeout in ms (5000-300000)

Example

// Open a webpage in the shared window
const result = await firefox_create_window({ url: "https://example.com" });
// Returns: {
//   windowId, tabId, ownerId, tabCount, maxTabs,
//   isPrivate, privateFallback, modeWarning, isNewWindow
// }

// Explicitly request a non-private window (useful for sites needing login)
await firefox_create_window({ url: "https://x.com", private: false });

Notes

• Returns POOL_FULL if 12 tabs are already open. Use the mercy system to request space.
• You own every tab you create. Only you can close or navigate your tabs.
• Auto-fallback on private mode failure — If private: true is requested but Firefox’s incognito permission isn’t granted, the call automatically falls back to a non-private window instead of hard-failing. The response then carries privateFallback: true and a human-readable modeWarning so the agent can detect the change. Check privateWindowsAvailable in the firefox_activate response if you need to know capability upfront.
• If the existing shared window’s mode conflicts with an explicit private request, the call returns a structured MODE_MISMATCH error instead of silently producing the wrong mode.

---

firefox_navigate

Navigate an existing tab to a new URL. Ownership is enforced when a tabId is provided.

Parameters

Parameter	Type	Default	Description
url	string	required	The URL to navigate to
tabId	number	active tab	Target tab ID (ownership enforced)
timeout	number	150000	Request timeout in ms (5000-300000)

Example

// Navigate a specific tab
await firefox_navigate({ url: "https://example.com/page2", tabId: 42 });

---

firefox_get_tabs

List all tabs in the Claudezilla pool with URLs, titles, tab IDs, and owner IDs.

Parameters

Parameter	Type	Default	Description
timeout	number	150000	Request timeout in ms (5000-300000)

Example

const tabs = await firefox_get_tabs();
// Returns array: [{ tabId, url, title, ownerId }, ...]

---

firefox_close_tab

Close a specific tab by ID. You can only close tabs you own.

Parameters

Parameter	Type	Default	Description
tabId	number	required	Tab ID to close (must be your tab)
timeout	number	150000	Request timeout in ms (5000-300000)

Example

await firefox_close_tab({ tabId: 42 });

Notes

• Returns an OWNERSHIP error if you try to close another agent’s tab.
• Use firefox_get_tabs to check ownership before closing.

---

firefox_close_window

Close the entire Claudezilla window and all tabs.

Parameters

Parameter	Type	Default	Description
timeout	number	150000	Request timeout in ms (5000-300000)

Caution

This closes tabs for all agents sharing the window. Prefer firefox_close_tab for individual tab cleanup.

---

firefox_resize_window

Resize and/or reposition the browser window.

Parameters

Parameter	Type	Default	Description
windowId	number	current window	Window ID to resize
width	number	—	New window width in pixels
height	number	—	New window height in pixels
left	number	—	Window X position from left edge
top	number	—	Window Y position from top edge
timeout	number	150000	Request timeout in ms (5000-300000)

Example

// Resize to 1280x800 and position at top-left
await firefox_resize_window({ width: 1280, height: 800, left: 0, top: 0 });

---

firefox_set_viewport

Set the browser viewport to a device preset for responsive testing, or specify custom dimensions.

Parameters

Parameter	Type	Default	Description
windowId	number	current window	Target window ID
device	string	—	Device preset (see below)
width	number	—	Custom viewport width (use instead of device)
height	number	—	Custom viewport height (use instead of device)
timeout	number	150000	Request timeout in ms (5000-300000)

Device presets

iphone-se, iphone-14, iphone-14-pro-max, pixel-7, galaxy-s23, ipad-mini, ipad-pro-11, ipad-pro-12, laptop, desktop

Example

// Test mobile layout
await firefox_set_viewport({ device: "iphone-14" });

// Custom dimensions
await firefox_set_viewport({ width: 768, height: 1024 });