Explain This Project

Make sense of any codebase in seconds.

Ever opened a project and felt lost? This extension helps you understand any code project instantly. Just run one command and get a clear, comprehensive overview of what you're looking at.

What Does It Do?

Explain This Project creates a friendly overview document that tells you everything you need to know about a project:

• What kind of project it is — web app, library, API, etc.
• What technologies it uses — React, Python, TypeScript, and more
• How the files are organized — see the folder structure at a glance
• Plain-English summary — AI-powered explanation of what the project does
• Git insights (NEW!) — see which files change most often, who the top contributors are, and where bugs tend to happen
• Ask Questions — chat with AI about the project to learn more

Key Features

Complete Project Analysis (Works Offline!)

The extension scans your project automatically to find:

• Programming languages and frameworks
• Main entry points and configuration files
• Directory structure and file organization
• Dependencies and packages

Git History Insights (NEW in v0.3!)

For projects using Git, you'll also get:

• Churn Hotspots — files that change most frequently (might need refactoring!)
• Bug Clusters — files with the most bug fixes (watch out for these!)
• Top Contributors — who's been working on the project recently
• Commit Activity — visual chart showing project momentum
• Stability Metrics — count of reverts and emergency fixes

AI-Powered Understanding

Get a plain-English summary of what the project does, written by GitHub Copilot or OpenAI. No technical jargon required!

Interactive Q&A

Not sure about something? Ask questions in natural language and get instant answers based on your project.

Multi-Language Support

Works with JavaScript, TypeScript, Python, Rust, Go, PHP, Java, C#, C++, and many more!

How to Use

Using the extension is super simple:

1. Open a project folder in VS Code (any project works!)
2. Press Cmd+Shift+P on Mac or Ctrl+Shift+P on Windows/Linux
3. Type "Explain This Project" and press Enter
4. Wait a few seconds while it analyzes everything
5. Check your project root — you'll find a new PROJECT_OVERVIEW.md file

That's it! Open the file to see a complete breakdown of your project.

Available Commands

💡 Tip: If the AI summary is taking too long, just click "Cancel" in the progress notification. You'll still get the complete analysis, just without the AI-generated summary at the top.

Installation

Option 1: VS Code Marketplace (Easiest)

1. Open VS Code
2. Click the Extensions icon on the left sidebar (or press Ctrl+Shift+X / Cmd+Shift+X)
3. Search for "Explain This Project"
4. Click the Install button

Option 2: Install from File

If you have a .vsix file, open a terminal and run:

code --install-extension explain-this-project-[VERSION].vsix

Example Output

Here's what a typical PROJECT_OVERVIEW.md looks like:

# Project Overview

## AI Summary

This is a modern web application built with React and TypeScript.
It uses Next.js for server-side rendering and includes a REST API
powered by Express. The project follows best practices with ESLint
for code quality and has a comprehensive test suite...

---

## Basic Information

**Name:** my-awesome-app
**Type:** Web Application
**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.2
- Next.js 14
- Express 4.18

## Entry Points

- `pages/index.tsx`
- `server/index.ts`

## 📁 Directory Structure

src/
├── components/
│   ├── Header.tsx
│   └── Dashboard.tsx
├── api/
│   └── users.ts
└── utils/
    └── helpers.ts

## Dependencies

react, next, express, typescript...

---
*Generated by Explain This Project*

The AI Summary section only appears if you have GitHub Copilot or OpenAI configured. If not, you'll still get all the other great analysis!

🤖 Understanding the AI Features

AI Summary in Your Overview

When you run the analysis, the extension can add a friendly summary at the top that explains what your project does in plain English.

What gets sent to AI? Only the structured overview text (file names, dependencies, structure). Your actual source code is never transmitted.

What if it takes too long? The summary request times out after 30 seconds by default. If that happens, or if you click "Cancel," you'll still get the complete analysis — just without the AI summary at the top.

Ask Questions Feature

After generating an overview, you can run the "Ask Questions" command to start an interactive conversation. Examples:

• "What does this project do?"
• "Where should I start reading the code?"
• "Which files handle authentication?"
• "How do I run this project?"

Type "exit" when you're done chatting.

Requirements: You need either a GitHub Copilot subscription (default) or an OpenAI API key.

⚙️ Settings & Customization

You can customize how the extension works through VS Code settings. Go to Settings (Cmd+, / Ctrl+,) and search for "Explain This Project".

Quick Settings Guide

Example Configuration

Here's a sample settings configuration:

{
  "explainThisProject.llmProvider": "copilot",
  "explainThisProject.aiSummaryTimeoutSeconds": 30,
  "explainThisProject.includeDevDependencies": true,
  "explainThisProject.maxDirectoryDepth": 3,
  "explainThisProject.excludeDirectories": [
    "node_modules",
    ".git",
    "dist",
    "build",
    "coverage"
  ]
}

💡 Tip for Large Projects: If analysis is slow, try reducing maxDirectoryDepth to 2 or adding more folders to excludeDirectories.

Supported Languages & Technologies

The extension recognizes a wide variety of programming languages and can identify popular frameworks automatically:

Don't see your language? The extension still works! It might not detect specific frameworks, but it will show you the file structure and basic project info.

Requirements

• VS Code version 1.105.0 or higher
• An open workspace folder (File → Open Folder)
• Optional: GitHub Copilot subscription for AI features (analysis works without it!)
• Optional: Git installed to get the git history insights

Troubleshooting

Can't find the command in the Command Palette? Make sure you have a folder open, not just a single file. Go to File → Open Folder and select your project folder.

No AI Summary in the output? This is normal if:

• You don't have GitHub Copilot enabled
• The request took longer than 30 seconds
• You clicked "Cancel" during analysis
• Your workspace is offline

The full analysis is still generated — just without the AI summary at the top!

The extension is slow on my project Try these fixes:

• Lower the Max Directory Depth setting to 2 or 1
• Add build folders to Exclude Directories (like dist, build, .next)
• Make sure node_modules and .git are excluded

Git insights aren't showing up This happens when:

• Your project isn't a Git repository
• Git isn't installed on your computer
• You're in a non-root folder of the repository

This is totally fine — the extension will just skip the git analysis and show everything else!

About the Author

Explain This Project is created and maintained by Peter Benoit.

If you find this extension helpful, consider:

• Starring the GitHub repository
• Writing a review on the VS Code Marketplace
• Reporting issues or suggesting features on GitHub

Want to contribute? Check out the Contributing Guide!

License

MIT License — See LICENSE for details.

Links

• Author Website: peterbenoit.com
• GitHub Repository: github.com/peterbenoit/explain-this-project
• Report Issues: GitHub Issues
• VS Code Marketplace: marketplace.visualstudio.com