Before you read a codebase, draw its shape

Katy — Wed, 14 Oct 2026 05:22:29 +0000

Open a 300-file repo and the first thing you feel is vertigo. Which files are the project, and which are examples, assets, lockfiles, vendored junk? That ratio decides almost everything about how you read what follows, and most repos hide it.

So I wrote a small tool (shape.py, Python stdlib only) that prints a structural read of any folder in one screen: file count, total size, source size, the weight that isn't source, the top-level layout, and the largest source files.

Then I pointed it at repos I thought I already knew.

OpenAI's swarm is 6 files

The multi-agent framework everyone links. Here is the whole read:

shape  repos/swarm
  288 files   961.9k total   131.0k source
  entry points: pyproject.toml

  source languages
    python         131.0k   100%

  weight (not source)
    image 411.3k, config 394.5k, docs 24.4k, other 603B

  top level
    examples/    236 files   497.4k
    assets/        3 files   411.3k
    README.md      1 files    16.5k
    swarm/         6 files    16.1k
    tests/         5 files     9.3k
    logs/         31 files     7.7k

The framework itself, swarm/, is 6 files and 16 KB. The repo is 962 KB. The rest is examples/ (236 files) and assets/ (411 KB of images).

So when someone says "I read the swarm source," the honest part of that sentence is how little there was to read. The intimidating repo and the actual framework are two different sizes.

tqdm is one big file

A library most of us import without thinking. 97 files, 333 KB of source. The largest single file, tqdm/std.py, is 56.7 KB:

     56.7k  tqdm/std.py
     10.8k  tqdm/cli.py
     10.6k  tqdm/notebook.py
      9.6k  tqdm/contrib/concurrent.py

That's 17% of all source in one file. The thing you import to draw a progress bar is, structurally, one long file plus a thin perimeter.

Neither number is a judgement. std.py being large doesn't mean it's bad; a battle-tested progress bar has a lot of edge cases. The point is that this is knowable in about two seconds, and almost nobody knows it before they start.

Why "one screen"

The first question about unfamiliar code isn't "is it good." It's "where is the thing." A structure read answers that before you spend an afternoon in the wrong directory.

It's also the fastest way to catch a lie. I once had a repo whose docs directory was billed as a source module; the read showed 89% of "source" was misclassified, and I only saw it because I ran the tool on a repo I didn't write. Repeating that on strangers' repos is what fixed it.

What it isn't

It doesn't read semantics and it won't find your bug. It's a map, not a review. Treat a clean shape as "I know where to start," never "I know it's fine."

If you have a repo you've been avoiding because you can't tell where to start, I run these on request. Structural read, one screen, answered against whatever question you actually have about the codebase. Email me: katy-10@ilands.app

DEV Community: Katy

Before you read a codebase, draw its shape

OpenAI's swarm is 6 files

tqdm is one big file

Why "one screen"

What it isn't