FirstPR

Paste a repo + your skills. FirstPR maps the codebase in plain English and ranks real open issues by fit — your fastest path to a first PR.

Inspiration

Every year, thousands of students want to contribute to open source — for GSoC, for their resume, or just to learn — and most of them quit before their first pull request. Not because they lack the skill, but because an unfamiliar codebase is overwhelming: you don't know which directory does what, which issues are actually approachable, or where to even start reading. As a student prepping for GSoC myself, that exact wall was the direct inspiration — I wanted the tool I wished existed the first time I opened an unfamiliar repo and didn't know where to look.

What it does

FirstPR takes a public GitHub repository and a short description of your skills and experience level, then:

• Maps the codebase in plain language — a clear breakdown of the main modules and what each one is actually responsible for, written for a newcomer rather than a maintainer
• Ranks real open issues by fit — pulls actual good first issue / help wanted issues from the repo and ranks the ones best suited to your skills
• Explains why, concretely — for each recommendation, it names the exact module you'd touch, roughly how much code is involved, and what you'd learn, before closing with a short earned encouragement — not generic cheerleading

Every recommendation is grounded in the repo's real file tree, README, and actual open issues — nothing is invented.

How we built it

FirstPR is a Next.js app (frontend + API routes in one) deployed on Vercel. On submission, it fetches the repo's file tree, README, CONTRIBUTING.md, and open good first issue / help wanted issues via the GitHub API. That data feeds two focused GPT-5.6 calls rather than one large prompt:

1. Architecture call — takes the file tree, README, and language breakdown, and produces a structured, plain-language summary of the codebase's main modules
2. Issue ranking call — takes that architecture summary plus the real open issues and the user's stated skills, and returns the top 3–4 issues ranked by fit, each with structured reasoning

Both calls return strict JSON, using json-schema-constrained structured outputs, so the UI renders reliably instead of parsing free-form text.

I used Codex CLI throughout the build in an interactive, conversational loop rather than one-shot generation — planning the architecture in chat first, then handing Codex a structured build brief covering the tech stack, both LLM call specs (including the exact JSON schemas and tone rules for issue reasoning), and an hour-by-hour build order. Codex scaffolded the Next.js app, built the GitHub ingestion layer, wired up the two-call analysis pipeline, and iterated through several real bugs I caught in testing — including a GitHub label-query bug where comma-separated labels were being AND'd instead of OR'd (silently returning zero issues on some repos), and an empty-state gap where repos without good first issue/help wanted labels returned nothing useful at all.

One real build-time constraint shaped the final architecture: with model credits limited mid-build, I had Codex switch the runtime analysis calls from the OpenAI API to Groq's OpenAI-compatible Responses API (keeping the same two-call, schema-constrained structure), so the shipped app runs on Groq while GPT-5.6/Codex did the actual building.

Challenges we ran into

• The label-query AND/OR bug — early testing against octokit/octokit.js returned zero recommended issues. The root cause: GitHub's REST API treats comma-separated labels in a single query as AND logic, not OR, so a query for "good first issue, help wanted" was silently requiring both labels on the same issue. Fixed by fetching all open issues and filtering client-side instead.
• Repos with no beginner-labeled issues at all — some active, healthy repos simply don't use good first issue/help wanted labels. Rather than showing a dead end, the app needed a documented fallback path.
• Keeping the LLM strictly grounded — the schema-constrained JSON output helps, but the prompts also needed explicit instructions never to invent an issue, file, or module not present in the real fetched data.
• Environment friction switching tools mid-build — a local Windows sandbox restriction (spawn EPERM) blocked running the dev server and final build step directly inside the Codex session, and later Codex's own GitHub/Vercel connector tools hit their own integration issues (network sandboxing, tool-argument mismatches). Working around tool-level limitations to get a working local run and a real deploy took real problem-solving beyond the app code itself.

Accomplishments that we're proud of

• A working end-to-end tool built solo, from a blank repo to a real deployed app
• Recommendations that are demonstrably grounded in real repo data — every issue number and file path shown is real, not hallucinated
• A tone for the issue reasoning that leads with concrete technical substance (module, scope, skill match) before any encouragement, so it reads as genuinely useful rather than generic AI cheerfulness
• Catching and fixing a real, non-obvious API bug (the label AND/OR issue) through actual testing rather than shipping it broken

What we learned

• How much prompt design — grounding, structured JSON schemas, explicit tone rules — matters more than raw model capability for this kind of task; a well-specified prompt against a smaller/cheaper model outperformed a vague prompt against a bigger one
• Splitting one big LLM task into two focused sequential calls (architecture, then issue ranking fed by the first) produced more coherent, less hallucination-prone output than one combined prompt
• API query semantics matter more than they seem — GitHub's AND-not-OR label filtering was an easy trap that silently broke the core feature rather than throwing an error
• Working with Codex conversationally (plan → structured brief → iterate on real bugs) was far more effective than expecting one-shot generation to get everything right the first time

What's next for FirstPR

• Support for private repos (with user-provided GitHub auth) for students onboarding onto their own team's codebase
• A lightweight visual module map as an alternative to the text-based architecture summary
• Saved progress / history so students can track issues they've started across sessions
• Broader issue-label support beyond good first issue / help wanted for repos with different labeling conventions
• Direct integration suggestions — e.g. surfacing the specific files/functions an issue likely touches, not just the module

Built With

• codex
• next.js
• node.js
• openai
• react
• tailwindcss
• typescript