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.
TypeScript agentic-browseragentic-browsingagy-cliaiai-agentai-browser-extensionai-toolsbrave-extensionbrowser-agentbrowser-automationbrowser-extensionbrowser-usebrowserskillchrome-extensionclaude-codecodexfirefox-addonmcp-servernanobrowserweb-automation
docs: open the door to community contributions
Shahriar196cd16ee0de
diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlnew file mode 100644index 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: textdiff --git a/.github/ISSUE_TEMPLATE/capability.yml b/.github/ISSUE_TEMPLATE/capability.ymlnew file mode 100644index 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: truediff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.ymlnew file mode 100644index 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.mdnew file mode 100644index 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.ymlnew file mode 100644index 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:builddiff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.mdnew file mode 100644index 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/translationsdiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdnew file mode 100644index 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.