Building CodeGuide

I have been watching something shift quietly over the past few years, and I am still figuring out how I feel about it. Most of the code we write today is generated by AI — and that is both a remarkable thing and a troubling one.

However, there are aspects of this era I find hard to get comfortable with — the code slopes, the passive learning, the habit of accepting what is generated without really reading it, the quiet bloat that accumulates in a codebase nobody fully owns.

As an engineer who really likes to code and build systems from ground up, I have been a fan of elegantly written code. I have read books like Clean Code - Robert C. Martin, You Don’t Know JS - Kyle Simpson, The Pragmatic Programmer - Andrew Hunt and David Thomas, each one of them have taught me a great deal to write clean and readable code. As one author brilliantly puts it “Writing clean code is an art”, I have been mastering that art and I still do even though I’m an Engineering Manager. I sneak time to build systems.

For a guy like me, when AI is generating code trained on data from the internet — which is already, to put it nicely, a lot of gibberish — accepting code without reviewing is a big mistake that you are doing as an engineer for your team. I don’t blame anyone for this, it is just that we barely had space to establish rules before we adopted AI code generation tools.

When engineers are accepting AI generated code without reviewing, in no time, your codebase gets bloated. At this current pace, onboarding a new engineer to work on your bloated codebase would increase it manifold — in large part because our attention spans have been greatly diminished. The causes of that I won’t go into here; my other blogs on Psychology cover it.

Enter codeguide

That frustration, sitting with me long enough, turned into a small tool I called codeguide.

As the codebase gets bloated, onboarding a new engineer or an engineer who has previously worked on the codebase should not find it daunting to understand the codebase. So I built codeguide to gamify the whole process.

Even though there are many competitors in this landscape, my focus is very different from theirs. And most importantly, this is not a SaaS product, it is a free, open-source tool.

Getting Started

When you install codeguide using npm like

npm install @vastoria-ai/codeguide

The commands will be available in your Claude/Codex session, you don’t have to configure any API keys or setup a different process.

The codeguide needs to be initialised first, when executing codeguide init inside your Claude/Codex session or even outside the session. It scans your entire repository, indexes the modules and files, and writes to the codeguide-out directory with INDEX.md, STRUCTURE.md, GRAPH_REPORT.md.

You can add this codeguide-out directory to version control SCM like git, to save your precious tokens

After it is initialised, run codeguide install to append the codeguide instructions to your CLAUDE.md, AGENTS.md directives & registers the PreToolUse hook. This will tell your agent to update the index while the code is being generated.

Touring the Codebase

Now you are ready to tour the codebase with the help of AI. Open a Claude/Codex session and run /codeguide tour

Here the agent (Claude/Codex) reads the committed index and gives a structured orientation.

Missions and Ask

With the high-level understanding of the codebase, I can dive deeper with the suggested mission in an interactive mode. If I want to understand components in this project codebase. I can run

/codeguide mission components

The mission is saved as a .md file in the codeguide-out directory, so make sure to commit this to your SCM. This will act as the onboarding document to new engineers.

It also has an ask command, codeguide ask, where you can prompt your question about the codebase and get answers via the indexed files.

Conclusion

As the codebase increases exponentially, having a system to onboard new engineers to your codebase with the right tools becomes key to a successful engineering team. If not, we just accept AI generated code, with all the code slopes and end up in a situation where it would be impossible to debug an issue because we failed to understand and review the code AI generated.

I am still building this. There is more I want to add — a UI for those who prefer it, support for more languages, and ideas I haven’t thought of yet. If something here speaks to a problem you’ve felt on your team, I’d welcome you being part of it.