git:20260729.ccb9566 to git:20260806.b85ae9f

---

name: co-browser

description: Drive one persistent, logged-in browser from the shell with `co browser`. Use when the user asks to open a page, log into a site, scrape/extract page content, fill forms, upload files, take screenshots, or automate any browser task — solo or with multiple agents sharing the browser.

tools:

- Bash(co browser *)

- Bash(CO_WHO=*)

- Bash(export CO_WHO=*)

- Bash(timeout *)

- Bash(grep *)

- Bash(sed *)

- Bash(tail *)

- Bash(sort *)

- Bash(sleep *)

- Bash(pkill *)

- read_file

---

# co browser Skill

Drive **one real browser** from the shell. The browser stays open between commands —

cookies and logins persist until `co browser close`. Every terminal on the machine

talks to the same daemon: one browser, one board, no matter where you type.

**Always read the output, not just the exit code.** A failed action (selector not

found, browser not open) often returns exit `0` with the error text on stdout —

never chain `co browser ... && next_step` as your only success check.

## Step 1: Identity — who are you?

The daemon attributes every tab to a caller and uses that identity to stop two

agents from silently driving the same page. **Set `CO_WHO` explicitly** — shell

state does not survive between your tool calls, so a lone `export` is lost.

Either prefix every command:

```bash

CO_WHO=alice co browser go_to example.com

```

or keep the export and the commands in the SAME shell invocation:

```bash

export CO_WHO=alice && co browser go_to example.com && co browser get_text

```

(Some environments — e.g. Claude Code background jobs — are auto-identified,

but setting `CO_WHO` is always safe and never worse.) An anonymous caller still

works but gets **no contention protection**.

## Step 2: Check the board, then claim a tab

**One task = one tab.** Before touching the browser, see what's already happening:

```bash

co browser status # browser state, headless flag, last command, the board

co browser tab ls # every tab: who owns it, purpose, last command (--json for scripting)

```

**Solo (nobody else on the board)** — bare commands run on the shared `main` tab, no ceremony:

```bash

co browser go_to example.com # runs on 'main'

co browser get_text # still 'main'

```

**Concurrent (another agent or a second parallel task exists)** — open your own tab

and add `-t <name>` to EVERY command, including `do`. Pick an explicit literal tab

name — a `NAME=$(...)` capture is lost between tool calls:

```bash

CO_WHO=alice co browser tab open scrape --for "scrape pricing" --needs 10m

CO_WHO=alice co browser -t scrape go_to example.com/pricing

CO_WHO=alice co browser -t scrape do "extract every plan and its monthly price"

CO_WHO=alice co browser tab close scrape # release when done

```

`--needs` is your estimate of how long you will hold the tab (`30s`, `10m`, `2h`).

Say it: other agents leave your tab alone until then, and `co browser tab ls`

shows them when you expect to finish. Without it, two minutes of silence is

enough for another agent to take your tab — which is wrong when you are waiting

on a slow page or a human.

When delegating browser work to subagents, write each subagent's tab name into its

prompt — parallel agents share the one logged-in browser through separate tabs.

## Step 3: Pick the right verb

Two ways to drive the browser — pick per command, mix freely:

**Direct functions** (deterministic, instant, free — no LLM). Use for every step you can spell out:

```bash

co browser go_to https://example.com/login # https:// assumed if omitted

co browser get_text # visible page text

co browser get_links_from_page # every link, one per line

co browser take_screenshot /tmp/page.png # saves a PNG, prints its path

co browser click_element_by_selector "button" --index=0 --text="Send message"

co browser type_text_by_selector "#email" "user@example.com"

co browser scroll # scroll the page (scroll 3 = fewer steps)

co browser get_current_url

```

`co browser help` prints the live list of every function with its arguments —

trust it over any example here. Calling a function with wrong arguments returns

its usage line: self-correct from that.

**Typing into whatever already has focus** — after a `mouse_click` into a field

that no selector reaches cleanly — is `keyboard_type`, and pressing keys is

`keyboard_press`. There is **no `type_text`**; that name returns

"unknown command" and costs a round trip. Use `type_text_by_selector` when a

selector works, `keyboard_type` when only focus is available.

`keyboard_type` **appends** — it does not replace. To overwrite a field: click

into it, then `keyboard_press "Meta+a"` (macOS) and `keyboard_press "Backspace"`

before typing, or you get `1:15 AM09:00 AM`. And confirm the click actually landed

inside the input: if it missed, `Meta+a` selects the **entire page** instead and

your text goes nowhere while the screen turns blue. The screenshot after typing is

the only way to tell those two outcomes apart. (The verb is `scroll`, not `scroll_down`;

guessing a plausible name costs a round trip.)

**Never hunt for an item by scrolling a feed.** Infinite lists re-render as they

lazy-load, so scroll position is not reproducible: the same `scroll 6` lands

somewhere different each time, `Home`/`Meta+Home` do not return you to the top,

and the card you were aiming at moves between screenshots. Worse, clicking a

per-item menu you located by eye can hit a *neighbouring* item — on a destructive

action that is the wrong row deleted.

Extract the item's id once, then address it directly:

```bash

# 1. one script over the whole list, returning ids -- not screenshots

co browser -t mytab run_page_script /abs/find-id.js # match on text, return data-urn/data-id

# 2. open that item alone, where its controls cannot be confused with anything else

co browser -t mytab go_to "https://example.com/item/<id>/"

```

Six scroll-and-screenshot round trips became one script plus one `go_to` this way,

and the per-item menu became unambiguous because the page held exactly one item.

**`do "<instruction>"`** (natural language — an AI agent sees the page and works out

the steps). Use for judgment, not for steps you already know:

```bash

co browser do "log in with the saved credentials and open my notifications"

```

Describe the **end state**, not the steps. A `do` is a full agent run — many LLM

calls, possibly minutes — and the daemon is busy for its whole duration, so other

commands queue behind it. **Never wrap `do` in `timeout`**: killing the client

does not stop the run, it only orphans it (you pay for an answer nobody reads).

For state checks, prefer the free text probes first (exit 0 = matched):

```bash

co browser get_current_url | grep "/feed"

```

Only when the state is visually ambiguous, fall back to a one-word `do` probe:

```bash

co browser do "Look at the current page. Reply EXACTLY one of: STATE: feed | STATE: login | STATE: error"

```

## Step 4: Verify with evidence

- **Routine checks are text checks**: `get_current_url` / `get_text` after

navigation and clicks. Reserve screenshots for evidence gates.

- **Irreversible actions (submit, post, publish, pay) get the full gate**:

screenshot before, act **exactly once**, screenshot after. Never click the same

submit button twice — if the result is ambiguous, report uncertain state

instead of retrying.

- Long pages: dump once and read locally instead of re-extracting per chunk:

```bash

co browser get_text > /tmp/page.txt # one daemon round-trip

sed -n '1,200p' /tmp/page.txt

```

- To find stable selectors, save the DOM and grep it:

```bash

co browser save_page_context li_composer

grep -o 'aria-label="[^"]*"' ~/.co/browser_context/*li_composer*/page.html | sort -u

```

- Site-specific DOM logic belongs in skill-local JS run with an **absolute path**

(the daemon resolves relative paths against its own cwd, not yours):

```bash

co browser run_page_script /path/to/project/.co/skills/<skill>/scripts/extract-items.js

```

## Step 5: React to failures

Exit codes cover the daemon-level contract; the output text covers the action itself:

| Signal | Meaning | What to do |

|--------|---------|------------|

| exit `0`, clean output | success | continue |

| exit `0`, error text on stdout | the action failed softly (e.g. "No element found for selector") | read it, adjust selector or approach |

| exit `1` | the command raised (bad arguments print the usage line) | self-correct from the message |

| exit `2` | usage error (bad flags, empty `-t`, `tab` misuse) | fix the command syntax |

| exit `3` | unknown tab | `tab open` the name first, then target it |

| exit `4` | tab busy — another agent is mid-task there | do NOT retry the same command — the error prints the exact commands to run instead; follow them |

The exit-3/4 error messages ARE the documentation — they always carry the current

recovery steps, so trust them over this table.

When a tab blocks you, read `co browser tab ls` before deciding. Each tab shows

when its owner expects to finish:

```

[scrape] https://... who=alice purpose='scrape pricing' open 3m

owner expects to finish by 14:20 (7m left) — leave it alone until then

```

Inside that window, open your own tab instead. Once it has passed, the tab is

free and closing it is a courtesy — an estimate that ran out with the tab still

open means that agent crashed, not that it is still working. Every agent here is

cooperative; tidying up after a dead peer is expected, taking a live agent's page

is not.

## Logging in

The default is a **visible** window — exactly what you want for a first login.

Never automate credentials: open the login page, tell the user, then check with

short waits — one short check per tool call, not one long blocking loop (a long

loop hits the tool timeout, and every poll refreshes your claim on the tab,

locking other agents out for its whole duration):

```bash

co browser go_to https://site.com/login

# tell the user to log in in the visible window, then per check-in:

sleep 15 && co browser get_current_url | tail -1

```

Repeat the check a handful of times; if the URL is still the login page after

that, stop and ask the user instead of looping forever. Logins live in the profile (`~/.co/browser_profile/`),

not the daemon — they survive `close` and restarts. Log in once, stay logged in.

Headless: `co browser --headless go_to ...` — the mode is fixed by whichever

command **starts** the daemon (`status` shows `headless=true/false`). To switch:

`co browser close`, then relaunch.

## Scripting hygiene

- Wrap **direct functions** that might block in `timeout 60 ...`; never `timeout` a `do`.

- Take the data line with `tail -1` when output includes env banners.

- Batch related commands in one tool call; never spend a whole call on a bare wait.

- Uploads: try `upload_file_by_selector 'input[type="file"]' <path>` first; if the

input is hidden behind a button, `upload_file_after_click_by_selector '<button selector>' <path>`.

## Troubleshooting

- **"Where is my window?"** — `co browser status` says `headless=true`? An earlier

command started the daemon headless. `co browser close`, rerun without the flag.

- **"daemon is busy"** — a long `do` is holding the single-threaded daemon. Wait

and retry; `co browser status` shows the last command once it frees up.

- **"Opening in existing browser session" / profile in use (shows a PID)** — a

manually opened Chrome or stale daemon holds the profile; kill that PID, retry.

- **`TargetClosedError` after a crash** — the page died under the daemon; run

`co browser open_browser` again before retrying the command.

- **"Chrome failed to start"** — usually ssh/cron without a desktop session (run

from a logged-in Terminal, or use `--headless`). Full launch log: `~/.co/browser.log`.

- **Nuclear option** — kill the daemon and let the next command start fresh

(logins survive in the profile):

```bash

```

## Done checklist

- [ ] Identity attached to every command (`CO_WHO=... co browser ...`)

- [ ] Board checked (`status` / `tab ls`) before claiming a tab

- [ ] Own tab used if any other agent/task shares the browser (`-t` on every command)

- [ ] Output text read on every command, not just exit codes

- [ ] Irreversible actions performed exactly once, with before/after screenshots

- [ ] Tab closed (`co browser tab close <name>`) when the task is done

- [ ] Browser left open for the next task unless the user asked to `close`