When Patrick describes how he'd like to learn an unfamiliar codebase, he reaches for a map of Westeros. You open it and see the whole continent at once. You don't need to know any names yet. You notice a region, look closer, and the map fills in with smaller places. Keep going and you're down to a single town.
He wants code to work like that. Open a repository and see its major systems laid out. Click one, and it resolves into the smaller systems inside it, each with a short explanation of what it does. Click again and you're looking at a simplified account of the logic. Eventually, if you want it, you're looking at the source.
He has tried to build versions of this several times. None of them turned into something he uses. None was adequate for the problem. This article covers what those attempts were, what they taught him about the problem, and why it's still open.
Why not just ask?
The obvious answer in 2026 is to ask an agent. Point it at the repo, type a question, get an explanation. That can work when the reader already knows what they want to know. A directed task, like "how does this function handle retries?", fits a chat box well.
Open-ended learning is different. Patrick says he learns most by poking around. He opens a file, jumps to a definition, notices something unexpected nearby, and follows that instead. The path he ends up on is often not the one he'd have asked about, because he didn't know it existed when he started.
A chat answer is shaped by the question. The agent decides what's relevant and leaves out the rest. That's the point of an answer, but it also means the neighboring systems and side paths never show up unless you already know to ask about them. You lose discoverability.
So for exploring, Patrick would start with a map, not a question box. The first screen should give him places to go before he knows what they're called.
There's a second requirement that's easy to miss. When he zooms into a subsystem, he doesn't want it cut away from everything else. A module explained in isolation is hard to understand. You need to know what calls it, what it affects, and why it exists in the first place. The zoomed-in view has to keep some of the surrounding system visible, the way a regional map still shows where the borders are.
Four levels, four kinds of view
Patrick's working model has four levels of zoom:
| Zoom | What the reader sees |
|---|---|
| High | Written concepts, broken into pointers to systems |
| Mid | A highly simplified account of a selected system and its parts |
| Low | A simplified representation of the code's logic |
| Lowest | The source code itself |
The important thing about this table is that it isn't one diagram at four sizes. Patrick thinks each level probably needs its own representation. Prose is good for orienting yourself among systems: this part stores things, that part schedules work, this other part talks to the outside world. Prose is bad for following a branch. Once you're tracking what happens when a condition fails, you want something closer to code structure, just with less noise.
That leaves a lot unsettled. What exactly goes at each level? How do you generate it for a repository nobody has described before? Where does one level stop and the next start? How do you move between them without losing track of where you are? Patrick hasn't answered these. He's especially unsure about the lower levels, where the right abstraction for "simplified logic" might be a smaller map, might be something like pseudocode, or might be something else.
Editorial illustration of Patrick's proposed zoom levels, using an invented codebase. It is not a screenshot of a working tool or a map of Westeros.
Semantic Projector: one level above the source
The first attempt started closest to the code. Patrick wanted to see a program one step above its source, with the navigation he's used to from an editor. Jump to a definition. Follow a call. Back out. But instead of reading implementation code, he'd read short descriptions that he could get through much faster.
Early Semantic Projector prototypes tried several ways of representing a single function. The one Patrick liked best was a plain, text-first flow outline. It kept the program's shape. A branch still looked like a branch. A call still pointed somewhere you could follow. Hovering over a line showed the source behind it. He didn't want flashy HTML blocks; he wanted something he could skim.
That grounding mattered. A free-standing narrative about a function is pleasant to read, but you can't easily check it, and you can't explore from it. The outline kept a link back to the actual code at every step.
The first mechanical translation ran into a problem, though. When a function was rewritten as short verbs, assignments, branches, and returns, it still read a lot like the original TypeScript, just with different punctuation. Patrick wasn't convinced it was any easier to read. A broader description of what the function did worked better for him. That raised a harder question: could you get to that level of meaning without a language model doing the summarizing?
The project grew into a pipeline. It parsed TypeScript, built a language-neutral representation of control flow, followed calls it could resolve across files, and kept every piece tied to a source location. It could render a file, or a semantic view of a set of changes. A model could optionally add short labels, while the parser stayed responsible for structure and source anchors. The idea was to make the view traceable, so that a model couldn't quietly invent a tidy story about code that didn't match it.
The product question didn't go away. Patrick wanted to begin from a repository or module, the top of the map, and zoom down to a file or a diff. Running a model over an entire repository was slow and expensive. Narrowing the scope to single files and diffs made the model calls manageable, but it also pulled the tool away from the broad overview that exploration needs. At some point he wondered whether the useful piece might just be a skill that a coding agent runs when asked.
Semantic Projector produced specific views Patrick liked. It did not produce a way to learn a large, unfamiliar codebase that he kept coming back to.
Comprehension: a neighboring problem
Another experiment came at understanding from a different side, and it's worth being clear that it's a different problem.
Patrick would hand an agent a task, go do something else, and come back to a long account of what it had done. Reading the whole transcript or the whole diff was expensive. What he actually needed was narrower: where things stood, what had changed, what decisions the agent had made along the way, and what needed him. He compared it to a manager catching up on someone else's work. You have a partial picture and you need just enough context to make the next call.
The Comprehension plugin turns a message, a selection, or a thread into a saved HTML explainer, an audio briefing, or a podcast-style walkthrough. Patrick also tried narrated visuals. He found the newer audio better than an earlier version. The slides were harder: without a narrative holding them together, they were difficult to follow. Another pass still stayed too high level. He was interested in the idea of feeding information over time to hold attention, but changing the format didn't automatically produce understanding.
Comprehension sits next to the codebase question rather than inside it. Exploring an unknown codebase asks what exists and how it fits together. Catching up on an agent asks what just happened and what matters now. Both need clear explanations backed by evidence. But a finished report on one thread is not a map you can wander around in. The plugin's own documentation says its reports are static and don't yet keep a structured record of changes, decisions, and evidence, or track where the reader is in them.
Staged capture from the public Comprehension plugin. It shows an explainer for agent work, not the proposed codebase map.
Concept DSL: a middle layer you can click
The most recent attempt went back to the codebase and aimed at the part of the map Semantic Projector had struggled with: the middle.
Patrick wanted the clarity of a plain-English explanation combined with the explorability of an actual codebase. The picture was something like a much smaller, conceptual version of the repository. An agent would first lay out the conceptual files, the regions of the map. When he opened one, the agent would generate its contents. Clicking a concept inside it would take him to the next layer down. Going to the real implementation would be something he chose to do, not the only way forward.
Which raised the question that kept coming back: what should that middle layer actually look like?
It couldn't be ordinary code with friendlier names; that was the Semantic Projector problem again. It couldn't be loose prose either, because then you lose the ability to navigate. Early versions of the syntax had too many constructs and too many levels. Writing business logic as comments felt wrong to him. Comments describe a program, but here the natural language was supposed to be part of the logic being represented, so it had to be clearly contained as such. And since the audience was experienced programmers, familiar structure like types and calls could stay wherever it helped.
The repository now has a grammar, examples, a parser, and a read-only HTML reader. Concept files use Python-like flow alongside explicit natural-language logic statements, with source evidence kept alongside. A first walkthrough traced one message-submission path in BB across the composer, server, and daemon, with source attached to the explanation. The README describes this as a first investigation, not a completed trial.
That walkthrough surfaced real authoring problems. Where should the abstraction boundary go? How do you explain asynchronous error handling at this level without either hiding it or drowning in it? How much source is too much? How do you notice when a source link no longer points at what it used to? The reader is also a snapshot that has to be rebuilt after edits.
What Concept DSL is, then, is a prototype of a representation and a way to read it. It isn't a generated map of an unfamiliar codebase. Patrick stopped before getting far with generating the DSL, and he hasn't used it to learn a system. The hand-built walkthrough shows what one path might look like. It doesn't show how you'd get from an unseen repository to a full set of concepts worth clicking through.
Where it stands
Put side by side, the three projects each touched a piece of the problem. Semantic Projector explored flow views tied tightly to source. Comprehension explored how to bring someone back up to speed on work an agent did. Concept DSL explored what a clickable conceptual layer might be written in. That's a description of what they attempted, not a claim about how well they worked. Patrick doesn't use any of them, and none was adequate.
The target hasn't moved much. He still wants to open an unfamiliar repository and see a map, click a region, see what's inside it and what's next to it, and keep going until the code starts to make sense. What has changed is how much he knows about why that's hard.
Some of the questions are about the map itself. When you zoom into a subsystem, what has to stay visible from outside it? Its callers, the things it changes downstream, the data it shares with its neighbors, or the reason it was built? Probably some of each, but it isn't obvious how much before the view gets cluttered.
Some are about generation. In a repository nobody has described before, what decides which concepts exist? Directory structure may offer clues, but systems can span many directories. A model could draw the boundaries, but the reader would still need a way to check them against the code.
And some are about what counts as success. Patrick hasn't pinned down what it would mean to understand a module well enough. It could mean predicting what it does, changing it safely, explaining it to someone else, or catching an agent's mistake in it. Each of those might want a different map.
He stopped the Concept DSL work before finding out whether generated concept files could hold up across a whole codebase. It's possible they could. It's also possible the middle of the map needs something none of these prototypes tried.