Thanks for taking the time to contribute. This document covers the setup, the checks a change has to pass, and the conventions the repository follows.
WebOperator is a Chrome extension plus a Node-based MCP bridge. The npm project
lives in core/, not in the repository root.
git clone https://github.com/KazKozDev/WebOperator.git
cd WebOperator
nvm use # reads .nvmrc — Node 24
npm --prefix core ci
npm --prefix core run buildThe build writes the unpacked extension to core/dist. Load it through
chrome://extensions with Developer mode enabled.
For iterative work use the watch build:
npm --prefix core run devshellcheck is the one dependency npm does not install. Ubuntu ships it;
on macOS use brew install shellcheck. It is only needed for the full gate.
Every pull request must pass the same gate CI runs:
./scripts/check.shIt runs eight steps in order — fixture evals, bridge smoke test, typecheck,
ESLint, unit tests, the Knip dead-code and dependency scan, ShellCheck, and the
production build. Run it locally before opening a PR; CI runs it on both
ubuntu-latest and macos-latest, so a change that passes only on one platform
will be caught but is cheaper to find at home.
Individual steps are available as npm scripts in core/package.json
(typecheck, lint, test, deadcode, shellcheck, build). Coverage is
reported by npm --prefix core run test:coverage.
Unit tests live next to the code they cover as *.test.ts and run under Vitest.
A change to agent behaviour belongs with a test — the loop guard, the verifier,
the tool validator and the page-state readers all have existing suites to
extend rather than duplicate.
Browser-level evals are separate and not part of the gate, because they need a model backend. See docs/evals.md and the runner notes in docs/release-checklist.md.
The history follows Conventional Commits:
feat(captcha): add autonomous solver for slider puzzles
fix: read page state from the main frame
docs(readme): warn about the debugger bar in Permissions
chore: pin the Node version
Use feat, fix, docs, chore, ci, style, refactor, test or
perf. The scope is optional. These prefixes drive the CHANGELOG, so a
descriptive subject line is worth the extra seconds.
- Branch from
main. - Keep one concern per PR. A refactor bundled with a behaviour change is hard to review and harder to revert.
- Fill in the PR template — what changed, why, and how it was verified.
- A green
checkrun on both platforms is required before merge.
Some parts of the codebase carry more risk than their size suggests. Changes there get closer review:
- Prompt-injection boundary. Page content is untrusted data and must never
reach the model as instructions. See
core/src/lib/prompts.tsand the injection fixtures inevals/fixtures. - The bridge.
weboperator-bridge/accepts external calls and defaults to unauthenticated. Anything touching its parsing, binding or auth path needs a test. - Credential handling. The vault and masking code paths must not widen what is written to traces or logs.
Do not open a public issue for a vulnerability — see SECURITY.md.
README.md holds the short version; the detail lives in docs/. A change that
alters behaviour, a permission, a default or an environment variable should
update both. docs/known-limitations.md is the honest list — adding to it is a
contribution, not an admission.
Releases are cut by pushing a v* tag; the release workflow rebuilds from
that commit, runs the gate, and publishes the extension archive with notes
taken from CHANGELOG.md. Add user-visible changes under Unreleased as you
go — that section becomes the release notes, so writing it later means writing
it from memory. The full procedure is in
docs/release-checklist.md.
Participation is governed by the Code of Conduct.