Codebase Notebook

Codebase Notebook is a VS Code extension for keeping structured notes about a codebase and connecting those notes back to the code they describe.

I made it for the moments where understanding the code is the actual work. Maybe i am investigating a bug, learning how an unfamiliar project works, reviewing a large feature, or trying to remember why something was implemented in a very specific way. Normal comments are useful, but they are not always the right place for the complete story.

Notes that stay close to the code

Each note can reference specific files and line numbers. From the note i can jump back to the code, and from the editor i can see which notes reference the current file.

The extension watches for changes and updates line numbers when the code moves. It can also detect references that became stale or broken after a file was moved or deleted. This makes the notes more useful over time, instead of becoming another document that nobody trusts after a couple of refactors.

Markdown first

The notes are readable Markdown files. There is no special database and the project does not need to depend on an external service just to keep its documentation.

They can be stored globally for personal research, or inside a .codenotes/ directory in the repository. Workspace notes can be committed with the code and shared with the rest of the team using the tools that are already part of the development workflow.

Notes can also be organized with tags, templates, pinned references, archives and comments. For larger investigations, the reference graph gives another way to see how notes and files connect.

Optional AI helpers

AI is there as an optional layer, not as the place where the notes live. It can help generate an annotation from selected code, summarize a note, find related references, search annotations using natural language, or check whether an explanation might be stale.

The extension can use the VS Code Language Model API, or an external OpenAI-compatible endpoint such as OpenAI, Anthropic or Ollama. Without an AI provider, the normal Markdown notes, references, navigation and organization tools still work.

The useful small interactions

The extension includes shortcuts for quickly adding an annotation without interrupting the current train of thought. References can be added in bulk, reordered, pinned and opened directly from the sidebar. CodeLens and hover previews make the notes visible when i return to the code later.

It also includes a chat participant for questions about the current notebook, annotation history, a chronological timeline and tools for surfacing relevant notes during code review.

Codebase Notebook is an experiment in keeping the context around a codebase as portable as the code itself. The notes stay human-readable, the references make them practical inside the editor, and the optional automation is there to make documenting easier without taking ownership of the documentation away from me.

The extension is available from the VS Code Marketplace, and its source is available in the GitHub repository.