Every developer has had this experience.
You clone a repo. You stare at 40 files. You have no idea where to start.
The README says "just run npm start." The architecture diagram in the wiki hasn't been updated since 2021. Your team lead is in a meeting. You spend the first three hours of your day just trying to understand what the code does.
I got tired of this. So I built codebrief.
What It Does
You run one command in any project directory:
npx github:Android-Tipster/codebrief
It scans your source files, filters out the noise (node_modules, dist, build artifacts), picks the 25 most important files, sends them to Claude Haiku, and generates a CODEBASE.md that actually explains the project.
Not "here are the files." Actually explains it.
Here's what the output looks like for a real project (a browser extension I built):
What This Project Does
HistoryMind is a privacy-first browser extension that analyzes your browsing history to uncover intellectual blind spots and knowledge gaps. It clusters your reading by topic, rates your intellectual breadth, and recommends adjacent areas you should be exploring, all powered by Claude AI and processed entirely in your browser.
Architecture Overview
HistoryMind follows a three-stage pipeline: collection, analysis, visualization, with all sensitive data staying in the user's browser.
Collection happens in popup.js: the user enters their Anthropic API key, selects a time window, and chooses a history depth limit. These settings are saved locally.
Developer Onboarding Checklist
- Read the README: understand the mission, privacy model, and user workflow.
- Review manifest.json: know what permissions you have and what you don't.
- Walk through popup.js: trace the happy path from settings form to tab creation.
- Study analysis.js top-to-bottom: this is where the magic happens.
That's real output from a real codebase.
How It Works
- Walk the directory, collect source files by extension
- Sort them by importance (entry points first, config files second, depth third)
- Truncate files that are too long
- Respect .gitignore so you're not sending garbage to the API
- Send the top 25 files to Claude Haiku with a structured prompt
- Write the output to CODEBASE.md
No dependencies. No frameworks. Just Node.js built-ins and a direct call to the Anthropic API. Cost per run: roughly $0.001-0.005.
Building It in One Night
I built this in about 2.5 hours. The hardest part wasn't the code, it was the prompt engineering.
My first attempt asked Claude to "summarize the codebase." The output was generic and useless. What I actually wanted was a document a mentor would write for a new developer on day one.
The prompt that worked: I gave Claude a specific role ("you are a senior software architect helping a developer who just joined a new team"), a fixed output structure with exact headings, and explicit instructions on tone ("direct and useful, no corporate speak").
If you're building AI tools, this is the most important lesson: the intelligence isn't in the infrastructure, it's in the instructions. Getting the prompt right is 80% of the work.
The Larger Pattern
I've been building a lot of small AI tools this year, mostly to automate the parts of development that are genuinely tedious. The tools that actually get used are the ones that fit existing workflows. Developers already use the terminal. codebrief doesn't ask you to change anything. You just run it and it adds something useful to your repo.
If you want to go deeper on building AI tools into your workflow, I've written a detailed breakdown in my AI Agent Automation Blueprint. It covers how to decide when to use AI, how to prompt effectively, and how to build tools that don't get abandoned after a week.
For the full toolkit including prompt packs, content workflows, and agency frameworks, the AI Flywheel Bundle has everything in one place.
Try It
export ANTHROPIC_API_KEY=sk-ant-...
npx github:Android-Tipster/codebrief
Source at github.com/Android-Tipster/codebrief. MIT license.
If you try it, reply with what codebase you ran it on. Curious whether the output holds up across different languages.
Top comments (0)