This repository has no description
2.8 kB
98 lines
1# Browser CLI
2
3A command-line interface for controlling Firefox through WebExtensions API.
4Optimized for LLM agents with limited context windows.
5
6## Overview
7
8Browser CLI consists of three components:
9
101. **Firefox Extension** - Executes commands in the browser and provides visual
11 feedback
122. **Native Messaging Bridge** - Facilitates communication between the CLI and
13 extension
143. **CLI Client** - Minimal command-line tool that executes JavaScript via stdin
15
16## Installation
17
18### For Nix Users
19
20```bash
21nix run github:lassulus/superconfig#skills.browser-cli -- --help
22```
23
24### Manual Installation
25
261. **Install the Firefox Extension**
27 - Open Firefox
28 - Navigate to `about:debugging`
29 - Click "This Firefox"
30 - Click "Load Temporary Add-on"
31 - Select `manifest.json` from the `extension` directory
32
332. **Install Native Messaging Host**
34 ```bash
35 browser-cli --install-host
36 ```
37
38## Usage
39
40See [SKILL.md](SKILL.md) for usage examples and JavaScript API reference.
41
42## Architecture
43
44```
45┌─────────────┐ Unix Socket ┌──────────────┐ Native ┌────────────┐
46│ CLI │ ◄─────────────────► │ Bridge │ ◄─────────────► │ Extension │
47│ (stdin) │ │ Server │ Messaging │ │
48└─────────────┘ └──────────────┘ └────────────┘
49```
50
51## Development
52
53### Project Structure
54
55```
56browser-cli/
57├── extension/ # Firefox WebExtension
58│ ├── manifest.json
59│ ├── background.js # Extension service worker
60│ └── content.js # Page automation and JS API
61├── browser_cli/ # Python CLI package
62│ ├── cli.py # CLI entry point
63│ ├── client.py # Unix socket client
64│ ├── bridge.py # Native messaging bridge
65│ └── server.py # Bridge server
66└── pyproject.toml
67```
68
69### Building
70
71For Nix users:
72
73```bash
74nix build .#browser-cli
75```
76
77## Troubleshooting
78
79### Extension Not Connecting
80
811. Ensure Firefox is running
822. The Browser CLI extension is installed
833. Native messaging host is installed: `browser-cli --install-host`
844. Check Firefox console for errors: `Ctrl+Shift+J`
85
86### Commands Timing Out
87
88- Use `wait()` for dynamic content: `await wait("text", "Loaded")`
89- Check element refs are current: `snap()` to refresh
90
91### Stale Refs
92
93Refs are reset on each snapshot. If you get "Element [N] not found", call
94`snap()` to get fresh refs.
95
96## License
97
98MIT