Greenlight

Greenlight

Greenlight is the pre-flight and coordination layer for open-source contribution: the software that stands between an outside contributor (increasingly an AI agent) and the maintainers of a public repo, and answers the questions no other tool answers. Can I contribute here at all? Is this issue secretly taken? What are the house rules? Who else is racing me? And for maintainers: who is flooding my queue, and what is safe to merge?

Quickstart

npx @reneturcios/greenlight check <issue-url>

Why this layer exists

Follow the venture money and you will see where it is not going. Cognition (Devin) raised about $2B at a $48B valuation, and Factory raised $200M at a $5B valuation, to run autonomous coding agents *inside* enterprises' own repos. CodeRabbit raised $88M (valued near $550M), Graphite raised a $52M Series B before being acquired by Cursor, and Greptile raised a $25M Series A, all reviewing a team's *own* pull requests. OpenHands is an agent runtime. Every funded player assumes you are inside the org.

Nobody owns the boundary. No VC-backed tool answers the outside contributor's questions: can I contribute here, is this issue secretly taken, what are this repo's gates and AI policies, who else is racing me. And no VC-backed tool answers the maintainer's questions: which of these 30 open PRs are duplicates, who is claiming what, which claims have gone stale, which agent-written PRs are safe to merge. Greenlight is that layer, built from running real contribution campaigns through it every week.

The problem

AI made code cheap. Contribution coordination is now the bottleneck, and it breaks in specific, repeatable ways:

• Hidden competition. Issue list views lie. In a hand-vetted focus session on usebruno/bruno, 6 of 7 promising issues were secretly taken by PRs visible only in the issues' timelines, not in the list view or search results. You can spend a weekend on work that was already done.
• Gates and bans. Greenlight's own Agent Policy Index now tracks 505 repos: 127 of them (25%) carry contribution gates, and 19 ban agent contributions outright. Whole repos (nuxt, uv, Gradio, Activepieces) have closed their doors to outside PRs entirely. Nobody told you; it was in AGENTS.md.
• Duplicate AI PRs. When several contributors (human or agent) race the same issue, maintainers get three overlapping PRs and no way to arbitrate. GitHub has no claim system, only comments.
• House rules everywhere. CLAs, DCO sign-off, changesets, commit formats, assignment requests. Every repo invents its own, hides them in different files, and rejects your PR on the technicality.

These are coordination problems, not coding problems. The code agents keep getting better; the boundary keeps getting messier. Greenlight works the boundary.

What Greenlight does

Three layers, from decide to solve to coordinate:

• Decide. check reads an issue, its comments, linked and mentioned PRs (timeline plus search plus comment references), and the repo's rules, then answers in plain words: GO, RISKY, TAKEN, GATED, or STALE. scan ranks a repo's open issues so you pick a winnable one first. friction scores a repo 0 to 100 on how hard it really is to get a PR merged, with every gate quoting the file its evidence came from. xray (Timeline X-Ray) deep-verifies candidates against their issue timelines before you write a line, catching hidden in-flight PRs including reporter-owned fix PRs; scan --deep demotes anything taken before it shows you the list. racecheck (Keyword Race Check) catches the race X-Ray cannot see: an open PR fixing the same problem that never links the issue, found by the issue's problem keywords (filenames, identifiers, distinctive terms) instead of links, with RACE / SUSPECT / CLEAR verdicts and quoted keyword evidence; scan --deep and xray consult it automatically. The v0.20.1 precision pass keeps it honest on real repos: GitHub label names, URL path segments, and repo template boilerplate (via document-frequency suppression over the scanned PR queue) never count as evidence, RACE-by-terms requires title-derived terms, and a shared changed file needs a distinctive co-hit, so adjacency reads SUSPECT, not RACE. wave turns the Agent Policy Index into a build queue in one command: winnable open repos, x-rayed starter issues, behavioral gates excluded.
• Solve. ci-prep runs a repo's own pull-request checks locally before you push (tests, lint, typecheck, plus conventions like changesets, commit format, DCO), so avoidable CI failures never appear in front of a maintainer. ci triages red PRs into pre-existing vs likely-yours vs external-blocker against base-branch history. review classifies every review thread as likely-real, likely-noise, or needs-decision and drafts your replies. verify reports the honest red-green test delta of your change. autopilot verifies bot findings against the code at head and fixes the mechanical items (DCO surgery, conflict re-merges, formatting) itself. brief assembles a verified one-screen brief for any PR: change shape by area and risk, CI triaged against base-branch history, findings classified real vs false-positive with evidence, test evidence present or explicitly marked absent, merge blockers, and a one-line look-at-this-first. babysit watches your open PRs and reports one prioritized action list.
• Coordinate. claim posts a protocol claim (expiring lease, public queue, heartbeats; full spec in protocol/SPEC.md), with a hosted app client option via --via-api. guard analyzes an incoming PR for a maintainer: competing fix, prior claims, missing artifacts, first-time contributor. digest reports a repo's PR races, claimed-by-other conflicts, stale claims, and assignment-gate conflicts. radar scans the whole open-PR queue and clusters competing or duplicate PRs with evidence per cluster and a suggested keep, labeled a heuristic, never a verdict. passport renders a contributor's merged work plus claim record.

Every verdict and every report cites its evidence: the quoted policy line, the claim comment URL, the PR number, the failing check. Nothing is asserted without a source.

Who it is for

• Contributors (human). Run check before you spend an evening on an issue. Run scan when you are picking what to work on. Run ci-prep before you push.
• AI agents and coding tools. One command (init --agent claude-code, also cursor, copilot, windsurf, cline) installs the MCP config plus the one behavior rule: check Greenlight before opening a PR. Agents waste the most tokens fixing already-taken issues; 33 MCP tools make the whole engine available mid-run.
• Maintainers. guard on each incoming PR, radar across the whole open queue, digest for the weekly triage, and the roadmap below for the control room: stale-claim sweeps, policy enforcement, AI-PR filtering.

Proof, stated plainly

• 1268 tests, all passing, including a fixture corpus pinned to real campaign cases (a taken issue, a weak PR mention, claim-first gates, scoped claims, half-shipped issues, stale claims, paused-PR workflows).
• Dogfooded on real campaigns: the toolkit has authored 80+ pull requests across dozens of public open-source repos. Every feature exists because a real contribution died without it.
• Distributed everywhere the audience already looks: npm (@reneturcios/greenlight), the MCP Registry, and GHCR (ghcr.io/cloudcorprecords/greenlight), plus Docker and direct MCP stdio.
• Two living datasets ship with it: the Contribution Friction Index (data/friction-index.json) and the Agent Policy Index (505 repos, 127 gated, 19 agent bans, published at docs/policy.html), both built from real campaign field work, not scraped guesses.

Watch it work

*The 59-second demo: real issue checks on real repos, an AI-caught hidden claim, a GATED agent ban, campaign scouting, and the claims babysitter. Full narrated video.*

Install

npx @reneturcios/greenlight check <issue-url>

Set up your AI coding tool and verify the setup:

npx @reneturcios/greenlight init --agent claude-code   # one-command MCP setup (cursor, copilot, windsurf, cline work too)

npx @reneturcios/greenlight doctor # checks Node version, token, GitHub quota, cache

Or from source:

npm install

npm run build

Set GITHUB_TOKEN (a classic personal access token, no scopes needed for public repos) to raise the GitHub API rate limit from 60 to 5000 requests per hour. Greenlight caches API responses under ~/.cache/greenlight.

Run the MCP server with npx @reneturcios/greenlight mcp (stdio), or point your agent at the greenlight command with the single argument mcp.

Run it with Docker

Greenlight also ships as a container image on GHCR: ghcr.io/cloudcorprecords/greenlight.

Use it as a stdio MCP server:

docker run -i ghcr.io/cloudcorprecords/greenlight

Any CLI command can be passed after the image name instead of the default mcp argument:

docker run ghcr.io/cloudcorprecords/greenlight check <issue-url>

docker run ghcr.io/cloudcorprecords/greenlight --version

Use it inside your AI coding tool

One command sets it up:

npx @reneturcios/greenlight init --agent claude-code

(also cursor, copilot, windsurf, cline; repeat --agent for more than one). Init copies the MCP config into your project and installs the workflow instruction snippet that teaches your agent the one behavior rule: check Greenlight before it opens a PR. Prefer doing it by hand? The integrations/ drop-in pack has ready-to-copy MCP configs plus the same snippets. Then verify with a "list your MCP tools" prompt; the greenlight server carries 33 tools (see the list below).

CLI

# One-command setup for your AI coding tool (cursor, copilot, windsurf, cline work too)

npx @reneturcios/greenlight init --agent claude-code

Verify the setup: Node version, token, GitHub quota, cache (exit 1 when anything fails)

npx @reneturcios/greenlight doctor

Help: overview, one command's flags, or the version

npx @reneturcios/greenlight help check npx @reneturcios/greenlight --version

Verdict for one issue

npx @reneturcios/greenlight check https://github.com/batrapulkit/squidbrake/issues/74

[GO] batrapulkit/squidbrake#74

Taint: tell the approver when an agent edits its own setup right after reading outside content

- open, unassigned, no linked PRs, no claim signals, no blocking gates

Rank a repo's starter issues, GO first (falls back to recent open

unassigned issues when the repo does not use those labels; --no-fallback to opt out)

npx @reneturcios/greenlight scan PrefectHQ/fastmcp

Deep-verify candidates against their timelines first (catches hidden in-flight PRs)

npx @reneturcios/greenlight xray usebruno/bruno --issues 8149,9319 npx @reneturcios/greenlight scan