Thanks for your interest in Reticle! Reticle is the proof layer for AI agents — it verifies a running web app from the inside, without screenshots. It instruments the DOM, network, routing, console, and framework state in your app, and exposes that to an agent over MCP as a look → act → observe → assert loop.
This guide covers how to set up the repo, the rules we hold the line on, and how to land a change. We aim to make contributing pleasant — if anything here is unclear, ask in Discord or open an issue.
Looking for something to work on? good first issue is scoped, reviewed, and has a pointer to the file to start in. help wanted is bigger and unclaimed. Comment on the issue to claim it — we'll answer within a day, and nobody else will start on it once you have. For a first contribution with no code, good-first-skill issues ask for one SKILL.md that teaches an agent a verification recipe.
By participating you agree to our Code of Conduct.
-
Node.js
>=22.15(seeenginesin the rootpackage.json). -
pnpm
10.x— the repo pins[email protected]viapackageManager. The easiest way to get the right version is Corepack:corepack enable
This is a single git repo — a pnpm + turbo monorepo. Install everything from the root, and install the pre-commit hook while you are there:
pnpm install
pnpm hooks:install # symlinks pre-commit.sh — runs format → lint → types → tests on staged filesThe hook is optional and mirrors the fast gate, so it catches locally what CI would catch in ten minutes. It is not installed automatically; a repo that silently writes to your .git/hooks on install is a repo you cannot trust with a postinstall.
Before anything else, see the thing working: docs/first-drive.md takes you from git clone to a verdict on screen against a running app. A first ten minutes that ends with a passing unit test tells you the repo builds; it does not tell you what this project does.
Every item here cost somebody a debugging session. None is discoverable by reading the code.
- Port 4400 is the bridge, and your own daemon is probably on it. The e2e batteries use port
14400, so your daemon on4400can keep running. Neverkill -9the process that holds4400. That process can be thereticle mcpproxy, and killing it cuts your own agent's link with no log, because the process that writes the log is the one that dies. To free a port, usefreePortSafelyfromapps/e2e/gate-harness.mjs. It does not stop the proxy. - Telemetry fails silently. Nothing throws, no test reddens, the data is just permanently gone —
daemon_stoppedwas fired just beforeprocess.exit(0)for months and every POST died unseen. Readcontributing/telemetry/contract.mdfirst. - The fixtures are in a second repo. Every app in
apps/is already instrumented, so none of them can tell you whether a fresh install still works — re-runninginitover one reports "already wired" for every step and proves nothing. That question lives inreticle-fixtures, a maintainer repository that is not public yet. It keeps a pristinecleanbranch of real third-party apps, plusmainandreticle/<version>. Seedocs/fixtures.md. coreis the contract and does not get new dependencies. It depends only onzodandopen-verification. Anything that crosses browser, bridge and agent is a named constant plus a zod schema incore. A wire string written inline inbrowserorserveris a bug.- A new tool field needs several allowlists. Miss one and the call silently returns nothing — measured, twice. If you add a field and it "does not arrive", start by grepping for every place the existing fields are listed.
pnpm lintdoes not runformat:check. Runpnpm verifyas one command: it runsformat:check,lint,typecheckandtest:unitin order. If you run the parts on separate lines, only the last one sets the exit code.- A local gate is only trustworthy in a quiet checkout. If something else is editing the same worktree, turbo will read files mid-write and report failures that are not yours.
- Three minutes, highest value: submit an MCP-client compatibility record. Most rows in
docs/matrix/MATRIX.mdare◐— meaninginitwrites a runnable entry and nobody has ever run that client. Seedocs/matrix/README.md. - An afternoon:
good first issue— scoped, reviewed, with a pointer to the file to start in. - Found a bug in Reticle while using it?
reticle feedback --agent --kind bug "what happened"files it from the shell, no GitHub account needed.
The layout, the package boundaries, the coding rules, the names and the gate to run for each change are in AGENTS.md. Your coding agent reads the same file, so you and your agent follow one set of rules. Read it before your first change.
Every change runs pnpm verify. Some changes need one more gate: the table in AGENTS.md names it, and docs/gates.md explains each gate. CI also routes by path, and gate counts a skipped job as green. When you are not sure, run the gate.
pnpm bench is the benchmark harness. It is research, not a gate (see bench/README.md).
gate plus dco. The merge queue runs bench and the full Windows install matrix before a change lands. A job that runs after merge but not in the queue needs an entry in .github/flaky.json, and it leaves that file after three consecutive green nightlies on main.
apps/bench-app is the React dashboard we use to dogfood Reticle (tabs, lists, modals, forms, API calls).
pnpm install # once, from the repo root
pnpm --filter @reticlehq/bench-app dev # http://localhost:4312From there, point your MCP-capable agent at Reticle and ask it to verify the app — see docs/getting-started.md for the full walkthrough.
The rules are in AGENTS.md. This section tells you how to fix the two problems that most often stop a PR.
A commit has no sign-off. CI's Developer Certificate of Origin check needs a Signed-off-by: line on every commit. Use git commit -s. To fix commits that you already made:
git commit --amend --no-edit -s # one commit
git rebase --signoff origin/main # several commits
git push --force-with-leasegit config format.signOff true does not apply to git commit. To add the line automatically, run pnpm hooks:install. It installs a prepare-commit-msg hook that adds the line, and the pre-commit gate.
The PR is blocked, every check is green, and no reason is given. Your branch has a merge commit. The merge queue replays your branch on top of main, and it cannot replay a merge commit. Rebase instead of merging: git rebase --signoff origin/main, then push with --force-with-lease.
For a large change, open an issue first, so that we can agree on the approach before you write the code.
- A reply to a claim or a question within a day, and a first review within two days. If a PR has waited longer, say so on it; that is on us, not you.
- CI on a pull request takes about ten minutes. The slowest suites (the benchmark and the full Windows install matrix) run in the merge queue, not on the PR, so a PR you can act on is not held up by a job you cannot. Windows unit tests run on a PR when Windows-sensitive source changed.
- Once it is approved, the merge queue lands it. You do not need to keep rebasing while it waits.
Welcome, on one condition: the tests must fail without your change. Revert your fix locally and run the test you added; if it still passes, it is not testing the fix, and a green test that proves nothing is the one defect this project exists to catch. Say in the PR description that you checked. PRs that only reformat, rename or reword without an issue behind them will be closed.
Reticle uses Apache-2.0 for every npm package, and MIT for the reticle-tauri crate. By contributing, you agree that your contribution is licensed under the license of the package(s) you're modifying. See the root LICENSE and each package's own LICENSE file.