explain-codebase 0.1.2

CLI tool for explaining unfamiliar codebases.

Explain Codebase

CLI tool that analyzes any repository and explains its architecture, entrypoints, dependencies, and impact of changes.

explain-codebase analyzes a repository and helps developers understand unfamiliar projects faster by showing how the system is structured and where execution likely starts.

It works with both local folders and public GitHub repositories.

---

Why

When opening a new repository, it is often unclear:

• where the application starts
• which modules are central
• which files interact with external systems
• what files are risky to modify

explain-codebase scans the project, builds a dependency graph, detects architectural signals, and produces a compact CLI overview that helps you understand the codebase faster.

---

Installation

pip install explain-codebase

For local development:

pip install -e .[dev]

Quick Start

Analyze the current repository:

explain-codebase .

Verbose architecture output:

explain-codebase . --verbose

Deep architecture analysis:

explain-codebase . --deep

Analyze a GitHub repository:

explain-codebase https://github.com/user/repo

Example Output

Explain Codebase
--------------------------------

Repository

  Path        C:\Projects\orders-api
  Type        Python backend service
  Language    python
  Files       7

Architecture

  Entrypoints        1
  Core modules       5
  Side effects       4

Suggested starting point

  api_server.py

Run with --verbose to see full architecture

Verbose mode provides a deeper architecture view:

Execution flow

api_server.py
|- routes/order_routes.py
|- services/order_service.py
|  |- repositories/order_repository.py
|  \- clients/warehouse_client.py
\- middleware/auth_guard.py

Features

• Analyze local folders and public GitHub repositories
• Detect project language and project type
• Detect entrypoints automatically
• Rank core modules by dependency usage
• Infer likely execution flow
• Detect modules that interact with database, network, filesystem, or cache
• Detect architecture folders such as services, repositories, routes, and models
• Detect large modules and highly coupled files
• Detect architecture smells such as circular dependencies
• Generate dependency graph visualizations
• Generate HTML architecture reports
• Explain a single file in project context
• Suggest onboarding reading paths
• Support CI mode for architecture checks

Common Commands

Analyze a repository:

explain-codebase .

Verbose architecture output:

explain-codebase . --verbose

Deep architecture analysis:

explain-codebase . --deep

Suggest a reading order for a new developer:

explain-codebase onboarding .

Explain a single file:

explain-codebase file src/services/order_service.ts

Generate a dependency graph:

explain-codebase . --graph

Generate an HTML architecture report:

explain-codebase . --report

Run in CI mode:

explain-codebase . --ci

Remote Repositories

You can analyze a public GitHub repository directly:

explain-codebase https://github.com/user/repo

The tool will:

1. Resolve the repository
2. Check that it exists and is publicly accessible
3. Ask for confirmation before cloning
4. Clone it into a temporary workspace
5. Run the analysis
6. Remove the temporary workspace automatically

Output Modes

Default mode shows a compact overview:

explain-codebase .

Verbose mode shows the full architecture structure:

explain-codebase . --verbose

Deep mode focuses on architecture risks and potential issues:

explain-codebase . --deep