coquibot/coqui-toolkit-browser

Browser automation toolkit for Coqui — web browsing via playwright-cli

v0.1.0 2026-02-23 14:27 UTC

Requires

• php: ^8.4
• carmelosantana/php-agents: ^0.6

Requires (Dev)

• pestphp/pest: ^3.0
• phpstan/phpstan: ^2.0

MIT

• Carmelo Santana

• toolkit
• browser
• playwright
• php-agents
• coqui
• web-automation

README

Browser automation toolkit for Coqui. Wraps playwright-cli to give agents full web browsing capabilities including navigation, page interaction, screenshots, cookie/storage management, and session control.

Requirements

• PHP 8.4+
• Node.js 18+ and npm (for playwright-cli installation)

Installation

composer require coquibot/coqui-toolkit-browser

When installed alongside Coqui, the toolkit is auto-discovered via Composer's extra.php-agents.toolkits -- no manual registration needed.

On first use, the agent will automatically install playwright-cli and Chromium into .workspace/browser/ via the browser_session setup action. No manual Node.js setup is needed.

Tools Provided

browser

Navigate web pages and interact with elements.

Parameter	Type	Required	Description
action	enum	Yes	open, click, dblclick, fill, type, press, keydown, keyup, hover, select, check, uncheck, scroll, drag, upload, back, forward, reload, eval, resize, wait, close
url	string	No	URL for open action
ref	string	No	Element ref from snapshot (for interaction actions)
value	string	No	Value for fill, type, select, eval
key	string	No	Key for press, keydown, keyup (e.g. "Enter", "Tab")
session	string	No	Override session name
headed	bool	No	Show visible browser (default: headless)
browser_engine	enum	No	chromium, firefox, webkit
persistent	bool	No	Use persistent browser profile

browser_capture

Capture page state as snapshots, screenshots, or PDFs.

Parameter	Type	Required	Description
action	enum	Yes	snapshot, screenshot, pdf
ref	string	No	Target element ref
filename	string	No	Output filename (auto-generated if omitted)
session	string	No	Override session name

browser_storage

Manage cookies, localStorage, sessionStorage, and persist browser state.

Parameter	Type	Required	Description
action	enum	Yes	cookie_get, cookie_get_all, cookie_set, cookie_delete, cookie_clear, localstorage_get, localstorage_set, localstorage_delete, localstorage_clear, sessionstorage_get, sessionstorage_set, sessionstorage_delete, sessionstorage_clear, state_save, state_load
name	string	No	Cookie/storage key name
value	string	No	Value for set operations
domain	string	No	Cookie domain
filename	string	No	State filename for save/load
session	string	No	Override session name

browser_session

Manage browser sessions and playwright-cli installation.

Parameter	Type	Required	Description
action	enum	Yes	setup, setup_deps, status, list, close, close_all, kill_all, delete_data
session	string	No	Target session for close/delete_data

Session Management

Sessions are auto-scoped to the workspace using a deterministic hash (coqui-{md5_8chars}). All four tools share the same session by default, so cookies and state persist across tool calls.

Override the session name with the session parameter on any tool to manage multiple independent browser contexts.

Agent Workflow

1. browser_session action setup -- install playwright-cli (first time only)
2. browser action open -- navigate to a URL
3. browser_capture action snapshot -- get the accessibility tree with element refs
4. browser action click/fill/type -- interact using refs from the snapshot
5. browser_capture action screenshot -- capture visual output
6. browser_session action close -- clean up when done

Standalone Usage

<?php

declare(strict_types=1);

use CoquiBot\Toolkits\Browser\BrowserToolkit;

require __DIR__ . '/vendor/autoload.php';

$toolkit = BrowserToolkit::fromEnv();

foreach ($toolkit->tools() as $tool) {
    echo $tool->name() . ': ' . $tool->description() . PHP_EOL;
}

// Navigate to a page
$browser = $toolkit->tools()[0];
$result = $browser->execute([
    'action' => 'open',
    'url' => 'https://example.com',
]);
echo $result->content;

Development

git clone https://github.com/AgentCoqui/coqui-toolkit-browser.git
cd coqui-toolkit-browser
composer install

Run tests

./vendor/bin/pest

Static analysis

./vendor/bin/phpstan analyse

License

MIT