RepoPath

RepoPath helps you trace the code, preserve your starting point, and explain the feature back in your own words.

Comment

Inspiration

I built my earlier portfolio project, Kiwi Interview Agent, with Codex. The development speed was real: I could ask AI to write a walkthrough, identify the files behind a feature, or explain a prompt and receive a polished answer in seconds. But when I closed the chat, I often could not reconstruct the feature in my own words.

The clearest example was its Agent Harness. I could find the planner, tools, traces, and prompts, but that did not mean I truly understood why the harness existed, how state and evidence moved across the system, where the safety boundaries were, or what would happen when retrieval failed. I had created a portfolio project faster than I had converted it into my own technical knowledge.

RepoPath began from that gap. I wanted a learning product that treats AI output as scaffolding, not proof of understanding. The goal is not to generate another repository summary. The goal is for a learner to trace one real feature through a repository, explain it without AI assistance, and support that explanation with code, tests, and official documentation.

What it does

RepoPath turns a public GitHub repository into an evidence-grounded learning path.

A learner imports a repository, chooses a feature, gives a raw baseline explanation, and receives a structured lesson plan tied to a fixed repository snapshot. The plan links product purpose, execution flow, important code, tests, uncertainty, and later assessment. Human checkpoints let the learner accept, revise, or reject important AI proposals instead of silently treating them as product truth.

The current implementation is intentionally smaller than the final vision. Checkpoints 1–4 are implemented: the local FastAPI/PostgreSQL/React foundation, public GitHub repository intake, evidence-backed feature discovery, feature acceptance, baseline capture, bounded retrieval, curriculum-planner proposals, Product Harness validation and persistence, and append-only human review. Checkpoints 5–6 are in progress, and Checkpoint 7 remains planned. Tutor sessions, final assessment, and learner memory are therefore not presented as completed features.

The educational success condition is also strict: opening files, spending time in the UI, or receiving a good AI answer does not prove learning. Only the learner's own evidence-backed explanation can support a demonstrated result.

How I built it

I built RepoPath as a series of closed-loop checkpoints rather than as one long coding prompt.

For each checkpoint, I first defined a bounded goal, non-goals, dependencies, completion evidence, and stop conditions. I then wrote a specification covering typed inputs and outputs, authority boundaries, budgets, failure states, tests, and the exact evidence required before the checkpoint could be called complete. Implementation started with contracts and targeted tests, then moved through the smallest vertical slice, and only expanded to broader gates after the focused slice was green.

The application uses React, TypeScript, Vite, and TanStack Query on the frontend; FastAPI and Pydantic at the API boundary; PostgreSQL, SQLAlchemy, and Alembic for durable state; and LangGraph for bounded agent workflows. Public repository access is read-only through GitHub APIs. Imported repository content is treated as untrusted data, not as instructions, and the product never executes imported code or installs its dependencies.

The Agent Harness is the best example of the architecture. RepoPath has one learning agent with isolated modes, including repository analysis and curriculum planning. Each mode receives typed context, an explicit tool allowlist, a budget, an output schema, and a stop condition. The agent can only return a structured proposal. The Product Harness remains the authority for mode transitions, schema and citation validation, idempotency, human review, and persistence. A fixed repository snapshot and evidence references keep a model-generated claim traceable to the source that supported it.

How I used Codex and GPT-5.6

I used GPT-5.6 through Codex as a reasoning, implementation, and review partner throughout the project, rather than as a one-shot code generator.

Codex provided the execution harness for reading files, inspecting repository history, editing code, running tests, reviewing diffs, and recording implementation evidence. GPT-5.6 was the reasoning model I used to interpret that evidence, connect product intent with architecture and implementation, maintain constraints across long workflows, identify root causes, and decide what should change.

I used GPT-5.6 for the most reasoning-intensive parts of the work. It helped turn ambiguous product intent into bounded checkpoint goals and specifications, compare conflicting sources of truth, define typed contracts and failure behaviour, preserve authority and privacy boundaries, and coordinate focused changes across frontend, backend, persistence, agent runtime, tests, documentation, and issue records.

Goals and specifications acted as control surfaces. The goal defined the learner outcome, non-goals, and exit condition. The specification constrained affected components, tools, budgets, authority, privacy, failure behaviour, and validation evidence.

My recurring loop was:

  1. Use Codex to inspect the current source, tests, repository status, history, and applicable product contracts.
  2. Use GPT-5.6 to identify the real problem, challenge assumptions, and define one bounded goal with explicit non-goals.
  3. Write the contract, authority boundary, and failure behaviour before broad implementation.
  4. Ask GPT-5.6, through Codex, to implement or review only that bounded slice.
  5. Use Codex to run targeted deterministic checks before expanding to broader quality gates.
  6. Ask GPT-5.6 to interpret failures, group related symptoms into root causes, and compare the implementation with the specification.
  7. Register material failures as issues and allow at most three evidence-backed remediation attempts for one root cause.
  8. Stop for a human decision when the product or authority boundary remained unclear instead of allowing the agent to continue indefinitely.

This mattered for both quality and cost. A closed goal, explicit constraints, deterministic validation, and visible stopping conditions reduced the risk of long coding loops drifting away from the intended outcome or repeatedly spending tokens on the same unsupported hypothesis.

Several activities demonstrate why I selected GPT-5.6 for this workflow. During debugging, it reduced fourteen apparent test failures to a small number of contract-level causes before changing production code. During the Dashboard redesign, it compared the interface, visual reference, frontend types, and assessment contracts, then rejected an incorrect threshold implied by the generated design. During authentication work, it treated Google login as an ownership and workspace-isolation problem rather than merely adding a sign-in button.

I also compared this closed-loop process with a delegated coding pass that produced a detailed-looking implementation and small passing tests. The output appeared productive, but integration review exposed important gaps: an official-document adapter followed a redirect before validating the destination domain, exact dependency versions could be fabricated when the source page did not provide one, a frontend creation flow used an unkeyed POST inside a query, Dashboard state accepted unsupported strings, and the handoff left an unmapped gitlink and failing formatting gates.

I do not treat that comparison as a scientific model benchmark or as proof that one model always produces better code. Many individual tasks could also be attempted with other models. The practical lesson was that a capable coding model and a long instruction document are not enough by themselves. GPT-5.6 produced its strongest work when it operated inside a closed Codex loop with explicit authority, bounded context, deterministic validation, issue evidence, and a human stop gate.

The final product direction, architecture, acceptance criteria, security decisions, and approval of every change remained my responsibility.

Challenges I faced

The hardest challenge was making repository evidence retrieval reliable without giving the agent an unbounded search loop.

In one Checkpoint 3 evaluation, retrieval selected a nested benchmark README and archived backup artifacts before the repository's root README and canonical source files. The run used only five of twelve allowed tool calls, yet the stored result incorrectly claimed the budget was exhausted. The lesson plan could therefore be polished, cited, and still teach the wrong feature.

The first remediation round used all three allowed attempts. I added authority ranking and explicit budget state, then reserved capacity for evidence, then corrected the one-call boundary. The targeted suite became green, but a remaining risk was still visible: a repository containing only archival artifacts could be treated as if it had canonical evidence. According to the issue policy, I stopped instead of making a fourth patch.

After defining a new, narrower goal, I opened a second bounded resolution round. Three further hypotheses handled generated-directory categories, common aliases, and exact artifact filename stems. The final targeted verification covered 135 backend unit, contract, and agent tests and made archival-only repositories stop with a deterministic canonical-evidence-missing result before model synthesis.

That issue changed how I think about AI coding. The initial failure was not simply "the model wrote a bad summary." The deterministic harness had biased what any model was allowed to see. Each apparently complete fix exposed another edge case. Reliable agent behavior required retrieval policy, budget semantics, tests, stop rules, and human judgment to work together.

A second challenge was specification completeness. My early drafts sounded comprehensive to me, but lower-capability agents could satisfy the visible wording while passing through gaps in redirect safety, idempotency, state authority, or evidence semantics. They were not intentionally cheating; they were optimizing against an underspecified contract. I learned to turn important prose into schemas, negative-path tests, and deterministic write gates.

What I learned

First, repository knowledge and learner knowledge are different things. An AI can produce an accurate explanation while the human still cannot explain the feature independently. RepoPath therefore separates source evidence, AI proposals, learner attempts, and demonstrated outcomes.

Second, closed loops work. A bounded goal, explicit constraints, a three-attempt remediation limit, and a real completion gate reduce both agent drift and token waste. However, the loop is only as good as its contract. A vague draft can make the loop efficiently produce the wrong result.

Third, model quality and harness quality are complementary. GPT-5.6 was valuable for cross-file reasoning, contract review, code generation, and diagnosing why a fix was incomplete. Deterministic validators, focused tests, fixed snapshots, Product Harness authority, and human checkpoints kept that capability aligned with the product.

Finally, an honest partial result is more useful than a fabricated complete one. RepoPath explicitly supports partial, insufficient-evidence, blocked, and unassessed outcomes. That principle shaped both the product and the way I used Codex to build it.

Accomplishments so far

At the Checkpoint 4 freeze, the repository recorded six launcher tests, 200 backend tests, and 65 frontend tests passing, along with formatting, lint, strict backend and frontend type checks, and the frontend production build. More importantly, the implemented slice preserves the core educational boundary: it can prepare and review a lesson, but it does not claim that the learner has demonstrated understanding.

What's next

Checkpoint 5 will complete guided learning and Tutor interactions. Checkpoint 6 will add readiness, assessment, and an evidence-grounded dashboard without turning activity metrics into learning proof. Checkpoint 7 will add bounded learner memory, deletion and retention verification, abuse-path evaluation, Playwright coverage, live-provider evidence, and the final demo package.

The long-term goal is a reusable portfolio-learning workflow: not "AI, explain my codebase to me," but "help me build enough evidence and practice that I can explain it myself."

Limitations

RepoPath currently supports public GitHub repositories only. It is read-only and does not execute imported code. The full Tutor, Assessor, dashboard, and learner-memory journey is still under construction. Live-provider and browser end-to-end evidence will be reported separately from deterministic local test results, and planned behavior will remain labeled as planned until source and reproducible verification support a stronger claim.

Built With

Share this project:

Updates