Browser CLI#

A command-line interface for controlling Firefox through WebExtensions API. Optimized for LLM agents with limited context windows.

Overview#

Browser CLI consists of three components:

Firefox Extension - Executes commands in the browser and provides visual feedback
Native Messaging Bridge - Facilitates communication between the CLI and extension
CLI Client - Minimal command-line tool that executes JavaScript via stdin

Installation#

For Nix Users#

nix run github:lassulus/superconfig#skills.browser-cli -- --help

Manual Installation#

Install the Firefox Extension
- Open Firefox
- Navigate to about:debugging
- Click "This Firefox"
- Click "Load Temporary Add-on"
- Select manifest.json from the extension directory
Install Native Messaging Host
```
browser-cli --install-host
```

Usage#

See SKILL.md for usage examples and JavaScript API reference.

Architecture#

┌─────────────┐     Unix Socket     ┌──────────────┐     Native      ┌────────────┐
│    CLI      │ ◄─────────────────► │    Bridge    │ ◄─────────────► │ Extension  │
│  (stdin)    │                     │   Server     │    Messaging    │            │
└─────────────┘                     └──────────────┘                 └────────────┘

Development#

Project Structure#

browser-cli/
├── extension/          # Firefox WebExtension
│   ├── manifest.json
│   ├── background.js   # Extension service worker
│   └── content.js      # Page automation and JS API
├── browser_cli/        # Python CLI package
│   ├── cli.py          # CLI entry point
│   ├── client.py       # Unix socket client
│   ├── bridge.py       # Native messaging bridge
│   └── server.py       # Bridge server
└── pyproject.toml

Building#

For Nix users:

nix build .#browser-cli

Troubleshooting#

Extension Not Connecting#

Ensure Firefox is running
The Browser CLI extension is installed
Native messaging host is installed: browser-cli --install-host
Check Firefox console for errors: Ctrl+Shift+J

Commands Timing Out#

Use wait() for dynamic content: await wait("text", "Loaded")
Check element refs are current: snap() to refresh

Stale Refs#

Refs are reset on each snapshot. If you get "Element [N] not found", call snap() to get fresh refs.

License#

MIT

Configure Feed