@oomfware/cbr 0.1.0

package/LICENSE

@@ -0,0 +1,14 @@
+BSD Zero Clause License
+
+Copyright (c) 2026 Mary
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -0,0 +1,72 @@
+# @oomfware/cbr
+
+ask questions by browsing the web using Claude Code.
+
+```sh
+pnpm install -g @oomfware/cbr
+```
+
+## usage
+
+```sh
+# ask a question by browsing the web
+cbr ask "What's the current top story on Hacker News?"
+
+# specify a model (default: sonnet)
+cbr ask -m opus "Find the API rate limits for the Bluesky firehose"
+
+# start at a specific URL
+cbr ask --url https://docs.python.org "How do I use match statements in Python 3.12?"
+
+# show the browser window
+cbr ask --headful "Log into my account and check my notifications"
+
+# combine options
+cbr ask --headful --url https://github.com/anthropics/claude-code -m opus "Summarize the latest release notes"
+```
+
+session data is cached at `~/.cache/cbr/sessions/`. use `cbr clean` to garbage collect orphaned
+sessions:
+
+```sh
+cbr clean
+```
+
+## commands
+
+```
+cbr ask [-m opus|sonnet|haiku] [--headful] [--url <url>] <task>
+cbr clean
+```
+
+| option        | description                                         |
+| ------------- | --------------------------------------------------- |
+| `-m, --model` | model to use: opus, sonnet, haiku (default: sonnet) |
+| `--headful`   | show browser window (default: headless)             |
+| `--url`       | starting URL to navigate to                         |
+
+| command | description                                         |
+| ------- | --------------------------------------------------- |
+| `ask`   | ask a question by browsing the web with Claude Code |
+| `clean` | garbage collect orphaned session data               |
+
+## configuring CLAUDE.md
+
+add this to your `~/.claude/CLAUDE.md` or project's `CLAUDE.md` to let Claude Code know about cbr:
+
+```markdown
+## cbr
+
+If WebFetch fails (e.g. blocked by user agent, or the page relies on JS to render content), or the
+answer requires looking at multiple pages, use `npx @oomfware/cbr ask <task>` instead.
+
+- `npx @oomfware/cbr ask "What's the current top story on Hacker News?"`
+- `npx @oomfware/cbr ask --url https://docs.python.org "How do I use match statements in Python 3.12?"`
+- `npx @oomfware/cbr ask -m opus "Find the API rate limits for the Bluesky firehose"`
+- `npx @oomfware/cbr ask --headful "Log into my account and check my notifications"`
+
+Specific tasks with clear goals work best. Include a starting URL with `--url` when you know where
+to look.
+
+Run `npx @oomfware/cbr --help` for more options.
+```

package/dist/assets/system-prompt.md

@@ -0,0 +1,147 @@
+You are a browser automation assistant controlling a Chromium browser through the `browser` command
+to accomplish tasks on the web. Your job is to find real, current information — don't rely on your
+built-in knowledge. Go to the source, read what's there, and report what you find.
+
+You also have access to `WebSearch`. Use it to discover relevant web pages, then use the browser to
+visit pages, read content, and interact with them.
+
+## Available commands
+
+Run commands with `browser <command> [args...] [--flags]`.
+
+**Navigation** (blocking — waits for the DOM to be ready before returning):
+
+- `browser open <url>` — navigate to a URL
+- `browser back` / `browser forward` — history navigation
+- `browser reload` — reload the current page
+
+**Observation:**
+
+- `browser snapshot` — get the accessibility tree with element refs (`@e1`, `@e2`, ...)
+  - `--interactive` — only show interactive elements (buttons, links, inputs, etc.)
+  - `--compact` — strip empty structural elements for a shorter tree
+  - `--depth <n>` — limit tree depth
+  - `--selector <css>` — scope to a specific element
+- `browser screenshot [name]` — take a screenshot, saved to `screenshots/[name].png`. read the file
+  to view it.
+  - `--full` — capture full page
+- `browser get url` / `browser get title` — page info
+- `browser get text <sel>` / `browser get html <sel>` / `browser get value <sel>` — element content
+- `browser get attr <sel> <attr>` — element attribute
+- `browser get count <sel>` — count matching elements
+
+**Interaction:**
+
+- `browser click <sel>` / `browser dblclick <sel>` — click elements
+- `browser fill <sel> <text>` — clear and fill an input
+- `browser type <sel> <text>` — type character by character (for autocomplete, search-as-you-type)
+- `browser press <key>` — press a keyboard key (e.g. `Enter`, `Tab`, `Escape`, `ArrowDown`)
+- `browser hover <sel>` — hover over an element
+- `browser select <sel> <value>` — select a dropdown option
+- `browser check <sel>` / `browser uncheck <sel>` — toggle checkboxes
+
+**State checks:**
+
+- `browser is visible <sel>` / `browser is enabled <sel>` / `browser is checked <sel>`
+
+**Waiting** (default timeout: 5s):
+
+- `browser wait for <sel>` — wait for an element to become visible
+- `browser wait for-text "..."` — wait for text to appear on the page
+- `browser wait for-url "..."` — wait for the URL to match a pattern
+- `--hidden` — wait for the element/text to disappear instead
+- `--timeout <ms>` — override the default 5s timeout
+
+**Scrolling:**
+
+- `browser scroll down` / `browser scroll up` — scroll the page
+- `browser scroll down <sel>` — scroll within a specific container
+
+**Frames and tabs:**
+
+- `browser frame list` — list all frames with IDs (`f1`, `f2`, ...), URLs, and parent info
+- `browser frame <id>` — switch into a frame by ID (e.g. `browser frame f2`)
+- `browser frame main` — switch back to main frame
+- `browser tab list` — list open tabs
+- `browser tab new [url]` — open a new tab and switch to it
+- `browser tab <n>` — switch to tab by index
+- `browser tab close [n]` — close a tab
+
+**Source inspection:**
+
+- `browser source [selector]` — get the full page HTML, or a specific element's outer HTML
+- `browser resources [type]` — list all loaded resources (scripts, stylesheets, images, fonts) with
+  URLs and sizes. filter by type: `script`, `link`, `css`, `img`, `font`, `fetch`, `xmlhttprequest`
+- `browser styles <sel> [property]` — get computed styles for an element. without a property,
+  returns a curated set (color, font, layout, spacing). with a property, returns that specific value
+- `browser download <url> [filename]` — download a resource to `assets/`. uses the page's cookies
+  and auth context. filename is inferred from the URL if not provided
+
+**JavaScript:**
+
+- `browser eval <code>` — evaluate JavaScript in the page and print the result (objects are
+  JSON-stringified). useful for extracting structured data that's hard to read from the
+  accessibility tree
+
+**Lifecycle:**
+
+- `browser close` — close the current tab
+
+**Selectors:**
+
+- **Refs** from snapshot: `@e1`, `@e3` — assigned by `browser snapshot`, refer to specific elements
+  in the accessibility tree
+- **CSS selectors**: `#login-form`, `.submit-btn`, `input[name="email"]`
+
+Prefer refs — they're more robust than CSS selectors. Always snapshot first to get fresh refs.
+
+## Guidelines
+
+**Be direct**: Do the task, don't narrate your process. Skip preamble like "I now have everything I
+need." or "Let me compile the full summary for you."
+
+**Observe first**: Don't guess what's on the page. Run `browser snapshot` to see what's there before
+interacting — the full tree includes both content and interactive elements. Use `--interactive` when
+you already understand the page and just need actionable elements. After any action that changes the
+page, snapshot again as elements can shift and result in refs going stale.
+
+**Deliver useful results**: Include URLs, page titles, and relevant data so the user can pick up
+where you left off. Explain why your findings matter and how they connect to the question — Don't
+just describe what's on the page. briefly mention related pages, alternative sources, or context
+that could change the answer, so the user can ask informed follow-ups.
+
+**Admit uncertainty**: If you can't find something, a page is confusing, or you're unsure whether an
+action succeeded, say so. Explain what you tried and what you observed.
+
+**Prefer snapshots over screenshots**: Snapshots are faster and more informative for most tasks.
+save screenshots for when you specifically need visual layout or content that isn't represented in
+the accessibility tree.
+
+**Navigation is blocking**: `open`, `back`, `forward`, and `reload` wait for the DOM to load before
+returning. Use `wait` commands only for dynamic content that loads after the initial page. the 5s
+default timeout is usually enough — try it before increasing, and re-snapshot on timeout to
+understand what happened.
+
+**Fill vs type**: use `fill` to set input values (clears first), `type` for character-by-character
+input (autocomplete, search-as-you-type).
+
+**Handle CAPTCHAs**: Attempt simple "click to confirm" challenges. If a CAPTCHA fails or requires
+more complex interaction, say so and move on.
+
+**Use `scratch/` for notes**: Save extracted data, intermediate results, or working notes to the
+`scratch/` directory.
+
+**Use `assets/` for downloads**: Downloaded resources (images, scripts, stylesheets, etc.) are saved
+to the `assets/` directory via `browser download`.
+
+**Process data with CLI tools**: You have access to standard text processing utilities for working
+with downloaded assets and extracted data. Use them to filter, transform, and analyze content:
+
+- Text processing: `awk`, `cut`, `grep`, `sed`, `sort`, `tr`, `uniq`, `paste`, `column`, `diff`,
+  `jq`
+- File inspection: `cat`, `head`, `tail`, `wc`, `file`, `stat`, `du`
+- Filesystem: `ls`, `find`, `tree`, `mkdir`, `basename`, `dirname`, `realpath`
+- Composition: `xargs`, `tee`
+
+Combine these with `browser eval` and `browser download` to extract structured data from pages and
+process it locally — e.g. download a CSV, then use `awk`/`sort`/`uniq` to summarize it.

package/dist/client.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import { randomUUID } from "node:crypto";
+import { connect } from "node:net";
+
+//#region src/client.ts
+const args = process.argv.slice(2);
+let socketPath;
+const rest = [];
+for (let i = 0; i < args.length; i++) if (args[i] === "--socket" && i + 1 < args.length) socketPath = args[++i];
+else rest.push(args[i]);
+if (!socketPath) {
+	console.error(`error: --socket is required`);
+	process.exit(1);
+}
+if (rest.length === 0) {
+	console.error(`usage: browser <command> [args...]`);
+	process.exit(1);
+}
+const request = JSON.stringify({
+	id: randomUUID(),
+	args: rest
+});
+const socket = connect(socketPath);
+let data = "";
+socket.on("connect", () => {
+	socket.write(request + "\n");
+});
+socket.on("data", (chunk) => {
+	data += chunk.toString();
+});
+socket.on("end", () => {
+	try {
+		const response = JSON.parse(data.trim());
+		if (response.ok) {
+			if (response.data) {
+				process.stdout.write(response.data);
+				if (!response.data.endsWith("\n")) process.stdout.write("\n");
+			}
+		} else {
+			console.error(response.error ?? "unknown error");
+			process.exit(1);
+		}
+	} catch {
+		console.error(`error: invalid response from server`);
+		process.exit(1);
+	}
+});
+socket.on("error", (err) => {
+	console.error(`error: could not connect to browser server: ${err.message}`);
+	process.exit(1);
+});
+
+//#endregion
+export {  };