NextBranch

NextBranch: see the product inside any codebase, then explore where it could go next.

Comment

Inspiration

As a developer there are many times when I open an unfamiliar repository and am unsure of the many files and what they do. Being able to map out in my head on where code is and what it does. I try to use File trees to help me find where certain things are, but they don't show what the product does or which parts actually matter. AI coding tools wait for to already know what to ask.

I wanted to solve this gap, and to do it honestly between "what is this codebase?", "what should I change next, and which direction is actually better?", giving the user proven information and evidence to fill that gap.

What it does

You paste a public GitHub URL. NextBranch safely ingests it (excluding dependencies, generated output, secrets, and binaries with a machine-readable reason for every exclusion), then projects it into runnable products -> product areas -> ProductSurfaces - the meaningful units a person would actually want to change. Each surface gets a deterministic 0-100 opportunity score per lens ("make faster", "improve reliability", "improve accessibility"…), so a large repo collapses to the eight things that matter instead of hundreds of files.

Pick a surface/node and NextBranch then compiles it into a reviewable "experiment specification", a settings file to create boundaries, constrains, evidence plan and a token/cost estimate before any model runs. This gives developers an honest window on what this generation might cost them to do, and creates 2 - 3 different variants, checks every patch against the boundary with non-executing checks and then show them side-by-side. For a static web surface, a live before/after render in a sandboxed iframe, and for everything else it shows a behaviour graph and API-contract comparison.

How I built it

A pnpm/TypeScript monorepo: a Next.js frontend, a Fastify API, and independent worker processes for ingestion and generation, all sharing typed Zod contracts and an embedded SQLite store.

The intelligence layer is deterministic first. Ranking blends git-history activity, graph centrality, and complexity. Crucially, I weight each commit's churn contribution by

$$w_c = \frac{1}{\sqrt{n_c}}$$

where $n_c$ is the number of files touched in commit $c$ - so a 200-file "v0" bulk commit barely moves any single file's score, while a focused 3-file fix counts. A surface's importance is a clamped composite:

$$ S = \min!\left(100,\; \underbrace{R}_{\text{readiness}}

  • \underbrace{\alpha \sum_{c} w_c}_{\text{activity}}
  • \underbrace{\beta\left(f_{\text{in}} + \tfrac{1}{2} f_{\text{out}}\right)}_{\text{centrality}}
  • \underbrace{\gamma\,\frac{L}{55}}_{\text{complexity}} \right) $$

Only then does an LLM enrich the top surfaces - improving names, plain-language summaries, and search synonyms - through the OpenAI API with Structured Outputs, strictly bounded, cached by commit + analyzer + prompt version, and never permitted to alter a file, edge, or score. Generation re-clones the exact commit into a hardened, network-restricted Git sandbox and returns complete path-scoped patches that are validated but never executed.

What I learned

That honesty is a feature, not a limitation. The hardest engineering wasn't calling a model - it was refusing to let the model become the source of truth. Keeping four decisions independent (can we read this? is it meaningful? could a variant be evaluated? is there real evidence of a problem?) is what makes the output trustworthy. I also learned how much signal is sitting unused in git log, and that the difference between "impressive demo on a toy repo" and "works on a messy 14,000-file group project" is almost entirely dependency resolution and honest ranking.

Challenges I faced

  • Ranking that survives real repos. Early versions gave every surface an identical score on solo-dev repos with commit-everything habits; the $1/\sqrt{n_c}$ weighting fixed it.
  • Logic for ranking surfaces by a particular category, "how can i determine a surfaces importance according to the chosen lens category without AI assistance?"
  • Visualizing a variant without running it. Rendering a real website means executing a build, which breaks the no-execution safety model. The breakthrough was realizing every variant already stores its full file content, so a static surface can be assembled and served as inert files into a sandboxed, network-blocked iframe — a real render with zero host execution — while framework/backend surfaces get an execution-free behavior-and-contract diff instead.

Built With

Share this project:

Updates