Skip to content
Skills Library
Programming · Building & coding

browser-connect

/browser-connect

Use when reaching a running browser over CDP from Rust. Attach, bind a tab, launch.

Repository
Agito ↗
Licence
CC0-1.0
Last repository change
13.11.2026

Assessment and security

90/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content30 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
4
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

CC0-1.0, otwarta.

What it does and when to use it

Use when reaching a running browser over CDP from Rust. Attach, bind a tab, launch.

Original author description

Use when reaching a running browser over CDP from Rust. Attach, bind a tab, launch.

How it works

  1. The three operations
  2. Find the endpoint
  3. Bind an existing tab
  4. Failure codes
  5. Never attach to a tab a debugger already holds
  6. Reference
  7. Claim → test
Original SKILL.md headings · 123 lines, 860 words
SKILL.md preview
---
name: browser-connect
description: Use when reaching a running browser over CDP from Rust. Attach, bind a tab, launch.
version: 1.0.0
license: MIT
platforms: [macos, linux]
metadata:
    hermes:
        tags: [cdp, rust, chromiumoxide, attach, target]
---

# Browser Connect

Reach a browser this process did not start, and bind the tab a person is looking at. The Rust
substrate is `agito-browser-cdp`; the executable is `agito browse`.

---

## The three operations

They differ in who owns the process and which page is touched, so they are three statements, not one
boolean.

**Launch** starts a browser this session owns and may close. `OpenOptions::Launch(call)`.

**Attach** connects to a browser somebody else owns and opens a new page in it.
`OpenOptions::Attach(endpoint, call)`.

**Bind** connects to that browser and drives a page it already has.
`OpenOptions::Existing(endpoint, page, call)`.

Disposal reads the ownership: a launched browser is closed, an attached one is only let go of. A
bind that closed the page would take away the tab the person was reading, which is the whole reason
ownership is recorded.

---

## Find the endpoint

Two endpoints exist and they are not interchangeable. `/json/version` carries the browser-level one
that attach needs; `/json/list` carries per-tab ones and is the only honest tab inventory.

```sh
curl -s http://127.0.0.1:<debug-port>/json/version | python3 -c 'import sys,json;print(json.load(sys.stdin)["webSocketDebuggerUrl"])'
curl -s http://127.0.0.1:<debug-port>/json/list | python3 -c 'import sys,json;[print(t["id"],"|",t["type"],"|",t["url"][:80]) for t in json.load(sys.stdin)]'
```

The `id` from `/json/list` is the target id a bind takes. Filter `type == "page"`: a listing also
carries extension pages, service workers and iframes, and a bind by URL prefix matches a non-page.

---

## Bind an existing tab

```sh
Target/debug/agito browse \
  --url https://example.test/ \
  --attach ws://127.0.0.1:<debug-port>/devtools/browser/<uuid> \
  --bind <target-id> \
  --expression '({title: document.title, url: location.href})' \
  --timeout 40000
```

`--bind` without `--attach` is refused, because a browser this tool launched has no page to bind.
The refusal is deliberate: silently opening a tab instead is the failure this flag exists to
prevent.

**Why a bind needs a fetch first.** A browser announces no `targetCreated` event for the tabs that
were already open when a client connected, so the handler's own map is empty and `Browser::pages()`
returns nothing. `Chrome::Bind` calls `Browser::fetch_targets()` before matching, which registers
those targets and starts an `AttachToTarget` round trip per target.

**Why the match is retried.** A page cannot be handed out until its session arrives, so a first
match can legitimately miss. The match is retried every 25 ms up to a 2 s grace
(`Chrome::PageGrace`); past it, the failure names every page the browser does hold, which is how a
race is told apart from a wrong id:

```
navigation-failed: the browser holds no page matching the one asked for
no target id or URL starts with AAAA...; it holds [1111... https://... | 2222... chrome-extension://...]
```

Matching is target id first, URL prefix second. The id is exact and the prefix is not, so a caller
that knows only the URL gets the first page that starts with it.

**What a bind costs.** `fetch_targets` attaches a CDP session to _every_ target in that browser. On
a browser that also hosts an extension holding its own debugger, a second client on a tab can detach
the first. Bind deliberately, on the tab you mean, and do not enumerate a browser you do not intend
to drive.

---

## Failure codes

The port has three codes and the substrate maps every `chromiumoxide` error onto one of them, so a
caller never has to guess which library failed.

| Code                  | Means                                                  | Typical cause                                                        |
| --------------------- | ------------------------------------------------------ | -------------------------------------------------------------------- |
| `browser-unavailable` | there is no browser to talk to                         | socket closed, connect refused, process exited, no answer            |
| `navigation-failed`   | the transport is alive and the page is what went wrong | JavaScript exception, page not found, protocol error naming the page |
| `timeout`             | a deadline passed                                      | the caller's own budget, or silence                                  |

A closed transport wins over a page defect: once the socket is gone, the next failure is classified
`browser-unavailable` rather than as the page misbehaving.

---

## Never attach to a tab a debugger already holds

Two debugger clients cannot share one tab; the second attach detaches the first. If a tab is being
driven by an extension or another session, drive a different tab or a browser you launched. This is
a correctness rule, not a courtesy.

---

## Reference

`Reference/Index.md` - the file list for this skill.

---

## Claim → test

| Claim                                       | Test                                                                                                                           |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| A bind drives the page that is already open | `agito browse --attach <ws> --bind <id> --expression 'location.href'` returns that tab's URL, and `/json/list` gains no target |
| An attach without a bind opens a page       | the same command without `--bind` makes `/json/list` show one more `page` target                                               |
| A bind without an attach is refused         | `agito browse --bind <id>` exits non-zero naming `--attach`                                                                    |
| A wrong target id is reported, not guessed  | `--bind deadbeef` exits non-zero and lists the pages the browser holds                                                         |
| Ownership is honoured on release            | after a bind, the bound tab is still in `/json/list`; after a launch, the browser is gone                                      |
| The browser-level endpoint is the one used  | attaching with a per-tab `/json/list` websocket fails as `browser-unavailable`                                                 |
Files in this package (2)
  • SKILL.md 6 KB
  • Reference/Index.md 1 KB

Versions

The database has no other skills named browser-connect.

Database snapshot: 13.11.2026 · package version 0316460ac6c6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 86browser-automation
    Use when code must drive a real browser (Playwright, CDP).
  • 90browser_cdp
    Use this skill when the user explicitly wants to connect to a running Chrome browser, scan local CDP ports, specify a `cdp_port`, or share a single browser across multiple agents/tools. By default browser opens no debugging port; pass an explicit `cdp_port` only when the user…
  • 100operating-cdp-cli
    Drives a live browser with the repo's cdp CLI — attaching to a running Chrome/Brave, navigating, clicking, evaluating JavaScript, extracting page state, and running the screenshot-first observe-act-verify loop over cdp --mcp. Use when the task means operating a browser right now…
  • 91timeline-browser-transport
    Use when relaunching the CDP browser or its extension goes silent.
  • 100browser-harness
    Direct browser control via CDP — automate, scrape, test, or interact with web pages by driving the user's already-running Chrome (or a Browser Use cloud browser). Use when the user wants to click, screenshot, fill forms, extract data, or navigate real web pages. Default to…
  • 95browser
    Direct browser control via CDP. Use when the user wants to automate, scrape, test, or interact with web pages. Connects to the user's already-running Chrome.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.