# AgentChrome
**Give your AI agent browser superpowers.**
AgentChrome is a native CLI tool for browser automation via the Chrome DevTools Protocol, designed for AI coding agents such as Codex. Every command outputs structured JSON, uses accessibility-tree UIDs for element targeting, and returns typed exit codes for programmatic error handling. No Node.js, no Python, no MCP server — just a fast Rust binary your agent calls from the shell.
## Codex Integration
**1. Install AgentChrome** (see [Installation](#installation) for more options)
```sh
cargo install agentchrome
```
**2. Add AgentChrome guidance to Codex**
```sh
agentchrome skill install --tool codex
```
This writes the AgentChrome Codex skill to `$CODEX_HOME/skills/agentchrome/SKILL.md`, or to `~/.codex/skills/agentchrome/SKILL.md` when `CODEX_HOME` is not set. AgentChrome is self-documenting through `agentchrome --help`, `agentchrome capabilities`, and `agentchrome examples`, so Codex can discover the current CLI surface directly from the installed binary.
For project-local guidance, you can also add the AGENTS template:
```sh
curl -fsSL https://raw.githubusercontent.com/Nunley-Media-Group/AgentChrome/main/examples/AGENTS.md.example > AGENTS.md
```
**3. Ask Codex to use the browser**
> "Check if the login form at localhost:3000 works correctly"
Behind the scenes, Codex will run commands like:
```sh
agentchrome connect --launch --headless
agentchrome navigate http://localhost:3000/login --wait-until networkidle
agentchrome page snapshot
agentchrome form fill-many '[{"uid": "s2", "value": "test@example.com"}, {"uid": "s3", "value": "password123"}]'
agentchrome interact click s4 --include-snapshot
agentchrome console read --errors-only
```
See the full [Codex Integration Guide](docs/codex.md) for workflows, efficiency tips, and error handling patterns.
For agentic tools supported by AgentChrome's built-in skill installer, use `agentchrome skill install` to write the tool-specific guidance file and `agentchrome skill update` after upgrading AgentChrome. Supported targets include Claude Code, Windsurf, Aider, Continue.dev, GitHub Copilot, Cursor, Gemini CLI, and Codex; Codex users can target it explicitly with `agentchrome skill install --tool codex`.
## Features
### Built for AI Agents
- **JSON output by default** — every command returns structured, parseable output
- **Accessibility tree snapshots with UIDs** — `page snapshot` assigns stable UIDs (e.g., `s1`, `s5`) to interactive elements for reliable targeting
- **Structured exit codes** — 0 (success), 1 (general error), 2 (connection error), 3 (target error), 4 (timeout), 5 (protocol error) for programmatic error handling
- **Self-documenting CLI** — `agentchrome capabilities` outputs a machine-readable JSON manifest of every command, flag, and argument
- **`--include-snapshot` on interactions** — get the updated accessibility tree in the same response as a click or form fill, cutting round-trips in half
<details>
<summary><strong>Full Browser Control</strong></summary>
- **Tab management** — list, create, close, and activate browser tabs
- **URL navigation** — navigate to URLs, go back/forward, reload with wait strategies
- **Page inspection** — accessibility trees, text extraction, element search
- **Screenshots** — full-page, viewport, element, or region captures
- **JavaScript execution** — run scripts in page context, return results as JSON
- **User interactions** — click, hover, drag, type, press keys, scroll, coordinate-based drag and decomposed mouse actions
- **Form filling** — fill inputs, select options, upload files, batch fill with `fill-many`, ARIA combobox support
- **Iframe/frame targeting** — list frames, target specific iframes with `--frame` on all commands, cross-origin OOPIF support
- **Media control** — list, play, pause, seek audio/video elements with CSS selector or bulk targeting
- **Page analysis** — structure discovery with iframe detection, framework identification, overlay/blocker detection, and hit testing for click debugging
- **DOM event introspection** — inspect event listeners on any element via CDP
- **Cookie management** — list, set, delete, and clear browser cookies
- **Network monitoring** — list, inspect, and follow requests in real time
- **Console capture** — read and follow console messages with type filtering
- **Device emulation** — mobile devices, network/CPU throttling, geolocation, color scheme
- **Performance tracing** — record traces, analyze insights, measure Core Web Vitals
- **Lighthouse auditing** — run audits returning structured category scores with filtering
- **Dialog handling** — accept, dismiss, or respond to alert/confirm/prompt dialogs
</details>
### Comparison
How AgentChrome stacks up for giving AI agents browser access:
| **AI agent integration** | CLI — works with any agent that runs shell commands | Requires JavaScript wrapper | MCP protocol (specific client required) |
| **Runtime** | No Node.js — native Rust binary | Node.js | Node.js |
| **Install** | Single binary, `cargo install` | `npm install` | `npx` |
| **Interface** | CLI / shell scripts | JavaScript API | MCP protocol |
| **Startup time** | < 50ms | ~500ms+ | Varies |
| **Binary size** | < 10 MB | ~100 MB+ (with deps) | Varies |
| **Shell pipelines** | First-class (`| jq`, `| grep`) | Requires wrapper scripts | Not designed for CLI |
## Architecture
```
Agent → CLI (clap) → Command Dispatch → CDP Client (WebSocket) → Chrome (DevTools Protocol)
```
AgentChrome communicates with Chrome using the [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/) (CDP) over WebSocket. Run `agentchrome connect --launch --headless` to start a session — subsequent commands reuse the connection automatically. Native Rust binary, <50ms startup, <10MB on disk.
## Installation
### Cargo install
```sh
cargo install agentchrome
```
### Pre-built binaries
Download the latest release for your platform from [GitHub Releases](https://github.com/Nunley-Media-Group/AgentChrome/releases).
<details>
<summary>Quick install via curl (macOS / Linux)</summary>
```sh
# macOS (Apple Silicon)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-aarch64-apple-darwin.tar.gz \
| tar xz && mv agentchrome-*/agentchrome /usr/local/bin/
# macOS (Intel)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-x86_64-apple-darwin.tar.gz \
| tar xz && mv agentchrome-*/agentchrome /usr/local/bin/
# Linux (x86_64)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-x86_64-unknown-linux-gnu.tar.gz \
| tar xz && mv agentchrome-*/agentchrome /usr/local/bin/
# Linux (ARM64)
curl -fsSL https://github.com/Nunley-Media-Group/AgentChrome/releases/latest/download/agentchrome-aarch64-unknown-linux-gnu.tar.gz \
| tar xz && mv agentchrome-*/agentchrome /usr/local/bin/
```
</details>
<details>
<summary>Build from source</summary>
```sh
git clone https://github.com/Nunley-Media-Group/AgentChrome.git
cd AgentChrome
cargo build --release
# Binary is at target/release/agentchrome
```
</details>
### Supported platforms
| macOS (Apple Silicon) | `aarch64-apple-darwin` | `.tar.gz` |
| macOS (Intel) | `x86_64-apple-darwin` | `.tar.gz` |
| Linux (x86_64) | `x86_64-unknown-linux-gnu` | `.tar.gz` |
| Linux (ARM64) | `aarch64-unknown-linux-gnu` | `.tar.gz` |
| Windows (x86_64) | `x86_64-pc-windows-msvc` | `.zip` |
## CLI Quick Start
For shell scripting and manual use:
**1. Install AgentChrome** (see [Installation](#installation) above)
**2. Start Chrome with remote debugging enabled:**
```sh
# macOS
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222
# Linux
google-chrome --remote-debugging-port=9222
# Or launch headless Chrome directly via AgentChrome:
agentchrome connect --launch --headless
```
**3. Connect to Chrome:**
```sh
agentchrome connect
```
**4. Navigate to a URL:**
```sh
agentchrome navigate https://example.com
```
**5. Inspect the page:**
```sh
agentchrome page snapshot
```
## Command Reference
| `connect` | Connect to or launch a Chrome instance |
| `tabs` | Tab management (list, create, close, activate) |
| `navigate` | URL navigation and history |
| `page` | Page inspection (screenshot, text, accessibility tree, find, analyze, hittest, frames, workers) |
| `dom` | DOM inspection, manipulation, and event listener introspection |
| `js` | JavaScript execution in page context |
| `console` | Console message reading and monitoring |
| `network` | Network request monitoring and interception |
| `interact` | Mouse, keyboard, scroll, and coordinate-based drag interactions |
| `form` | Form input, submission, and ARIA combobox support |
| `emulate` | Device and network emulation |
| `perf` | Performance tracing and metrics |
| `cookie` | Browser cookie management (list, set, delete, clear) |
| `dialog` | Browser dialog handling (alert, confirm, prompt, beforeunload) |
| `media` | Media element control (list, play, pause, seek) |
| `audit` | Run audits against the current page (Lighthouse) |
| `diagnose` | Pre-automation challenge scan (iframes, overlays, media gates, frameworks, patterns) |
| `skill` | Agentic tool skill installation and management |
| `config` | Configuration file management (show, init, path) |
| `completions` | Generate shell completion scripts |
| `examples` | Show usage examples for commands |
| `capabilities` | Output a machine-readable manifest of all CLI capabilities |
| `man` | Display man pages for AgentChrome commands |
Run `agentchrome <command> --help` for detailed usage, `agentchrome examples <command>` for practical examples, or `agentchrome capabilities` for the full machine-readable command manifest.
## Session resilience
Long-running automation sessions survive transient WebSocket drops and idle timeouts without manual intervention.
**Auto-reconnect.** When a command's stored `ws_url` is no longer reachable but Chrome is still running on the recorded port, AgentChrome transparently re-discovers the current browser-level WebSocket URL, rewrites the session file (preserving `pid`, `port`, and `active_tab_id`), and retries the command within the same invocation. Diagnostics are stderr-only; stdout stays pure JSON.
**Keep-alive.** While a command holds the CDP session open longer than the keep-alive interval (default `30000` ms), AgentChrome sends a WebSocket Ping frame to prevent idle-timeout disconnects. A missing Pong within 10 s triggers the existing reconnect path.
**Configuration precedence:** `--keepalive-interval <ms>` flag > `AGENTCHROME_KEEPALIVE_INTERVAL` env var > `[keepalive] interval_ms` in `config.toml` > built-in default (30000 ms).
```sh
# Run a long command with a 60-second keep-alive
agentchrome --keepalive-interval 60000 console follow
# Disable keep-alive (--no-keepalive or interval 0)
agentchrome --no-keepalive page snapshot --json
```
**Scripting against connection-loss errors.** When auto-reconnect cannot recover the session, the CLI emits a structured JSON error on stderr with a `kind` discriminator and a `recoverable` boolean:
| Chrome process is gone | `"chrome_terminated"` | `false` | `agentchrome connect --launch` |
| Probe failed but Chrome may still be alive | `"transient"` | `true` | `agentchrome connect` |
Scripts can branch on these fields to decide whether to relaunch Chrome or simply re-discover the connection.
## Usage Examples
<details>
<summary><strong>Page inspection</strong></summary>
```sh
# Get the accessibility tree with element UIDs
agentchrome page snapshot
# Extract visible text content
agentchrome page text
# Find elements by text or role
agentchrome page find "Submit" --role button
```
</details>
<details>
<summary><strong>Form filling</strong></summary>
```sh
# Snapshot to discover form field UIDs
agentchrome page snapshot
# Fill multiple fields at once (returns updated snapshot)
agentchrome form fill-many --include-snapshot \
'[{"uid": "s5", "value": "hello@example.com"}, {"uid": "s8", "value": "MyPassword123"}]'
# Or fill fields individually
agentchrome form fill s5 "hello@example.com"
# Click the submit button
agentchrome interact click s10
```
</details>
<details>
<summary><strong>Screenshots</strong></summary>
```sh
# Viewport screenshot
agentchrome page screenshot --file screenshot.png
# Full-page screenshot
agentchrome page screenshot --full-page --file full-page.png
```
</details>
<details>
<summary><strong>JavaScript execution</strong></summary>
```sh
# Run a JavaScript expression and get the result
agentchrome js exec "document.title"
# Run JavaScript from a file
agentchrome js exec --file script.js
```
</details>
<details>
<summary><strong>Network monitoring</strong></summary>
```sh
# List recent network requests
agentchrome network list
# Filter requests by URL pattern
agentchrome network list --filter "api"
# Get details for a specific request
agentchrome network get <request-id>
```
</details>
<details>
<summary><strong>Pre-automation diagnostics</strong></summary>
```sh
# Scan a new URL for automation challenges before you begin
agentchrome diagnose https://example.com/course
# Diagnose the already-loaded page in place (no navigation)
agentchrome diagnose --current
# Extract strategy suggestions for each matched pattern
# Check if the page is straightforward to automate
</details>
<details>
<summary><strong>Interaction strategy guides</strong></summary>
```sh
# List all scenario-based interaction strategy guides
agentchrome examples strategies
# Show the full guide for iframe automation
agentchrome examples strategies iframes
# Get all strategy guides as JSON (for AI agent discovery)
agentchrome examples strategies --json
# Get the full SCORM/LMS strategy as JSON
agentchrome examples strategies scorm --json
```
Available strategies: `iframes`, `overlays`, `scorm`, `drag-and-drop`, `shadow-dom`, `spa-navigation-waits`, `react-controlled-inputs`, `debugging-failed-interactions`, `authentication-cookie-reuse`, `multi-tab-workflows`.
</details>
## Related Projects
- **Chrome DevTools MCP servers** — If you need MCP-based browser control rather than a CLI tool, use a CDP-backed MCP server.
## Contributing
All contributions must follow the [NMG-SDLC](https://github.com/Nunley-Media-Group/nmg-plugins) workflow without deviation. NMG-SDLC is a BDD spec-driven development toolkit that enforces a structured delivery lifecycle: issue creation, specification writing, implementation, verification, and PR creation. Contributions that bypass the SDLC process will not be accepted.
### Prerequisites
- [Rust](https://rustup.rs/) 1.93.0 or later (pinned via `rust-toolchain.toml`)
- Chrome or Chromium (for integration testing)
- Codex with the [NMG-SDLC plugin](https://github.com/Nunley-Media-Group/nmg-plugins) installed
### Build and test
```sh
git clone https://github.com/Nunley-Media-Group/AgentChrome.git
cd AgentChrome
# Build
cargo build
# Run tests
cargo test
# Lint
cargo clippy -- -D warnings
cargo fmt --check
# Generate man pages
cargo xtask man
```
### Code style
This project uses strict Clippy configuration (`all = "deny"`, `pedantic = "warn"`) and rustfmt with the 2024 edition. All warnings must be resolved before merging.
## License
Licensed under either of [MIT License](LICENSE-MIT) or [Apache License, Version 2.0](LICENSE-APACHE) at your option.