Skip to content

An agentic browser harness: an AI side panel & orb in your own logged-in Chrome, Edge, Arc, Brave or even Firefox run by the agent/subscription you already use (Claude Code, Codex, Antigravity). Free, open source, no API key. Also an MCP server.

docs: open the door to community contributions

Shahriar196cd16ee0de
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml
new file mode 100644
index 0000000..a044512
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/bug_report.yml
@@ -0,0 +1,59 @@
+name: Bug report
+description: Something misbehaved — a tool failed, a run stalled, the panel did the wrong thing
+labels: [bug]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ Thanks for the report. Two things before the form:
+ - **Security problems are not issues.** A vulnerability in a tool that holds live browser
+ sessions goes through a [private advisory](https://github.com/imshaikot/browsentic/security/advisories/new).
+ - The [troubleshooting guide](https://browsentic.com/docs/guide/troubleshooting/) resolves
+ the common failures — worth two minutes first.
+ - type: textarea
+ id: what-happened
+ attributes:
+ label: What happened
+ description: What you asked for, what you got instead. Error codes verbatim if there were any.
+ placeholder: 'Asked the panel to fill a form on …; the run stopped with TAB_UNREACHABLE after …'
+ validations:
+ required: true
+ - type: textarea
+ id: repro
+ attributes:
+ label: How to reproduce it
+ description: Steps, and the site or page type it happens on if that matters.
+ placeholder: |
+ 1. Open …
+ 2. Say/run …
+ 3. …
+ validations:
+ required: true
+ - type: textarea
+ id: status
+ attributes:
+ label: Output of `browsentic status`
+ description: It names the daemon state, both versions, manifest sync and pairings — most reports are answered by it.
+ render: text
+ validations:
+ required: true
+ - type: input
+ id: agent
+ attributes:
+ label: Agent
+ description: Which agent CLI runs your side panel, if the bug involves a run.
+ placeholder: claude / codex / agy, and its version
+ - type: input
+ id: environment
+ attributes:
+ label: Environment
+ description: Browser and version, OS, Node version.
+ placeholder: Chrome 139, macOS 15.5, Node 22
+ validations:
+ required: true
+ - type: textarea
+ id: logs
+ attributes:
+ label: Relevant `browsentic logs` lines
+ description: Optional. The lines around the failure — tool calls and their outcomes. Trim anything private.
+ render: text
diff --git a/.github/ISSUE_TEMPLATE/capability.yml b/.github/ISSUE_TEMPLATE/capability.yml
new file mode 100644
index 0000000..2721929
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/capability.yml
@@ -0,0 +1,44 @@
+name: Capability proposal
+description: An idea for something Browsentic should be able to do to a page — or any feature
+labels: [enhancement]
+body:
+ - type: markdown
+ attributes:
+ value: |
+ A capability ships as an MCP tool the moment it lands in the registry, so its name, shape
+ and guardrails are API decisions. Two paragraphs here beat a rejected diff — and
+ [adding one](https://browsentic.com/docs/internals/contributing/) is one file plus one
+ line in the registry once the shape is agreed.
+ - type: textarea
+ id: job
+ attributes:
+ label: The job
+ description: What would a user say to the panel, and what should happen? Real scenario over abstract capability.
+ placeholder: '"Download the CSV export and attach it to the ticket" — today the run stops at …'
+ validations:
+ required: true
+ - type: textarea
+ id: today
+ attributes:
+ label: Where it stops today
+ description: What you tried with the existing tools, and where it fell short.
+ validations:
+ required: true
+ - type: textarea
+ id: shape
+ attributes:
+ label: Proposed shape
+ description: Optional. Tool name(s), inputs, what comes back — and whether anything needs an approval gate.
+ placeholder: 'page_captureDownload(target) → { path, summary }; gated as confirm under a file-download rule'
+ - type: dropdown
+ id: surface
+ attributes:
+ label: Where it lives
+ options:
+ - A page tool (src/lib/actions)
+ - The extension UI (panel, popup)
+ - The daemon / MCP server
+ - Skills / agent behaviour
+ - Not sure
+ validations:
+ required: true
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
new file mode 100644
index 0000000..16a35cc
--- /dev/null
+++ b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,8 @@
+blank_issues_enabled: true
+contact_links:
+ - name: Security vulnerability
+ url: https://github.com/imshaikot/browsentic/security/advisories/new
+ about: Report privately. A public issue on a tool that holds live browser sessions puts every user at risk before a fix exists.
+ - name: Documentation
+ url: https://browsentic.com/docs/
+ about: Guides, the tool reference, and the internals — including troubleshooting.
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
new file mode 100644
index 0000000..fb93c64
--- /dev/null
+++ b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,10 @@
+## What and why
+
+<!-- One concern per PR. Link the issue if one exists; a capability PR should follow an agreed proposal. -->
+
+## Checklist
+
+- [ ] `yarn check` is green locally
+- [ ] Registry touched → `yarn daemon:manifest` run, and `docs/reference/tools.md` in step
+- [ ] Docs travel with the change
+- [ ] Commits follow the log's convention (`feat(actions): …`, `fix(daemon): …`)
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..5b31160
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,47 @@
+# The same gate CONTRIBUTING.md asks for locally, on every pull request — until now
+# `yarn check` only ran inside the release workflow, so a community PR could land red.
+#
+# Install mirrors release.yml: Yarn is vendored at the path .yarnrc.yml pins, so nothing
+# depends on whichever yarn the runner image ships, and src/daemon is a separate project
+# with its own lockfile that the root install does not cover.
+
+name: CI
+
+on:
+ pull_request:
+ push:
+ branches: [main]
+
+permissions:
+ contents: read
+
+concurrency:
+ group: ci-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ check:
+ runs-on: ubuntu-latest
+ steps:
+ - uses: actions/checkout@v5
+
+ - uses: actions/setup-node@v5
+ with:
+ node-version: 24
+
+ - name: Install dependencies
+ run: |
+ yarn_bin=$(sed -n 's/^yarnPath: *//p' .yarnrc.yml)
+ test -f "$yarn_bin" || { echo "::error::no vendored Yarn at '$yarn_bin'"; exit 1; }
+ echo "YARN=$yarn_bin" >> "$GITHUB_ENV"
+ node "$yarn_bin" install --immutable
+ node "$yarn_bin" --cwd src/daemon install --immutable
+
+ - name: Check
+ run: node "$YARN" check
+
+ - name: Build both bundles
+ # Type checks pass on code Vite still refuses to bundle; catch that here, not on a tag.
+ run: |
+ node "$YARN" build
+ node "$YARN" daemon:build
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
new file mode 100644
index 0000000..a3d8f85
--- /dev/null
+++ b/CODE_OF_CONDUCT.md
@@ -0,0 +1,131 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+ and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+ community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances
+ of any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+ without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+ professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official e-mail address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the maintainer at [email protected].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
new file mode 100644
index 0000000..2d5e54c
--- /dev/null
+++ b/CONTRIBUTING.md
@@ -0,0 +1,77 @@
+# Contributing to Browsentic
+
+Found a bug, or have an idea for a capability? Both are welcome. This page is the front door:
+what kinds of contribution land well, the one gate every pull request goes through, and where
+the deeper guides live.
+
+## Ways in
+
+| You have | Do this |
+| --- | --- |
+| A bug | [Open a bug report](https://github.com/imshaikot/browsentic/issues/new?template=bug_report.yml) with `browsentic status` output |
+| A capability idea | [Open a proposal](https://github.com/imshaikot/browsentic/issues/new?template=capability.yml) before writing code |
+| A security problem | **Not an issue.** [Report it privately](SECURITY.md) — this tool holds live browser sessions |
+| A docs fix | Edit under `docs/` and open a PR straight away — no issue needed |
+| A small code fix | A PR straight away is fine too |
+
+Proposals before code, for anything that adds surface: a capability ships as an MCP tool the
+moment it lands in the registry, so its name, shape and guardrails are API decisions worth two
+paragraphs of discussion before they are a diff.
+
+## Setup
+
+One command builds everything — both projects, both bundles — with nothing on your `PATH` but
+Node 20+:
+
+```sh
+yarn setup
+```
+
+Then `yarn dev` launches a throwaway Chrome profile with hot reload. The full build topology,
+the daemon's lifecycle, and every command live in the
+[internals contributing guide](docs/internals/contributing.md).
+
+## The gate
+
+```sh
+yarn check
+```
+
+That is both type checks plus the intent and security fixture suites — the same command CI runs
+on your pull request. Green locally means green in CI.
+
+If you touched the action registry, also run `yarn daemon:manifest` and keep
+[docs/reference/tools.md](docs/reference/tools.md) in step with what it prints. The manifest is
+generated from the registry, so the docs are the only place drift can hide.
+
+## Adding a capability
+
+The short version: one action module in `src/lib/actions/page/`, one line in
+[the registry](src/lib/actions/registry.ts), and the daemon publishes it as an MCP tool — the
+extension and the MCP server build from the same registry, so a tool can never describe
+something the browser cannot do. The long version, including the four conventions that are
+load-bearing at runtime, is in the
+[internals guide](docs/internals/contributing.md#adding-a-capability).
+
+Think about the guardrail while you are there: anything that commits something, sends data
+somewhere, or acts on another site's security control should carry a rule in the
+[policy](docs/guide/approvals.md), not a scattered check.
+
+## Pull requests
+
+- **One concern per PR.** A fix and a refactor are two PRs.
+- **Conventional commits**, subject line first: `feat(actions): …`, `fix(daemon): …`,
+ `docs: …`. Look at `git log --oneline` and match it.
+- **Docs travel with the change.** A new capability without its `docs/` page is half a PR.
+- CI runs `yarn check` and both builds on every PR. A red check is yours to fix, but ask if
+ the failure makes no sense — the fixtures have opinions.
+
+## Conduct
+
+Be the person you would want reviewing your first PR. The specifics are in the
+[code of conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+Browsentic is [MIT licensed](LICENSE). Contributions are accepted under the same terms:
+inbound = outbound, no CLA.