CodeGuide – Explain Code in Plain Words
CodeGuide helps you understand code you didn't write: a new job, an open-source project, or a language you haven't learned yet.
Click the CodeGuide icon in the activity bar (the column of icons at the side of VS Code), then open any file. It explains whichever file you're looking at, and follows you as you switch files. You can also right-click a file and choose Explain This File. The view shows:
- What this file is: its role in plain English, such as "DTO (data transfer object)", "Controller", "Vue component" or "Database migration", and why CodeGuide thinks so.
- When does this run?: follows the code up to the things a person would recognise: the web requests that use it (
GET /jobs/{id}), the pages that show it (/inspections/add), timers (every hour), start-up and tests. For example: "This code can run as part of 8 web requests and every hour", with the chain it followed (via JobDto).
- What's in it: one plain sentence, such as "1 class (AddressDto) with 6 properties. It only holds data and has no functions.", and an outline with types. Click a name to jump to it, or a type such as
AppUserDto to open the file that declares it.
- Builds on: the classes and interfaces this code inherits from or promises to follow, with links to where they're defined.
- Used by: which other files use this one, how many times, and the line that uses it.
- Brings in: the namespaces, modules and packages this file imports.
- Code words: every language feature in the file, such as
async/await, ??, => or [Attribute], explained in one or two plain sentences. Click I know this and that word is hidden from then on, in every project.
Hover help: point at a language word in the editor, such as ??=, async or [Required], and a tooltip explains it.
Learn this project: the second tab builds a reading order for the whole project. It starts with the start-up file, then the controllers and pages, the rules, the data, and the building blocks everything relies on. Tick off each file as you read it. CodeGuide remembers your progress, and a banner on each file takes you to the next one.
Project map: the third tab draws the project as a flow chart. It groups the files by what they do, in layers from the ways in (pages, controllers, timers, start-up) down to the rules, the data access, the data and the database. Arrows show which kind of code uses which, and how many files do, for example Controllers → Services: 11 files. Click a box to see its files. Open the full chart shows the whole diagram in an editor tab. In a repository that holds several projects, choose which part to map.
Select a few lines and choose Explain Selection to get help for just that code.
All of this is free, works offline, and never sends your code anywhere. The first time you open a project, CodeGuide maps it in the background, which takes a few seconds for a large project.
Optional: plain-English summaries from AI
If you already have an AI in VS Code, CodeGuide can also write a short explanation of what the code does and when it runs. You don't need an API key, and nothing is sent until you click Explain with ….
| You have |
What happens |
Cost |
| GitHub Copilot |
CodeGuide asks Copilot through VS Code. VS Code asks your permission the first time. |
Copilot's free plan works, within its monthly limit. |
| Ollama running on your computer |
CodeGuide asks your local model. The code stays on your computer. |
Free. Needs a reasonably powerful computer and a one-time model download, e.g. ollama pull qwen2.5-coder. |
| Neither |
You get everything above except the AI summary. |
Free |
AI answers come back in VS Code's display language. You can choose another with the codeguide.explanationLanguage setting.
Languages
| What |
Languages |
| Outline, "Used by", "Builds on" |
Read by CodeGuide itself for C#, Java, JavaScript, TypeScript, React, Vue, Python, Go and PHP, with no other extension needed. For any other language, CodeGuide uses that language's VS Code extension if you have it. |
| "What this file is" |
Any language. It uses common naming and folder conventions. |
| "When does this run?" |
ASP.NET (controllers, minimal APIs, Hangfire timers, hosted services), Spring, Express, NestJS, Flask, FastAPI, Django, Go net/http, gin and echo, Laravel, Symfony, Vue Router and React Router |
| "Brings in" |
C#, JavaScript, TypeScript, Vue, Python, Java, Kotlin, Go, PHP, Rust, Swift, Ruby, Dart, C, C++ |
| Code words |
C#, JavaScript, TypeScript, React (JSX/TSX), Vue, Python, Java, Go, PHP |
When a language extension is installed (for example C# Dev Kit, Pylance or Volar), CodeGuide uses it for exact results, the same information as Go to Definition and Find All References. Without one, "Used by" searches the project's files for the names this file declares.
Settings
| Setting |
Default |
What it does |
codeguide.ai.provider |
auto |
auto uses Copilot if it's available, otherwise Ollama. copilot or ollama uses only that one. off never uses AI. |
codeguide.ollama.url |
http://localhost:11434 |
Where your Ollama server is. |
codeguide.ollama.model |
(empty) |
Which Ollama model to use. If empty, CodeGuide picks an installed one, preferring coding models. |
codeguide.explanationLanguage |
auto |
The language AI answers are written in, for example Hindi or Spanish. |
codeguide.hover |
true |
Explain language words when you point at them in the editor. |
codeguide.whenDoesThisRun |
true |
Follow each file up to the web requests, pages and timers that use it. |
codeguide.followActiveEditor |
true |
Explain each file as you open it, while the CodeGuide view is visible. |
codeguide.findUsages |
true |
Look up which files use this one. Turn it off if it feels slow in a very large project. |
Privacy
- Without AI, CodeGuide reads only the files in your open workspace and talks to nothing outside your computer. Its project map is kept in memory and isn't written anywhere.
- With AI, the file or selection is sent only when you click the button. It goes to GitHub Copilot or to your own Ollama server, whichever is named on the button.
- CodeGuide collects no telemetry.
Building from source
npm install
npm test # compiles and runs the unit tests
npm run test:vscode -- C:/code/my-app # runs CodeGuide in a clean copy of VS Code against a real project
npm run package # creates codeguide-<version>.vsix
Run test:vscode from an ordinary terminal. When it's started from inside VS Code's own processes, the test copy of VS Code can inherit settings that stop it opening a window.
To try it in VS Code, open this folder and press F5. That starts a second VS Code window with the extension loaded.
License
MIT. See the LICENSE file that comes with the extension.
| |
