DEV Community

NewsMan
NewsMan

Posted on

Show HN: Badge that shows how well your codebase fits in an LLM's context window

#ai #technology #productivity #aitools

Alright, let's talk about something I just spotted that's genuinely interesting for us Indie Hackers. Forget the latest "AI-powered" todo list app. This one actually tackles a real, emerging problem.

The Hook

Remember when "small codebase" was just a nice-to-have? Something your senior dev might grumble about if you bloated things up? Well, that's officially old news. With coding agents—those AI brainiacs we're all playing with—a small codebase isn't just "good," it's becoming a superpower. If your entire project fits into an LLM's context window, that agent can understand and reason about your entire stack at once. That's a massive advantage.

And someone just dropped a simple, brilliant little tool called Repo Tokens that tells you exactly how "AI-friendly" your codebase is. It's a GitHub Action that slaps a badge on your README, showing you how much of an LLM's context window your code eats up. Green for good, red for "your AI agent is gonna choke."

How It Works

It's deceptively simple. This thing is a GitHub Action. You add it to your repo's workflow. What does it do?

  1. It grabs your entire codebase.
  2. It uses tiktoken (the same library OpenAI uses) to count how many "tokens" your code would take up if an LLM read it.
  3. It then compares that token count to a typical LLM context window size. The default is set to 200k tokens, which is what Claude Opus can handle. You can configure this if you're targeting a different model.
  4. Finally, it updates a badge in your README.md.
    • Green: Under 30% of the context window. Your AI agent is happy.
    • Yellow-Green: 30-50%. Still good.
    • Yellow: 50-70%. Getting a bit chunky.
    • Red: 70%+. Houston, we have a bloat problem. Your AI agent is going to need multiple passes, or miss crucial context.

It's basically a visual health meter for your codebase's AI digestibility.

The Lazy Strategy

This is the best part: it's a GitHub Action, so integration is dirt simple.

  1. Add the Action: Create a .github/workflows/repo-tokens.yml file (or add to an existing one). The action itself is a composite action, running about 60 lines of inline Python, so it's lean and fast (~10 seconds).

  2. Mark your README: In your README.md, you just drop some HTML comment markers where you want the badge and token count to appear:

    <!--repo-tokens-action-start-->
<!--repo-tokens-action-end-->

    The action will replace whatever's between those markers with the badge and token count.

That's it. The action runs, updates the README, but doesn't commit. You'll need to configure your workflow to commit the changes back to your repo if you want the badge to persist. This gives you control, which is nice.

The Reality Check

Look, I'm excited about this, but let's not get carried away.

  1. Moving Target: LLM context windows are expanding faster than my waistline after a pizza binge. 200k tokens is huge today, but what about next year? Will this badge become obsolete? Probably not entirely, but the "green" threshold might shift. It's more about the relative size.
  2. Bloat isn't always evil: Some projects need to be big. A complex enterprise system isn't going to fit into 200k tokens, and that's okay. This tool is probably best for microservices, side projects, libraries, or new ventures where you can control the scope.
  3. It's a metric, not a solution: This badge is a warning light, not an automatic bloat-remover. You still need to be disciplined about your code, refactor, and keep things tight. It just gives you a visual nudge.
  4. What about external dependencies?: It counts your code. It doesn't count the mental load of all the external libraries and frameworks you're pulling in, which also contribute to complexity an AI agent needs to grasp.

The Verdict

YES, it's absolutely worth trying.

For any new project, microservice, or even a personal library, this is a fantastic "code health" metric. It nudges you towards writing more concise, focused code, which has always been good practice, but now has a direct, measurable benefit for AI agent collaboration.

Think of it as a friendly little guardian on your README, whispering "keep it tight, champ" every time you push code. The easier your codebase is for an LLM to digest, the faster and more accurately those AI agents can help you build, debug, and iterate. And for us Indie Hackers, speed and iteration are everything. Go green!

🛠️ The "AI Automation" Experiment

I'm documenting my journey of building a fully automated content system.

  • Project Start: Feb 2026
  • Current Day: Day 20
  • Goal: To build a sustainable passive income stream using AI and automation.

Transparency Note: This article was drafted with the assistance of AI, but the project and the journey are 100% real. Follow me to see if I succeed or fail!

Top comments (0)