While an agent works, you wait. Sometimes it’s thirty seconds, sometimes a few minutes, and I mostly spend that time picking up my phone or wandering into a second conversation and scattering my brain across two problems. I’ve come to think those minutes are the most undervalued part of working with agents, and I have a specific idea about what they’re for.
The idea started with HyprMac, my tiling window manager for macOS. Most of its code was written with agents, and it grew fast. When bugs popped up, the only move I really had was describing the bug to my agent and hoping. What I wanted was to point at a specific module and say, this is what’s broken, fix it. I couldn’t, because the code had outgrown my understanding of it. There are a million reasons to actually know your codebase instead of blindly navigating it.
I don’t think the fix is reading harder. Software gets produced too fast now for line-by-line comprehension to keep up, and the pace is only increasing. The skill that matters is understanding code one level up, like what the modules are, what depends on what, what you can and cannot safely touch, and whether the agent is doing anything dumb along the way. The bar I want to hold is being able to answer any question about my codebase as if I wrote every line, even though I didn’t.
So the thing I’m developing is a live map of the codebase. It’s visual because dependencies are exactly the kind of information a diagram shows better than a wall of text, which UML figured out decades ago. It’s live because a map that updates while the agent works shows you what just changed, where the agent is working right now, and everything that depends on what it touched. You glance at it between prompts and build the mental model while the work happens, instead of after something breaks.
The one design rule I won’t bend on is that keeping the map current can’t cost LLM calls. If the map needs a model to stay fresh, I’m spending double the tokens and double the time between prompts, and reclaiming that time was the whole point. Static analysis already knows what changed and what depends on it, and it runs for free while the agent does the heavy lifting.
A piece went around this week warning against over-engineering your agent scaffolding, since the next model generation tends to absorb whatever you built and turn it into dead weight. The author calls it the Kirby effect, which is exactly the right mental image. It’s a fair warning, and I think this idea sits on the safe side of it. The map helps with a human limit, how much code one person can follow, and a better model doesn’t fix that. Better models will write more of my code faster, which makes understanding it at a higher level even more necessary. The research points the same way. In a randomized trial Anthropic published this year, engineers who leaned on AI for an unfamiliar coding task scored 17 points lower on a comprehension quiz right afterward than the group that coded by hand.
As for where it stands, it’s early. I’ve built a lightweight first draft, mostly to see what the idea looks like against a real repo, and it’s largely going to change. The likely home for it is llm-dev, Dallas Elleman’s Claude Code plugin for LLM-assisted development. I use it every day, and it’s a really great tool. A live codebase map lends itself naturally to what llm-dev already does, so Dallas and I are actively brainstorming the best ways to fold the idea in before I get into writing all the code.
I’ll write about it here as it develops (there’s an RSS feed if you’d like to follow along). The goal hasn’t moved since that first HyprMac bug. I want to understand what the agent is suggesting, so I can guide it better.