<img src="assets/banner.svg" alt="firefox-bidi" height="70">

# firefox-bidi

Use Firefox from Pi when you want Pi to drive a real browser through WebDriver BiDi.
It is useful for opening pages, exercising browser behavior, inspecting results, or recording a screencast with Firefox-specific tooling.

[Installation](../../README.md#install)

## First use

Enable `codemode` or `tool_search` so Pi can discover Firefox, then ask Pi to perform browser task.
Firefox starts only when Pi first uses it and gets a fresh temporary profile.

```text
Use tool_search to find firefox_bidi, then open http://localhost:3000 and check whether the login form is usable.
```

Run `/firefox` when you want to declare Firefox directly to Pi instead of discovering it.
Run `/firefox close` to stop Firefox and remove its direct declaration; later scripts can still launch it.
Start Pi with `--firefox` or set `firefox-bidi.enable` to `true` for that direct declaration at startup.

## What to expect

Pi uses the bundled Firefox guidance when it needs to compose WebDriver BiDi requests.
Pi can send related browser actions together, receive browser responses and events, and wait for an expected event.
Firefox is headless unless Pi starts it with a visible window.
Firefox must be on `PATH`, or set `firefox-bidi.executablePath` or `FIREFOX_BIN` to its executable.
Set `firefox-bidi.screencastDir` when Firefox screencasts should use a different default destination.

## Privacy and control

Pi sends raw WebDriver BiDi commands to the Firefox process it starts.
Browser responses, events, screencasts, and page content can contain sensitive data.
Use the fresh default profile for isolated work.
Using privileged system access is a deliberate browser-launch choice, not a sandbox.

## Reference

<!-- config:start -->
### Commands

| Command | Purpose |
| --- | --- |
| `/firefox` | Declare firefox_bidi directly (/firefox), or tear down (/firefox close) |

### Setting names

| Setting | Environment | CLI flag |
| --- | --- | --- |
| `firefox-bidi.enable` | `PI_FIREFOX` | `--firefox` |
| `firefox-bidi.executablePath` | `FIREFOX_BIN` |   |
| `firefox-bidi.screencastDir` |   |   |
<!-- config:end -->