There's a particular kind of blank-stare moment that many developers know. You open a project, maybe something you cloned a few weeks ago, maybe something you built yourself six months back and never quite finished, and you just stare. The code is right there, you may have even written some of it, but the thread is gone. What is this? How does it work? Where do I even start reading? You can open files, but without context, it's just code. It's like being dropped into a city where you don't speak the language, and trying to find your way around by looking at the street signs. You can do it, but it's slow, frustrating, and you can miss a lot.
The README, if there is one, can only tell you so much. It's a snapshot, usually written at the start, and projects have a way of drifting from their original intentions.
I built a VS Code extension called Explain This Project
to help with exactly this. Run one command, and it walks your workspace, figures out what languages
and frameworks are in play, maps the directory structure, lists your dependencies, and writes all of
it to a PROJECT_OVERVIEW.md at your project root. With GitHub Copilot connected, it
also prepends a plain-English narrative summary. No API key, no setup. Just a file you can read.
That covered the structure side of things pretty well. But structure is only part of the picture.
The history side
I came across a post recently by Ally Piechowski, The Git Commands I Run Before Reading Any Code , and it clicked immediately. She runs a handful of git commands before opening a single file: which files change the most, who built what, where bugs tend to cluster, whether the project is gaining momentum or slowly going quiet. It's the history side of the picture, the stuff no README ever captures.
Reading it, I thought: that belongs in my extension.
So I added it. The overview now includes a git diagnostics section alongside the structural
analysis. You get the high-churn files, the contributor picture, the bug hotspot map, the commit
velocity over time. It all lands in the same PROJECT_OVERVIEW.md, so when you open a
project cold, you have one place to start making sense of it.
What it gives you
The extension generates sections you can scan in thirty seconds and decide where to start:
Structure analysis tells you what languages, frameworks, and build tools are in use. It lists your dependencies, finds your entry points, and maps the directory tree. Standard stuff, but organized and consistent.
Git diagnostics shows you which files are the hotspots. The top ten most-changed files, the contributor breakdown, when the most active periods were, and where bug-related commits tend to land. If something breaks a lot, you find out before reading a line of code.
Plain-English summary is the part that surprised me. If you have GitHub Copilot, the extension uses it to read the generated overview and write a few paragraphs explaining what the project does, how it's organized, and what the current state looks like. No separate API keys. It just uses what's already connected.
New project, old project, someone else's project, your own half-finished thing from last spring. It doesn't matter. The first thing I do now is run Explain This Project, read the overview, and then open the code. It's not a magic answer, but it's a much better starting point than staring at a file tree and hoping something shakes loose.