pyCodeMap 🗺️

A real-time TUI for visualizing source code diagrams with AI-powered architectural summaries.

Overview

pyCodeMap helps you design, understand, and explore any Python codebase. It generates a live call graph that updates as you write code, complemented by an executive summary generated by Gemini AI.

Features

• Live Call Graph: Real-time visualization of function calls and class dependencies.
• AI Summary: Automated architectural overviews using Gemini 1.5 Flash.
• Interactive Navigation: Filter diagrams by selecting files or directories in the sidebar.
• Vim-style Navigation: Use HJKL to move around large diagrams.
• Zero Configuration: Works out of the box for any Python project.

Installation

Using uv (Recommended)

uv tool install git+https://github.com/cacrespo/pycodemap.git

Local Development

1. Clone the repository:

   git clone https://github.com/cacrespo/pycodemap.git
   cd pycodemap

2. Install dependencies:

   uv sync

3. Run:

   uv run pycodemap

Configuration

To enable AI summaries, create a .env file in your project root or set the environment variable:

GOOGLE_API_KEY=your_gemini_api_key_here

Usage

Run the tool in any Python project directory:

pycodemap

Or specify a path:

pycodemap /path/to/project

Key Bindings

• HJKL: Scroll diagram.
• R: Reset filter and refresh.
• Q: Quit.
• Click: Select file/folder to focus the diagram.

License

MIT