How i give my coding agent a map of the repo with Empryo

ProxySoul — Tue, 15 Sep 2026 19:54:13 +0000

i built Empryo solo because i was tired of explaining the same repo to my coding agent. where things live, what calls what, which files usually need to change together. then a new session starts and i'm doing it again.

Token usage bothered me too. A few prompts can involve a lot of reading, retries, and tool results. The prompt you type is only a small part of what the model processes.

So i started with the thing i wanted the agent to have before it opened another file: a useful map.

The Genome

The screenshot above is Empryo's Genome dock. It maps files, symbols, and imports, and updates as the code changes. The little agent moves around the graph while it works. yes, i gave it a home.

Behind that view, the agent gets a ranked text map. Connections between files matter. Recent reads and edits matter. Files that tend to change together in Git can provide another clue.

The graph helps choose where to look. The agent still needs to open the source, check its assumptions, and run the relevant tests.

One rename, several places to check

Take an illustrative task: rename a session method and update its callers.

auth/session.ts
  refreshSession()
       |
       +-- api/client.ts
       +-- workers/refresh.ts
       +-- tests/session.test.ts

A filename search might find the implementation immediately. The more interesting question is what depends on it.

An import relationship gives the agent a place to investigate. A test that often changes alongside the implementation is another lead. Neither proves that every caller has been found. Dynamic calls, generated code, and string references still need checking.

The workflow i want is simple:

Use the map to pick the likely implementation and dependents.
Read those files before changing the interface.
Make the change and update the map.
Search for remaining references and run the focused tests.
Review the diff for changes outside the task.

Keeping that map current matters. A map of yesterday's code can confidently send an agent to the wrong place.

Same idea, in the terminal

This is the TUI. The change view shows dependents and co-change hints beside the files. i want those clues visible to me too, so i can see what the agent is working from.

It also has themes. i spend enough time in a terminal to care how it feels to sit in one.

A cheaper model can still make a more expensive run

Empryo lets me route different tasks to different models. Exploration, editing, and review don't always need the same choice.

But switching models has a catch: cache reuse.

A worker on the same model can sometimes reuse an existing prompt prefix. Moving it to another model can mean paying to process that context again. A lower token price doesn't automatically mean a lower total.

This is why i care about cached input, fresh input, output, retries, and whether the change actually worked. A failed cheap attempt followed by a full retry is still two attempts.

Subscription usage is another separate measure. A token-price estimate is not the amount charged to a subscription, and cache percentage is not a percentage of money saved.

A small test i'd actually trust

If you're comparing coding agents, give each one the same commit and a small task with a checkable result. Keep the model and permissions comparable where possible.

Record:

Check	What to write down
Correctness	Did the relevant tests pass, and does the diff solve the task?
Exploration	Which files were read before the first edit?
Rework	How many retries or corrections were needed?
Usage	Fresh input, cached input, output, and the billing basis
Your time	How much explanation and review did it take?

Repeat it on a few tasks. One attractive screenshot can't tell you which setup works best for your repo.

That's the problem i'm working on with Empryo: better project awareness, with desktop and terminal interfaces that make the work easier to follow.

GitHub

How do you handle this today? A repo instructions file, your own index, or a lot of repeated explanations? i'm especially interested in what breaks once a project gets big.