RepoDNA

Turn repository history into evidence-linked AGENTS.md guidance and Codex Skills—reviewable, exportable, and ready to validate before promotion.

Comment

Inspiration

Coding agents can read the files that exist today, but mature repositories also depend on decisions accumulated over time: package-manager conventions, error contracts, testing patterns, logging boundaries, and release constraints. Those decisions are often scattered across documentation, workflows, source code, and commit history.

RepoDNA started from a simple question: how can a coding agent learn a repository’s working conventions without asking maintainers to trust an opaque generated instruction file?

The answer became an evidence-and-verification layer for agent context. Instead of producing unsupported recommendations, RepoDNA turns bounded repository evidence into a reviewable Pack where each rule is linked to collected source evidence.

What it does

RepoDNA produces a portable RepoDNA Pack containing:

  • concise AGENTS.md guidance;
  • a native Codex Skill;
  • source-linked evidence;
  • a rule-to-evidence mapping validator; and
  • a manifest describing the Pack and its safety properties.

The public demo presents a checked-in, reproducible hidden-contract fixture. Visitors can inspect its evidence, compare the deterministic promotion results, and download the Pack without providing credentials or triggering hosted model calls.

For real repository analysis, developers can clone and self-host RepoDNA, explicitly enable live analysis, and use their own server-side API key.

How we built it

RepoDNA is built with TypeScript, React, Next.js, vinext, a Cloudflare Worker-compatible server runtime, the GitHub REST API, and fflate for ZIP export.

The system is deliberately bounded:

  1. It accepts only canonical public GitHub repository URLs.
  2. It collects read-only evidence from metadata, selected files, workflows, and recent commits.
  3. It treats repository text and commit messages as untrusted data.
  4. In explicitly enabled self-hosted mode, GPT-5.6 converts bounded evidence into structured candidate rules.
  5. RepoDNA rejects rules that do not cite evidence IDs it actually collected.
  6. It exports a Pack whose internal rule-to-evidence mapping can be validated without executing target repository code.

The public deployment intentionally disables /api/analyze before any GitHub or OpenAI request can run. This creates a clear cost and security boundary: judges can explore the full product experience and export a Pack without consuming an API budget.

How Codex and GPT-5.6 were used

Codex was the primary development environment for this project. It accelerated research, product reframing, implementation, UI iteration, API-boundary design, Pack generation, test construction, security review, deployment preparation, and submission documentation.

GPT-5.6 is used meaningfully in RepoDNA’s optional self-hosted structured-analysis path. It receives bounded public-repository evidence under an explicit untrusted-data boundary, with strict structured output and no model tools. Its output is not trusted automatically: every candidate rule must cite evidence collected by RepoDNA before it can be exported.

The public demo does not make GPT-5.6 calls. That is intentional: it demonstrates the evidence model, validation flow, export format, and deterministic evaluation without requiring visitors to pay for or supply credentials.

Challenges

The main challenge was balancing useful agent context with trustworthy provenance.

Repository files and commit messages can contain hostile or misleading text, so RepoDNA had to treat them as evidence rather than instructions. The design therefore uses strict URL validation, bounded upstream responses, read-only collection, no target-code execution, evidence-ID validation, and a fixed export layout.

Another challenge was avoiding misleading benchmark claims. The hidden-contract evaluation is a reproducible synthetic fixture, not a claim of universal model improvement. It compares bare context, generic initialization, unverified context, and a verified RepoDNA Pack on the same checked-in task.

What we learned

The valuable part of repository context is not merely generating more instructions. It is preserving why a rule exists, making the rule reviewable, and validating it before promotion.

We also learned that a public developer-tool demo should be safe to inspect. RepoDNA therefore separates a no-cost reproducible public experience from optional self-hosted live analysis.

What’s next

Next steps include authenticated private-repository support with explicit consent, provenance-aware pull-request and CI-history analysis, rule aging and maintainer approval workflows, and repeated temporal-holdout Codex trials on real repositories.

Try it

Built With

Share this project:

Updates