io.github.tyler-mitchell/type-atlas

Type Atlas is what I have all my code agents use across all of my TypeScript projects for all code navigation needs. Most of those projects are monorepos. Some are large and complex enough that understanding how a change fits into the rest of the system is a real part of the work. This tool was designed as a complete replacement for an agent's default code navigation methodology.

I've been iterating on this tool for months based on how my own coding agents actually work in my projects. Most of what Type Atlas does, exists because I kept seeing the same problems:

• Agents reason from an incomplete view of the system. They may understand the file they found while missing the surrounding code that determines how it is supposed to be used.
• Agents rebuild things that already exist. The capability is already in the repo, but the agent never finds it because it does not know what it is called.
• Agents often read either too little code (Claude) or far too much (Codex). Too little leaves them making decisions without enough surrounding context. Too much fills the context window with entire files and implementation detail that never mattered to the task.
• Agents repeatedly stop to run type checks just to find errors an IDE would already be showing. That adds latency throughout implementation and pushes feedback later than it needs to arrive.
• Agents are fundamentally operating blind. String-search navigation never gives them a strong internal atlas of the codebase. They are forced to make implementation decisions from fragments of files and matches they happened to retrieve, with important structure and compiler-known information still missing.

As projects grow, these problems compound and start showing up directly in the quality of the code agents write.

Semantic code navigation

Coding agents navigate code through file reads and string searches by default. That gives them source text and leaves the model to reconstruct relationships that the TypeScript language service already knows.

Type Atlas gives the agent direct access to that semantic information:

• A symbol resolves to its actual definition and references rather than every occurrence of the same text.
• Callers and implementations are identified by their relationship to the symbol.
• Inferred types come from the language service instead of being reconstructed from nearby source.
• Results keep their source range and owning TypeScript project attached.

A text match is still useful when text is what the agent is looking for. It is a weak substitute for semantic navigation when the question is about the program itself.

Find what already exists

Large codebases contain useful code that an agent has no reason to know by name. String search works best after the agent already knows enough vocabulary to formulate the search.

Type Atlas gives it other ways in:

• The agent can describe behavior in natural language and find code based on what it does.
• A discovered result leads back to a real symbol and an exact source range.
• From that symbol the agent can follow actual relationships through the codebase instead of guessing another identifier to search for.

This is especially useful in large monorepos. Existing helpers and established implementations are easier to discover before the agent

... View full README on GitHub