Imagine walking into a city you have never been to.

You have one job to do. Maybe you need to find a post office to mail a post card.

You could walk every street until you find it. That works. It takes all day. Or someone could hand you a map.

The map costs nothing to read. It answers your questions before you ask them. You go straight to the post office. You mail the postcard. You go back to your hotel.

AI agents working on code are in the same spot. Every time you give one a task, it has to figure out where it is. What file talks to what. What depends on what. Who calls this function. It does this by reading a lot of files. That reading is not free. You pay for it in tokens.

We built something called shards to give the agent a map.

What a shard is

A shard is a small file. We put one next to every source file in your project.

If you have a file called Foo.tsx, we make a file called Foo.graph.tsx next to it.

Inside the shard is a short summary. It says three things:

It is written in plain sentences. Not arrows. Not charts. Sentences. Like this:

"parseConfig is called by main (cmd/root.go:42) and calls readFile (io.go:7)."

The reason it's sentences is that AI models were trained to read sentences. Give them sentences and they understand. Give them charts and they have to work harder.

You run the tool once. It makes all the shards. After that, when an agent works on your code, it reads the shards first. The agent already knows the shape of the codebase before it does anything. No walking the streets.

The magic part is that Supermodel keeps all the shards up to date as your AI changes things.

The test

We wanted to know if this actually helps. So we ran a test.

We picked a real project: Django. It is big. About 270,000 lines of Python across 6,600 files.

We gave Claude a hard task. Eight tests were failing. The tests wanted a new piece of code called EmailChangeRecord that didn't exist yet. The tests showed what it should do. They didn't show how to build it.

We ran the same task four times. Same model. Same task. The only thing that changed was the map.

  1. No map.
  2. A map someone wrote by hand.
  3. A map our tool made by itself.
  4. A map split into three separate files.

Here is what happened:

All four got the right answer. The code worked. The tests passed.

But the one with no map cost 60% more and took 4x as long.

The hand-made map was the cheapest. The auto-made map caught 83% of those savings with nobody writing it. It just ran.

Condition Cost Turns Time (s) Tests Passed
No map $0.30 20 122 ✓
Hand-made map $0.12 9 29 ✓
Auto-made map $0.15 11 42 ✓
Three-file map $0.25 16 73 ✓

Why it's cheaper

There are two things an AI spends tokens on. Reading files and writing things down. Reading is the expensive part.

Without a map, Claude read 235,000 tokens to figure out how Django works. It read test files. It read the test runner. It ran little commands to check the version. It combed through code trying to build a picture of the codebase in its head.

With a map, Claude read 90,000 tokens. It wrote a little more (23,000 instead of 19,000) because it pulled the maps into memory. But reading is where the real money was. 145,000 fewer tokens read.

That is the whole trick. Trade a small amount of writing for a big amount of reading. The map holds the answers. The agent does not have to go find them.

What not having a map looks like

Here are the first six turns of Claude without a map:

# run the tests → see 8 errors
read tests/change_tracking/tests.py
read tests/change_tracking/models.py
# list the files in the test folder
read two more files to see the setup
read the test runner to see how apps get wired in

Six turns and still no code written. Claude was just learning the shape of things.

Here are the first six turns with a map:

# run the tests → see 8 errors
read the test file
read the models file
find the related files
write the new model
# run the tests → all pass

Same task, done in six turns, because the structural questions already had answers.

What this means for you

You do not save money on your first task. You pay for the map once.

You save money on every task after that. A bug fix. A new feature. A review. A refactor. Each one gets the discount.

The more an agent works on your project, the better shards pay back.

You also get something quieter: the agent gets the same answers every time. It does not go wander a different way each run. It reads the map, and the map says what is true.

Try it

Install the tool:

npm install -g @supermodeltools/cli

Go to your project and run:

supermodel setup
supermodel watch

Shards show up next to every file. The agent reads them the next time it runs. That is the whole setup.

Run the analysis once. Save on every task after.

Want to get rid of all of the shards? No problem, just run:

supermodel clean