Launching LemonBeam: Onboarding Guides for GitHub Repos That You Can Verify

Today we're launching LemonBeam, an open-source tool that scans a public GitHub repository and generates an onboarding guide where every claim cites the exact file and lines it came from.

🍋Try it: lemonbeam.app

The problem

Getting started in an unfamiliar codebase means piecing together what it does, how to run it, and how the tests work from READMEs, package scripts, config files, and source code.

The obvious shortcut is asking ChatGPT. The answers are often useful, but when we checked the citations, they were fabricated, pointed hundreds or even thousands of lines away, or were missing entirely. A right answer you can't check is still a guess.

How LemonBeam is different

Rules, not AI, decide which evidence the model sees. LemonBeam downloads the repo at an exact commit, then filters, parses, and chunks the code with Tree-sitter and scores each chunk within a per-section token budget. One AI call writes the guide from that evidence only.

Every citation is checked. A separate validator removes any citation that doesn't match the evidence the model actually received.

Gaps are visible. Anything that couldn't be read or included is listed in an Uncertainties section instead of being hidden.

Every guide has the same six sections: Project Overview, Setup/Installation, Running Locally, Project Structure, Testing, and Uncertainties and Missing Information. Each guide is pinned to the commit it analyzed, so everyone on a team can generate the same guide and check it line by line.

Three ways to use it

• 🌐 Website: Paste a public GitHub URL and your OpenRouter API key at lemonbeam.app.
• 💻 CLI: Run lemonbeam in a local folder or against a public GitHub URL, and save the guide as Markdown.
• 🔌 MCP server: Add LemonBeam to Claude Code, Codex, or another AI tool, and ask your assistant for an onboarding guide.

Setup instructions for the CLI and MCP server are on the website.

Your code isn't stored

LemonBeam has no database. Downloaded repos live in a temporary folder that's deleted when the scan ends, even if it fails. Your API key exists only in memory for that one request. The only code that leaves your machine is the evidence sent to the model through OpenRouter.

The hardest bug

Our pre-MVP pipeline was quietly sending every chunk to the model, which made guides expensive and limited us to a fraction of our target repo size. Fixing it cut the cost per guide from about 70¢ to 2¢ and took our supported repo size from 2 MB to 50 MB. I wrote about the full story here: From 2 MB to 50 MB: The Bug That Almost Killed Our MVP

What's next

• Separate, parallel AI calls with tuned prompts for each section
• Citation checking that verifies the cited lines actually support the claim
• Support for larger repos, monorepos, private repos, and languages beyond JavaScript and TypeScript
• A comparison of embeddings-based retrieval against our rule-based approach

Contribute

LemonBeam is open source under the MIT License. The best way to get started? Use LemonBeam on LemonBeam! Paste github.com/oslabs-beta/lemonbeam into lemonbeam.app to get a cited guide to our own codebase, then check out the contributing guide in the repo.

Built by Kanami Anderson, John DeLong, and Tanisha Thompson-Jones.

Comments

[Launch Gate]

Citations that are actually checked is the right thing to focus on. One evidence source worth weighting high for the Running Locally and Testing sections: the CI workflow files (.github/workflows/*.yml). READMEs drift, but the install and test commands in CI are the ones that ran green on the last commit. When the README says npm test and CI runs pnpm test --filter core after a docker compose up -d db, that mismatch is exactly what a new contributor trips on, and it would be a great thing to put in the Uncertainties section.

[Kanamija]

Thanks, this is a great suggestion. I'm going to look at weighting .github/workflows/*.yml higher for Running Locally and Testing, and surfacing mismatches in Uncertainties.

Your example is also a good nudge on scope. pnpm test --filter core is a monorepo pattern, and LemonBeam currently targets single-package JS/TS repos, so that kind of mismatch would also be a useful signal that a repo is outside what the guide can fully cover.

If you have a repo in mind where the README and CI have drifted, I'd love to run it as a test case.

[Launch Gate]

Thanks for clarifying the single-package scope. My pnpm --filter example was hypothetical, not a repo I'd inspected, so I don't want to pass off a made-up drift case as a test fixture. I don't have a verified public repo with that mismatch in mind right now. For the narrower case, I'd test a single-package repo where package.json has a test script but CI adds a required service or env var before invoking it, and show both cited sources rather than picking one command as authoritative.

[Kanamija]

Thanks for flagging that. A single-package repo where CI adds a service or env var before the test script is a great case, and I'll find a real one to use as a fixture. Showing both sources fits how Uncertainties is meant to work.

Where would you draw the line? When CI and the README disagree, should the guide lean toward CI, or stay neutral and let the contributor decide?

[Launch Gate]

I would not present them as equally authoritative for "how the current tests run." CI is executable evidence of what the repository actually does on that workflow and commit, so I would lead with its command and required setup, citing the job/step. But it is not proof that the same setup works locally or that the README is obsolete. Put the README's different instruction next to it as an explicit conflict, then say what remains unverified (for example, whether the service is only needed in CI). If LemonBeam can run a safe local check, that observation can narrow the uncertainty; otherwise the contributor should choose rather than the guide silently rewriting one source as fact.

[wolf Valencia]

Congrats on LemonBeam. The "evidence before the model writes" constraint is a great rule for onboarding guides.

While poking at the marketing site with an automated QA pass (Staff SDET habit), the page title stood out: it's just "LemonBeam" (9 characters), so search results and link unfurls don't carry the launch story at all. A title like "LemonBeam — verifiable onboarding guides for GitHub repos" is a one-line fix. Report card 95/100 (A), plus 12 additional findings.

Curious how you handle a source that changes after a guide has already cited it.