What If Humans and Coding Agents Shared a Map?

New agentic coding sessions in harnesses like Claude Code and Codex are almost blind when it comes to the structure of an unfamiliar codebase. They typically search, read, follow imports and references.

Their navigation tools are low-level retrieval primitives like grep, glob, file trees, semantic search, and feedback from tests or the compiler. This works surprisingly well, but can be quite slow and token-inefficient.

It gets even worse for legacy codebases with unfamiliar structures and naming conventions. Here the agent lacks an intuitive understanding of where things are and how files and variables are named, which makes searching more difficult.

Architectural understanding is mostly reconstructed on demand. Usually from scratch in every new agent session.

One agent spending time rediscovering a flow is inconvenient, but several agents doing it independently, across many tasks and sessions, means waiting and paying for the same discovery work again and again.

Illustration of a coding agent handling the request “Let users archive a project.” The agent lists the repository, searches for related code, reads the service, its route, the menu component, and the tests, and only then edits three files. A failing test points to a type it missed, so it searches for that type, fixes it, and reruns the tests. The run is illustrative, not recorded.

How a coding agent finds its way today

illustration

>

Let users archive a project.Ask the agent…Let users archive a project.

Agent run

waiting

1. searchls src/look at the repo

   Create project→Projects UI→Projects API→Projects table

   • api
   • app.ts
   • common
   • components
   • config
   • core
   • db
   • helpers
   • index.ts
   • jobs
   • lib
   • models
   • routes
   • services
   • shared
   • store
   • tests
   • types
   • utils
   • workspace
2. searchrg --files | rg -i projectfind entry points
3. searchrg -i "archive" src/look for related code
4. readservices/projectService.tsread the service
5. searchrg "projectService" src/trace references
6. readroutes/projects.tsfollow the route
7. readcomponents/ProjectMenu.tsxfind the UI entry
8. readtests/projectService.test.tscheck the tests
9. editservices/projectService.ts +2edit after 8 steps
10. testnpm testProjectDTO lacks field
11. searchrg "ProjectDTO" src/find the missed type
12. edittypes/project.ts
13. testnpm testall tests pass

0 searches · 0 files read · 0 test runs

Now, from a human perspective, we are faced with a different problem. Coding agents have become so good and fast that our own understanding has basically become the bottleneck.

So, I was thinking, why not create a map or graph of the codebase that draws out the logical flow happening in the background, making it more visual and easier to understand?

This UX/action map could give agents a higher-level entry point. Instead of asking “Which files mention project creation?”, the agent could start from a user action like “Create Project” and immediately see the relevant user flow, related actions, implementation steps, dependencies, and source files, without reading hundreds of lines of code.

The map could give each session a shared starting point, allowing the understanding built in one session to carry over to the next.

Both Claude Code and Codex support hooks in their agent harnesses, which I think could be ideal for keeping such a map up to date. A smaller, cheaper model might be enough to handle routine map updates, which could help keep the maintenance cost low.

I tried to illustrate how this could work below:

Animated illustration. A developer asks a coding agent for three features in an example project, one after another. After each feature, a stop hook updates a UX/action map: a flow chart of the codebase that links each user action to the frontend, backend, and data areas it runs through. From the second feature on, the agent reads the map before it changes code. Areas and links added by the latest feature are highlighted.

You request a feature

> Let users create a project.> Let users create a project.

Agent implements it

0 files changed

Hook updates the map

Stop → update-action-map

UX/action map of the codebase

Flow chart of the underlying code, from user action to data

User actionFrontendBackendData

empty map

Create project3 areasArchive project3 areasInvite member4 areasProjects UI0 filesProjects API0 filesProjects table0 filesSharing UI0 filesMembers API0 filesMembers table0 files

swipe the map →

1 / 3

The map would not replace code search but guide and accelerate it. The agent could use the map to identify the likely change surface, then verify those relationships against the live code before making changes.

I haven’t verified this yet, but the result could be less redundant exploration, lower context usage, faster orientation in unfamiliar codebases, and fewer accidental changes outside the intended feature flow. Example:

Illustration comparing two runs of the same request, “Let users archive a project.” Without a map, the agent searches the repository, reads files, edits, and only finds a missing type after a failing test. With the action map, the agent opens the related flow first, verifies it against the code, edits the listed files, and a hook adds the new flow to the map. The runs are illustrative, not measured.

Same request, two starting points

illustration · not a benchmark

>

Let users archive a project.Ask the agent…Let users archive a project.

Without a map

waiting

1. searchls src/look at the repo

   Create project→Projects UI→Projects API→Projects table

   • api
   • app.ts
   • common
   • components
   • config
   • core
   • db
   • helpers
   • index.ts
   • jobs
   • lib
   • models
   • routes
   • services
   • shared
   • store
   • tests
   • types
   • utils
   • workspace
2. searchrg --files | rg -i projectfind entry points
3. searchrg -i "archive" src/look for related code
4. readservices/projectService.tsread the service
5. searchrg "projectService" src/trace references
6. readroutes/projects.tsfollow the route
7. readcomponents/ProjectMenu.tsxfind the UI entry
8. readtests/projectService.test.tscheck the tests
9. editservices/projectService.ts +2edit after 8 steps
10. testnpm testProjectDTO lacks field
11. searchrg "ProjectDTO" src/find the missed type
12. edittypes/project.ts
13. testnpm testall tests pass

0 searches · 0 files read · 0 test runs

With the action map

waiting

1. mapopen flow "Create project"3 areas · 7 files

   Create project→Projects UI→Projects API→Projects table

2. readservices/projectService.tsverify against code
3. readtypes/project.tsverify the DTO
4. editservices/projectService.ts +2edit after 3 steps
5. edittypes/project.ts
6. testnpm testall tests pass
7. hookStop → update-action-mapadds “Archive project”

0 map lookups · 0 files read · 0 test runs

For users, it could mean maintaining a deeper understanding of their codebase and the changes made by coding agents, without reading all of the underlying code. Especially when the map is easy to explore visually.

The map could also let a developer review planned changes before the agent starts implementing them, see which user flows changed afterwards, spot unexpected effects on another flow, or explain the system to a teammate. As agents get faster, being able to understand and review their work becomes even more valuable.

I’m working on something along these lines and hope to release it soon.