firefox-control
/firefox-control
Automatyzuje przeglądanie stron w Firefoksie przez WebDriver BiDi: lista kart, wykonywanie JavaScriptu, zrzuty ekranu i pomocniki DOM.
- Autor
- vre ↗
- Repozytorium
- flow-state ↗
- Licencja
- MIT
- Ostatnia zmiana repozytorium
- 22.09.2026
Ocena i bezpieczeństwo
- Pliki w paczce
- 8
- Skrypty
- 3
- Komentarze HTML
- 0
- Adresy URL w SKILL.md
- 5
Brak sygnałów. Repozytorium zmienione 22.09.2026, bez odwołań do wycofanych modeli i API.
MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.
- 3 skrypty w paczce. Przejrzyj je przed instalacją, bo Claude może je uruchomić.
Skrypty: firefoxctl.py, firefoxctl_daemon.py, injection_defense.py
Co robi i kiedy
Automatyzuje przeglądanie stron w Firefoksie przez WebDriver BiDi: lista kart, wykonywanie JavaScriptu, zrzuty ekranu i pomocniki DOM.
Oryginalny opis (EN)
Use to automate web browsing via Firefox WebDriver BiDi — tab listing, JS evaluation, screenshots, DOM helpers.
Jak działa
- Usage
- Target commands
- DOM helpers
- Raw BiDi
- Gotchas
Podgląd SKILL.md
---
name: firefox-control
description: Use to automate web browsing via Firefox WebDriver BiDi — tab listing, JS evaluation, screenshots, DOM helpers.
---
# Firefox Control
Control Firefox via WebDriver BiDi on port 9223. Direct BiDi WebSocket,
no geckodriver. Use port 9223 because more popular Chrome CDP occupies 9222.
Launch Firefox: `firefox --remote-debugging-port 9223`
**TEST TOOL**: `navigator.webdriver=true` — detected by every anti-bot
system. No toggle exists. Use Chrome CDP for production automation.
## Usage
Just run a command — the daemon auto-starts on first call and connects to Firefox on port 9223. If Firefox isn't running or doesn't have remote debugging enabled, the error message will say so.
Full command list: `uv run firefoxctl.py --help`
Per-command help: `uv run firefoxctl.py COMMAND --help`
Always use `uv run` (PEP 723 inline dependencies):
```bash
uv run firefoxctl.py list
uv run firefoxctl.py --json list
uv run firefoxctl.py open https://example.com
uv run firefoxctl.py status
uv run firefoxctl.py targets
uv run firefoxctl.py stop
```
`--json` goes BEFORE the subcommand (global flag). The daemon idles out after 5 min. Unix socket: /tmp/firefoxctl-{uid}.sock. Tool responses are sanitized against prompt injection.
## Target commands
All target commands: `uv run firefoxctl.py CONTEXT COMMAND [ARGS]`
Context ID from list output (full UUID required — no prefix match).
```bash
uv run firefoxctl.py CONTEXT eval "document.title"
uv run firefoxctl.py CONTEXT screenshot -o page.png
uv run firefoxctl.py CONTEXT console-tail --for 30
uv run firefoxctl.py CONTEXT navigate https://example.com
```
**`navigate` and `open` may hand you a different context back.** Firefox sometimes answers a
navigation by replacing the browsing context rather than reusing it — the id you
asked for is destroyed and a new one appears at the target URL. `navigate` follows
the swap when it can identify the replacement:
```bash
uv run firefoxctl.py --json navigate "$ctx" https://example.com/feed.json
# {"navigation": "...", "url": "...", "context": "<same id>"}
# {"navigation": null, "url": "...", "context": "<NEW id>", "context_swapped": true}
```
**Read `context` back from the result — do not reuse the id you passed in, and for
`open`, not the tab you think it created.** `open` navigates through the same path:
its navigation is always a context's first, which is exactly the one a container
assignment replaces.
It adopts a new context only when that context is **new, at the address you
requested, and in the window the original was in**, and refuses when two qualify.
A Firefox that does not report `clientWindow` gets no recovery at all — the discard
propagates, as it did before this existed.
The address comparison is exact — query and fragment included, and only an empty
path is treated as `/`. A target that **redirects** therefore raises: the
replacement is at the redirected address, which no longer matches. Navigate to the
final URL, or handle the error.
Navigation failures propagate unchanged.
## DOM helpers
Shorthands for common eval patterns. Selectors are CSS.
```
click/check/uncheck/highlight SELECTOR
submit/clear FORM
type/fill SELECTOR TEXT
select SELECTOR VALUE
get-text/get-html/get-value/exists/count/get-texts SELECTOR
get-attr SELECTOR ATTR
scroll-to/wait-for/wait-hidden SELECTOR
wait-text SELECTOR TEXT
navigate URL
wait-url PATTERN
scroll-up/scroll-down [PIXELS]
scroll-by X Y
inject-css CSS
reload/back/forward/get-title/get-url/scroll-top/scroll-bottom
```
Wait commands: --timeout N (default 10s)
For anything not covered: `uv run firefoxctl.py CONTEXT eval "JS expression"`
Top-level await: `uv run firefoxctl.py CONTEXT eval "await fetch('/api').then(r => r.json())"`
## Raw BiDi
```bash
uv run firefoxctl.py bidi browser.getClientWindows
uv run firefoxctl.py bidi browsingContext.getTree --params '{}'
```
## Gotchas
### A container assignment replaces the context mid-navigation
`browsingContext.navigate` can return `Error: Browsing context got discarded` when
the navigation **succeeded** — the page is loaded under a new id.
The cause is a `userContext` (container) switch. An extension such as Multi-Account
Containers assigns a site to a container, and a context cannot change container in
place, so Firefox builds a new one and discards the old. Measured on
www.reddit.com 2026-09-22: the replacement carries the requested URL, the same
`clientWindow`, and the assigned `userContext`. It is **host-specific** — only sites
with an assignment rule swap — and **first-navigation only**: once a context is in
the container, it navigates normally.
Consequences:
- A profile with no container rules never sees this, so it will not reproduce on a
clean test profile.
- Creating the tab directly in the assigned container (`browsingContext.create` with
`userContext`) avoids the swap. The container's BiDi id is generated per session —
read it from `browser.getUserContexts`, never hardcode it.
- **BiDi exposes no "replaced context X" relation**, so `navigate`'s recovery is a
heuristic. What is left of it after the URL and window checks: the user would have
to open that exact URL, in that window, between the snapshot `navigate` takes and
the end of the wait. Accepted, not eliminated — "new" is new since that snapshot,
not since Firefox acted on the navigation.
If you need certainty rather than a narrow risk: validate what you get back (the
document's origin, or a marker you set before navigating), or drive a window nothing
else can create contexts in.
### `list` URLs lie on error pages — validate before trusting a tab
A Firefox error page (`about:neterror`, e.g. after a transient DNS failure)
**keeps the requested URL** in `list` output. So picking a tab by matching its
URL silently selects a dead tab:
```bash
uv run firefoxctl.py list # shows https://example.com/ ← looks fine
```
but the document is an error page with an **opaque origin**, so every `fetch()`
from it fails — relative URLs with `"X is not a valid URL"`, absolute ones with
`NetworkError` — and `eval` still works, which makes it look healthy.
Check the document, not the listing:
```bash
uv run firefoxctl.py CONTEXT eval "document.baseURI" # about:neterror?e=dnsNotFound&u=...
uv run firefoxctl.py CONTEXT eval "String(window.origin)" # "null"
```
A live page has `baseURI` starting with the real URL and `origin` equal to the
site. Recover by re-navigating the same context:
```bash
uv run firefoxctl.py CONTEXT navigate https://example.com/
```
This bit the wiki's daily fetch pipeline twice in one week (2026-07-31,
2026-08-04): the tab died on a DNS blip, every subsequent run silently returned
0 posts, and the failure looked like a quiet news day rather than an error. Any
script that reuses a long-lived tab should validate `baseURI` + `origin` after
selecting it, and treat an empty result as an error rather than as data. See
`research/2026-04-05-m5-max-local-llm/scripts/fetch_daily.py`
(`_firefox_tab_is_live`) for a reference implementation.
### `navigate` rejects `about:` URLs and unresolvable hosts
BiDi refuses both, so you cannot force an error page to test recovery paths —
verify the detection predicate against captured values instead.
Pliki w paczce (8)
- .gitignore 1 KB
- CHANGELOG.md 2 KB
- LICENSE 1 KB
- README.md 10 KB
- SKILL.md 7 KB
- firefoxctl.py 49 KB
- firefoxctl_daemon.py 5 KB
- injection_defense.py 4 KB
Wersje
W bazie nie ma innych skilli o nazwie firefox-control.
Migawka bazy z 13.11.2026 · wersja paczki 4ba5a2513630 (skrót SHA-256 całej paczki)
Pobrania w ostatnich 30 dniach: 0 · ranking
Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.
Podobne skille
- 100firefox-cli
Steruje Firefoksem użytkownika z terminala: nawigacja, karty i okna, zrzuty ekranu, odczyt DOM, oczekiwanie i interakcje na stronie w zalogowanej sesji. - 100webdriverbidi-net
Pomaga pisać w C# kod z biblioteką WebDriverBiDi.NET do sterowania przeglądarkami przez protokół BiDi. - 100firefox-extension-dev
Udostępnia wiedzę referencyjną o WebExtension w Firefoksie, obejmującą manifest.json, API browser.*, proces zgłoszenia do AMO i web-ext CLI. - 100firefox
Steruje przeglądarką Firefox na macOS: otwiera adresy URL, zamyka i przełącza karty, pobiera dane aktywnej karty oraz wysyła skróty klawiszowe. - 100upgrade-browser
Podnosi wersje przeglądarek Chrome lub Firefox w testach Flutter Web Engine i Framework. - 100webapp-selenium-testing
Pisze i utrzymuje testy Selenium WebDriver w Javie z JUnit 5, z Page Object, jawnymi czekaniami i zrzutami ekranu.