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.

4.2 KB
Raw Blame

Contributing to Browsentic

Bug reports, capability ideas and pull requests are welcome. This page covers where each kind of contribution goes, the one check every pull request must pass, and where the deeper guides live.

Ways in

You have Do this
A bug Open a bug report with browsentic status output
A capability idea Open a proposal before writing code
A security problem Not an issue. Report it privately: Browsentic 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

Propose before you code anything that adds surface. A capability becomes a page tool, for the side panel's agent and for MCP clients alike, the moment it lands in the registry, so its name, shape and guardrails are API decisions worth two paragraphs of discussion before they become a diff.

Setup

One command builds everything (both projects, both bundles) with nothing on your PATH but Node 20+:

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.

The required check

yarn check

It runs both type checks and the test suite with its coverage floors. CI runs the same command on your pull request, so green locally means green in CI.

If you touched the action registry, also run yarn daemon:manifest and keep 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.

Tests

A test sits next to the module it tests, as <module>.test.ts, and runs with Vitest:

yarn test                          # everything
yarn test src/daemon/guardrails    # one directory or file
yarn coverage                      # everything, then coverage by area against its floors

Where a test lives decides what it runs in:

Where Runs in
src/lib/** Node, with WXT's fake browser
src/lib/actions/page/** happy-dom
src/daemon/** Node, with HOME and the daemon's state in a throwaway directory and ports the OS picks
src/daemon/test/** The same sandbox, for tests that start a real daemon

Never put a test under src/extension/entrypoints/, because WXT builds every file there as an entrypoint. The floors in vitest.coverage.ts only ever go up: raise one when your tests lift an area, and never lower one to get a build through.

Adding a capability

The short version: one action module in src/lib/actions/page/, one line in the registry, and the daemon publishes it as a page tool over MCP. 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.

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, 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.

Conduct

Be the person you would want reviewing your first PR. The specifics are in the code of conduct.

License

Browsentic is licensed under the Apache License 2.0. Contributions are accepted under the same terms: inbound = outbound, no CLA.