Codebase Explorer

Codebase Explorer turns an unfamiliar repository into a guided onboarding experience inside VS Code.

It is built for developers who want to understand a codebase quickly without reading files in directory order.

Features

• Overview: a modern Markdown reading surface for architecture notes, key modules, and system context
• Core Flows: visual paths through the most important runtime behavior in the codebase
• Source Cards: Cursor-style file references for jumping from explanation to code
• Rich Code Blocks: highlighted snippets embedded directly in the reading experience
• Mermaid Architecture Views: architecture diagrams rendered inline
• Ask Claude: continue investigating the current step in your terminal with the current node context prefilled

Requirements

• VS Code or Cursor
• Claude Code available in your terminal for the handoff action
• The companion explore-codebase skill installed in Codex

Install the Companion Skill

Codebase Explorer depends on a companion Codex skill named explore-codebase.

The best installation model is the same pattern used by other Codex skills: publish the skill in a GitHub repository and install it with Codex's GitHub-based skill installer, then restart Codex.

Example installation flow after the skill is published:

python ~/.codex/skills/.system/skill-installer/scripts/install-skill-from-github.py --url https://github.com/ayo4code/Codebase-Explorer/tree/main/code-expolorer-skills

Then restart Codex so the new skill is loaded.

If you are preparing this extension for Marketplace release, publish the companion skill first and replace <owner>/<repo> with the real repository location before shipping this README.

How to Use

1. Install the companion explore-codebase skill
2. Restart Codex
3. Open your target repository
4. Ask Codex to run explore-codebase for that repository
5. Open the Codebase Explorer activity bar view
6. Start with Overview
7. Open a flow under Core Flows
8. Click a node to inspect Markdown explanations, code snippets, source references, and follow-up context
9. Use Ask Claude when you want to continue the investigation in your terminal

What the Experience Feels Like

Codebase Explorer is designed as a reading and navigation tool, not a raw graph viewer.

Instead of flooding the screen with dependency data, it helps you move between:

• architecture context
• guided runtime flows
• focused code snippets
• module summaries
• direct source jumps
• follow-up investigation in Claude Code

Development

cd codebase-explorer-vscode
npm install
npm test
npm run build

Press F5 in VS Code to launch an Extension Development Host.

Current Scope

Codebase Explorer is currently aimed at:

• onboarding-oriented repository summaries
• Markdown-first architecture and flow explanations
• Mermaid-backed architecture views
• curated flow diagrams with supporting code context
• source navigation and terminal handoff for deeper investigation
• report-driven rendering from .codebase-explorer/report.json

Out of scope for now:

• editing onboarding content from the extension
• monorepo-specific navigation models
• built-in codebase analysis inside the extension