RepoLens

Inspiration

Research code can be public and still be difficult to learn. Important behavior is distributed across sparse documentation, configuration, implementation modules, scripts, notebooks, and tests. RepoLens is designed around one principle: the repository revision, not a generated explanation, is the final authority.

What it does

RepoLens accepts a public GitHub repository and fixes the exact commit revision before analysis. The resulting research workspace includes:

• an evidence-linked architecture brief and mechanism map
• a staged path for understanding, reproducing, or extending the project
• source windows with file paths, line ranges, and immutable links
• a reproduction plan whose displayed commands must appear in cited evidence
• explicit prerequisites, safety guidance, and unverified-work boundaries
• repository-specific questions that return the learner to source evidence
• Markdown export that preserves the revision and citations

An optional read-only Agent performs bounded evidence exploration. It can select additional files only from a server-approved candidate list, runs for at most two rounds, and cannot execute code or modify a repository.

How I built it

RepoLens uses Next.js and TypeScript for the research workspace, GitHub REST and raw-content endpoints for immutable repository evidence, and Cloudflare Workers for public deployment. The server ranks research-relevant files, extracts bounded source windows, discovers symbols and conservative cross-file relationships, and assigns stable E-series evidence identifiers.

The deterministic evidence engine provides the complete core workflow without a model key. With DeepSeek configured, JSON-Schema-constrained analysis organizes mechanisms, research paths, reproduction tasks, and verification questions. The server validates model-requested paths, evidence identifiers, immutable links, and displayed commands. Repository text is isolated as untrusted data, and API-side model conversation storage is disabled.

Evaluation

On a fixed three-repository evaluation, RepoLens exact-path key-file coverage is:

• nanoGPT: 100.0%
• Whisper: 71.4%
• Segment Anything: 50.0%
• mean: 73.8%

The README-only baseline mean is 35.1%. Fixed-scope evaluations on mlx-examples/lora and pytorch/examples/mnist both reach 100.0%.

A paired four-repository evaluation measures bounded Agent exploration: mean exact-path coverage is 30.5% in standard mode and 63.7% with Agent exploration, with zero invalid evidence identifiers. A field-level evidence-support evaluation covers 73 report fields: 67 are fully supported, 6 partially supported, and none unsupported or unverifiable. All 15 displayed reproduction commands in the sample appear verbatim in cited evidence.

These measurements evaluate retrieval coverage, evidence support, and planning quality. They do not claim that third-party experiments were executed successfully.

Challenges

The core design problem is preventing a fluent explanation from outrunning its source. Repository trees are large, setup commands can appear deep inside documentation, and common function names can create ambiguous cross-file links. RepoLens therefore uses immutable revisions, bounded evidence windows, conservative relationship matching, field-level citations, exact command checks, and explicit uncertainty.

What I learned

Trustworthy educational AI needs more than citations attached to prose. Retrieval scope, immutable revisions, server-issued evidence, validation rules, and uncertainty language have to be designed as one system. The model can organize an explanation, while the application retains authority over what counts as evidence.

What's next

• Broader evaluation across notebook-heavy and multi-project research repositories
• Collaborative evidence annotations for research teams
• Revision comparison without silent evidence drift
• Optional sandboxed execution with explicit human approval

Built With

• cloudflare-workers
• deepseek
• github-api
• json
• next.js
• node.js
• rest
• typescript