VS Code Extension v0.3.0 MIT License Open Source

Explain This Project

A VS Code extension that analyzes any open codebase and generates a structured PROJECT_OVERVIEW.md at the project root. Detects languages, frameworks, entry points, directory structure, and git history insights. Core analysis is entirely offline. Optionally uses GitHub Copilot or OpenAI to add a plain-English narrative summary.

Install from Marketplace View Source

The Problem

Every developer has opened an unfamiliar repository and immediately felt lost. The questions are always the same:

  • ▸What does this project actually do?
  • ▸Where does execution start?
  • ▸Which framework is this using?
  • ▸What are the non-obvious dependencies I should know about?

The answers live scattered across package.json, requirements.txt, Cargo.toml, and folder structures. Reading all of that on a fresh checkout takes time that should go toward actual work. This extension eliminates that friction and produces an artifact you can commit alongside the code so the next developer has it ready immediately.

How It Works

A multi-stage analysis pipeline runs entirely on your local machine:

File System Walk

Recursively scans the workspace from the root, respecting configurable depth and exclude-directory settings.

Manifest Parsing

Reads package.json, Cargo.toml, go.mod, pyproject.toml, and more to extract dependencies and metadata.

Framework Detection

Matches dependency names and config files against known patterns. React, Vue, Django, Laravel, Express, and many more.

Entry Point Detection

Identifies likely entry files using common conventions: src/index.ts, main.go, app.py, and others.

Source Tree Rendering

Finds the primary source directory and renders it as a depth-limited ASCII tree, directories sorted before files.

Git History Analysis

When a git repository is present, adds churn hotspots, bug cluster signals, top contributors, commit momentum, and stability metrics.

AI Narrative Summary

Optionally sends the generated markdown to GitHub Copilot or OpenAI for a plain-English summary. Steps 1–6 run fully offline. AI is best-effort and skipped on timeout.

Commands

All commands are available via the Command Palette (Cmd+Shift+P) under the Project Analysis category.

Explain This Project

The primary command. Runs the full analysis pipeline and writes PROJECT_OVERVIEW.md to the workspace root. Prompts to overwrite if the file already exists. The progress notification is cancellable. Clicking Cancel skips the AI summary and writes the static overview immediately.

Explain This Project (Force Overwrite)

Identical to the primary command but silently overwrites any existing PROJECT_OVERVIEW.md without prompting. Useful for re-running analysis after the project has changed.

Explain This Project: Ask Questions

Opens an interactive Q&A session powered by an LLM. Loads the existing PROJECT_OVERVIEW.md as grounding context for the conversation. The agent runs in a loop until you type exit.

Example questions

  • ▸"What does this project do?"
  • ▸"Which parts of the code handle authentication?"
  • ▸"What would I need to change to add a new API endpoint?"

Example Output

Run the command in any open folder and you'll get a PROJECT_OVERVIEW.md like this: 

# Project Overview

## 🤖 AI Summary

A server-rendered e-commerce application built on Next.js with a Stripe
integration. Uses TypeScript throughout and Prisma for database access.

---

## Basic Information

**Name:** my-app
**Version:** 1.2.0
**Type:** Application (Build-enabled)
**Primary Language:** TypeScript

## Git Activity (Last 12 Months)

**Churn Hotspots** (files that change most):
- src/api/users.ts (47 changes)
- src/components/Dashboard.tsx (32 changes)
- src/utils/helpers.ts (28 changes)

**Top Contributors:**
- Sarah Johnson (143 commits)
- Mike Chen (98 commits)
- Alex Rivera (76 commits)

**Commit Activity:** ▁▂▃▅▆█▇▆▅▄▃▂ (trending up!)

## Frameworks & Libraries

- React 18
- Express 4
- Prisma

## Entry Points

- `src/index.ts`
- `src/server.ts`

## 📁 Source Structure

src/
├── index.ts
├── server.ts
├── components/
│   ├── Header.tsx
│   └── Footer.tsx
└── routes/
    └── api.ts

---
*Generated by Explain This Project: 2026-03-26T12:00:00.000Z*

The AI Summary section is omitted when Copilot is unavailable, the request times out, or you click Cancel.

Configuration

All settings are under the explainThisProject namespace. Configure in VS Code Settings or .vscode/settings.json. 

{
  "explainThisProject.llmProvider": "copilot",
  "explainThisProject.openaiApiKey": "",
  "explainThisProject.aiSummaryTimeoutSeconds": 30,
	"explainThisProject.includeGitAnalysis": true,
  "explainThisProject.includeDevDependencies": true,
  "explainThisProject.maxDirectoryDepth": 3,
  "explainThisProject.excludeDirectories": [
    "node_modules", ".git", "dist", "build", "coverage"
  ]
}
Setting Type Default Description
llmProvider "copilot" | "openai" "copilot" Which LLM backend to use for AI summary and Ask Questions
openaiApiKey string "" OpenAI API key. Required only when llmProvider is "openai". Set in user settings, never workspace settings.
aiSummaryTimeoutSeconds number (5–120) 30 How long to wait for the AI summary before skipping it and writing the static file anyway
includeGitAnalysis boolean true Include git history analysis in the output when a repository is available
includeDevDependencies boolean true Whether to include devDependencies in the analysis output
maxDirectoryDepth number (1–10) 3 Maximum depth for the file system walk
excludeDirectories string[] ["node_modules", ...] Directory names to skip entirely during the walk

Language & Framework Support

Fully Analyzed (manifest-based)

Language Manifest
JavaScript / TypeScript package.json
Python requirements.txt, pyproject.toml
Rust Cargo.toml
Go go.mod
PHP composer.json

Basic Detection (file extensions)

  • ▸Java
  • ▸C#
  • ▸C++
  • ▸C

Detected by source file extensions. No manifest parsing is performed for these languages.

JS/TS Framework Detection

React, Vue, Svelte, Next.js, Nuxt, Angular, Express, Fastify, NestJS, Vite, Webpack, Jest, Vitest, and more.

Who It's For

  • ▸Developers inheriting a codebase. Get oriented in minutes, not hours
  • ▸Open-source contributors. Understand a repo's structure before a first commit
  • ▸Freelancers and contractors who need to scope a client project quickly on first review
  • ▸Tech leads who want living documentation to share with new team members
  • ▸Code reviewers who need context on an unfamiliar repo before reviewing a PR

Requirements

  • ▸VS Code 1.105.0 or later
  • ▸An open workspace folder in VS Code (not just a single file)
  • ▸GitHub Copilot subscription for AI features when using the default provider
  • ▸OpenAI API key for AI features when llmProvider is "openai"
  • ▸Git installed for git history insights. If git is unavailable, the extension skips that section and still generates the rest of the overview

Static analysis (without AI summary) works entirely offline. No account or API key required.

Privacy

The core analysis runs entirely on your machine. No source code is ever transmitted to any external service.

  • ▸Git analysis reads local commit metadata only and does not upload repository history anywhere
  • ▸Steps 1–6 of the pipeline have zero network activity
  • ▸When AI summary is enabled, only the generated markdown is sent to the LLM. Not your raw source files
  • ▸AI summary is best-effort: any timeout or error silently falls back to the static-only document
  • ▸Set openaiApiKey in user settings, not workspace settings, to avoid committing it

Get Started

Install from the VS Code Marketplace. Free, open source, no account required for the core analysis.

Install Free on Marketplace GitHub