Explain Codebase

Static-analysis CLI for mapping repository architecture, dependencies, entry points, side effects, and change risk.

explain-codebase helps you find where execution starts, which files are central, how source files depend on one another, and where a change is likely to have the widest impact. It reads source files without importing or running the target project.

Quick start

Install from PyPI and inspect the current directory:

python -m pip install explain-codebase
explain-codebase .

For an isolated command-line installation, use pipx:

pipx install explain-codebase
explain-codebase .

The default view is intentionally compact:

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

Repository

  Path        C:\Projects\checkout-service
  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

What it shows

• likely application entry points
• central modules ranked by dependency usage
• relative and package import relationships
• probable execution paths
• files that interact with databases, networks, filesystems, or caches
• common architecture areas such as services, repositories, routes, and controllers
• large files, highly connected files, circular dependencies, and risky change points
• a suggested reading order for onboarding
• focused dependency graphs and an HTML architecture report

The results are heuristic signals intended to shorten initial investigation. Default rankings focus on application source: files below tests, fixtures, and examples remain available in the complete file graph but do not distort entrypoint, centrality, hotspot, or risk rankings.

These signals are not a substitute for reading critical code paths or running the target project's own checks.

Installation

Requirements

• Python 3.10 or newer
• Git when inspecting a public GitHub repository
• network access for remote repository checks and cloning

From PyPI

python -m pip install explain-codebase

Isolated CLI installation

pipx install explain-codebase

Local development

python -m pip install -e ".[dev]"

Usage

Common commands

--verbose and --deep cannot be combined.

Graph views

--graph writes dependency_graph.html. --report writes codebase_report.html. Both files are written to the current working directory.

The interactive graph starts from deterministic node positions with a restrained ambient pulse and directional edge flow. Selecting a node highlights its direct dependencies without restarting the layout, while search and filters keep the remaining nodes in place.

Nodes can be dragged into a more useful arrangement. When a dropped node overlaps another, a bounded local collision pass gently separates only the nearby nodes involved; it never restarts global layout physics. Tiny pointer movement during an ordinary click is ignored.

Choose at most one graph-view flag. A graph-view flag requires --graph or --report.

Examples:

explain-codebase . --graph --architecture
explain-codebase . --graph --entrypoint
explain-codebase . --report --risk
explain-codebase . --graph --full

Supported source formats

Import resolution keeps Python, JavaScript, and TypeScript candidates separate, accounts for relative paths and package entry files, and recognizes conventional root-level Python src/ package layouts where those relationships can be determined statically.

Scanning behavior

For a local directory, the scanner:

• considers only the supported source extensions
• keeps resolved file paths inside the selected repository
• honors the optional parsed-file limit and a 1 MiB per-file size limit
• skips common dependency, cache, build, coverage, and environment directories
• respects the root .gitignore file
• reads tracked and untracked non-ignored files from a Git worktree when Git metadata is available, then falls back to filesystem scanning if Git is unavailable
• handles unreadable source files safely and skips unsupported or oversized files

Use --max-files to lower the number of files parsed for a focused run. Application files are selected before tests, fixtures, and examples. Results report whether that limit truncated the analysis, along with discovered, skipped, Python syntax-error, and unresolved-local-import counts.

Public GitHub repositories

Pass a public repository URL in the canonical form:

explain-codebase https://github.com/owner/repository

The CLI checks public repository metadata, asks for confirmation, performs a limited clone in a temporary directory, analyzes the clone, and removes the temporary directory afterward. Private repositories, other hosting providers, and arbitrary Git URLs are not supported.

Remote inspection requires an interactive terminal, Git, and network access. Clone timeouts can stop remote preparation, and oversized source files are skipped during analysis.

Output and automation

Standard output and error output

Human-readable output and JSON are written to stdout. Progress stages, warnings, and errors are written to stderr. This keeps JSON suitable for redirection:

explain-codebase . --json > architecture.json

CI mode

explain-codebase . --ci

CI mode exits with status 0 when no architecture issues are found and status 1 when an issue is detected. Current issue checks include circular dependencies and utility-style god modules. Thresholds are built into the CLI.

JSON

JSON output includes repository information, entry points, central modules, side-effect files, architecture areas, large files, hotspots, risky files, architecture issues, execution paths, and paths to optional HTML outputs.

Coverage is explicit: truncated reports whether --max-files omitted supported files, while discovered_files, skipped_files, Python parse_errors, and unresolved_imports make partial results visible to scripts and CI jobs.

How it works

At a high level, explain-codebase:

1. resolves and validates the target
2. selects supported source files within safety boundaries
3. parses static imports and source-level signals
4. resolves imports and builds a dependency graph
5. ranks central modules and identifies entry points, side effects, hotspots, and architecture issues
6. renders the selected CLI, JSON, graph, or report output

The target project's source code is not imported or executed during analysis.

Limitations

• Dynamic imports, reflection, runtime dependency injection, and framework-specific wiring may not be visible.
• Custom path aliases and build-tool transformations may reduce import-resolution accuracy.
• Syntax that is valid only after a separate transform step may be skipped.
• Minified, vendored, mirrored, or highly repetitive code can reduce signal quality.
• Large monorepos should use --max-files or analyze a narrower directory.
• Remote analysis supports only public GitHub repositories.
• A shallow remote clone can still transfer large files because total repository download size is not capped.
• Interactive HTML views load a version-pinned, integrity-checked graph library from a public CDN and need network access when opened.

Development

Install the development tools and run the checks:

python -m pip install -e ".[dev]"
ruff check .
pytest
python -m build
python -m twine check --strict dist/*

Project information

• Changelog
• Security policy
• Issue tracker
• PyPI package

License

Licensed under the MIT License.