I built Satori: a read-only codebase map for AI coding agents

Hi, I’m Hamza, the maker of Satori.

Most AI coding agents can search files.

That is not enough.

Real codebases are not flat text dumps. They have symbols, ownership boundaries, wrappers, callers, callees, stale files, generated output, and logic spread across folders.

Without structured repo context, agents build context the hard way.

They burn tokens pulling broad file dumps.

They still may not have the complete picture.

They guess which file owns the behavior.

They miss related callers, wrappers, and stale paths.

That is expensive for frontier models — and even harder for smaller, local, or non-frontier models where every token matters more.

I built Satori to give MCP-compatible coding agents a more efficient investigation path before they touch code.

What is Satori?

Satori is an open-source, read-only codebase map for AI coding agents.

It helps agents move from:

plain-English intent

→ owner symbols

→ file outline

→ exact symbol / line reads

→ advisory caller/callee context

→ freshness-aware recovery

The goal is simple:

• less grep chaining


• less context waste


• fewer blind edits


• more visible evidence before the first diff

Satori does not edit your source code. It gives agents better repo context so developers can steer and approve changes with more confidence.

Why search alone is not enough

Search gives agents access to text.

But investigation needs more than nearby text.

A real repo has structure:

• which symbol owns the behavior?


• is this file a wrapper, test helper, generated output, or the real implementation?


• what exact span should the agent read?


• are there callers or callees worth checking?


• is the index stale or safe to rely on?


• did the agent use evidence, or did it just follow a grep chain?

When agents do not have a structured path, they often compensate by pulling more files into context.

That increases token cost, but it does not guarantee completeness.

More context is not the same thing as better evidence.

What Satori gives agents

Satori exposes a small MCP tool surface for repo investigation:

• index status and readiness


• semantic search by plain-English intent


• grouped, symbol-aware search results


• file outlines


• exact file / line reads


• advisory caller/callee context


• freshness warnings and recovery guidance

The point is not to replace developer judgment.

The point is to make the agent show better evidence before it proposes a diff.

Example workflow

Instead of asking an agent to grep around a repo and hope it finds the right place, Satori gives it a repeatable path:

1. Search by intent.


2. Land on owner symbols.


3. Open the file outline.


4. Read the exact symbol or line range.


5. Check related callers/callees when supported.


6. Verify freshness before relying on the result.

That makes the investigation cheaper, more inspectable, and less dependent on dumping entire files into the model.

Install

npx -y @zokizuan/satori-cli@latest install --client all

npx -y @zokizuan/satori-cli@latest doctor

Satori works with Codex, Claude Code, OpenCode, and MCP-compatible clients.

It is currently pre-alpha, and offline support is planned.

Links

Website: https://satori.hamza.my.id/

GitHub: https://github.com/ham-zax/satori

npm: https://www.npmjs.com/package/@zokizuan/satori-cli

Product Hunt: https://www.producthunt.com/products/satori-4?utm_source=other&utm_medium=social

Feedback

If you use coding agents on real repos, I’d love to hear where they usually lose context.

Is it wrong files?

Broad file dumps?

Missed callers?

Stale repo state?

Overconfident edits?

And if Satori looks useful, a GitHub star, Product Hunt upvote, or comment would really help the launch.