Multi-Agent Coordination

When multiple Claude agents share Claudezilla’s 12-tab pool, coordination tools manage tab space allocation. These tools implement a mercy system that prevents deadlocks when the pool is full.

How It Works

1. An agent tries to open a tab but gets a POOL_FULL error.
2. The blocked agent calls firefox_request_tab_space to queue a request.
3. When another agent closes a tab or calls firefox_grant_tab_space, a 30-second slot reservation is created for the waiting agent.
4. The waiting agent calls firefox_get_slot_requests to check for a reservation.
5. If reserved, the agent calls firefox_create_window to claim the slot (bypasses the pool limit during the reservation window).

firefox_request_tab_space

Queue a request for tab space when blocked by POOL_FULL. When another agent closes a tab or grants space, you receive a 30-second slot reservation.

Parameters

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

No other parameters.

Example

// After receiving POOL_FULL error
const result = await firefox_request_tab_space();
// Request is queued. Check back with firefox_get_slot_requests.

---

firefox_grant_tab_space

Voluntarily release your oldest tab to help a waiting agent. Creates a 30-second reservation for the waiting agent so they can claim the freed slot.

Parameters

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

No other parameters.

Example

// Voluntarily free a slot for a waiting agent
const result = await firefox_grant_tab_space();

Notes

• Only works if you have more than 2 tabs and there are pending slot requests.
• Closes your oldest tab to free the slot.
• The freed slot is reserved for the waiting agent for 30 seconds. Other agents cannot claim it during that window.

---

firefox_get_slot_requests

Check pending requests, active reservations, and your tab count. Shows whether you have a reserved slot and how long until it expires.

Parameters

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

No other parameters.

Example

const result = await firefox_get_slot_requests();
// Returns:
// {
//   pendingRequests: 1,
//   activeReservations: 1,
//   youHaveReservation: true,
//   reservationExpiresInMs: 24500,
//   yourTabCount: 3
// }

// If you have a reservation, claim it immediately:
if (result.youHaveReservation) {
  await firefox_create_window({ url: "https://example.com" });
}

Notes

• Reservations have a 30-second TTL (configurable via SLOT_RESERVATION_TTL_MS).
• Expired reservations are automatically cleaned up.
• When youHaveReservation is true, call firefox_create_window immediately to claim the slot before it expires.

---

Coordination Flow Example

A complete multi-agent coordination scenario:

// Agent A: Pool is full, request space
const window = await firefox_create_window({ url: "https://example.com" });
// Error: POOL_FULL

// Agent A: Queue a request
await firefox_request_tab_space();

// Agent B: Sees the request and grants space
await firefox_grant_tab_space();
// Agent B's oldest tab is closed, reservation created for Agent A

// Agent A: Check for reservation
const status = await firefox_get_slot_requests();
// { youHaveReservation: true, reservationExpiresInMs: 29800 }

// Agent A: Claim the reserved slot
await firefox_create_window({ url: "https://example.com" });
// Success — bypasses POOL_FULL during reservation window

Related

• Agents can only evict their own tabs when the pool is full. There is no silent eviction of other agents’ tabs.
• Session cleanup happens automatically when a Claude session ends (via goodbye on SIGINT/SIGTERM).
• For hard crashes, orphaned tab cleanup runs every 60 seconds with a 2-minute timeout threshold.