AI coding agents have made it much faster to produce code. But speed creates a new problem: when changes arrive quickly, it gets harder to keep track of the intent behind them—and to understand how each change affects the rest of the system.
I wanted a better way to plan changes on codebase before asking an agent to apply it. Not another static architecture diagram, but a workspace where the architecture could be explored, discussed, and used to guide implementation.
That became CodeChroma.
🔗 Quick link: CodeChroma on GitHub
The problem with diagrams that stand still
Mermaid and HTML diagrams are great tools for visualizing software architecture. I used them myself when I first started exploring ways to understand and navigate codebases.
But I kept running into the same problem: switching back and forth between the AI agent's terminal and a separate diagram breaks the workflow. And even when a diagram gives you a clear picture of the architecture, you can't simply click on a node and jump straight to the relevant code.
I wanted to see the bigger picture, navigate directly to specific parts of the codebase, and guide the agent without constantly switching between tools.
So I decided to build my own app—one where the architecture diagram isn't just a visualization, but an interactive workspace connected directly to the code and the AI agent.
What CodeChroma does, step by step
1. Build a map from a repository
CodeChroma analyzes a codebase and presents its structure as a hierarchy, from the system and its components down to services, functions, and code. The goal is to help you navigate the software by how it fits together—not only by which folder a file happens to be in.
2. Explore the system at different levels
Start with the broad shape of the system, then zoom into the parts you want to understand. Follow connections between components and move from an architectural view toward the code behind it.
This makes it easier to ask questions like: Where does this behavior live? What depends on it? What else might be affected if I change it?
3. Look at the architecture through different diagrams
Different views help answer different questions. CodeChroma includes diagrams for system context, design patterns, and change impact. They provide different ways to inspect relationships in and around the codebase.
The point isn’t to replace one static diagram with several static diagrams. It’s to make these views part of an architecture workspace you can explore.
4. Set workflow for routine tasks
AI agents can write code quickly, but handing over a task shouldn’t mean losing sight of the work. CodeChroma’s steerable workflows make the process easier to follow: start a run, track its progress, and pause at checkpoints to review or redirect before it continues.
Runs keep their state and history, while Git checkpoints help mark the changes made along the way. The agent can handle implementation; you stay involved in the decisions.
5. Bring an agent into the work
Once you understand the relevant part of the system, you can use that context to frame work for an agent. CodeChroma also supports agent questions and steerable workflows, so the process can include clarification and checkpoints rather than being a single, opaque “go build this” request.
The intention is to keep the person responsible for the change involved: the agent can do implementation work, while you provide direction and review the steps.
What I’m still figuring out
A visual map can help explain a system, but how should it stay useful as that system changes? How much architecture should be inferred automatically, and where should people be able to correct or reshape it?
And when an agent is working from architectural context, what’s the right balance between autonomy and checkpoints? How do we make its decisions understandable without slowing every task down?
If you work with AI coding agents, I’d be curious: what helps you stay in control when the code is changing faster than you can read it?# CodeChroma: From “What Does This Code Do?” to “What Should We Change Next?”
