A CLI tool to help non-technical product managers and AI-native builders understand codebases.
The name "Code Guro" is a play on two words:
- "Guro" - Tagalog (Filipino) word for "teacher"
- "Guru" - Expert or master in a particular field
This reflects the tool's purpose: to serve as both a teacher (guro) and expert guide (guru) for understanding code.
Many product managers are now using AI coding agents (Claude Code, Cursor, etc.) to build functional prototypes and MVPs, but lack the programming background to truly understand the code that's generated. This creates hesitation when scaling products or bringing in users.
Code Guro analyzes a codebase and generates structured, beginner-friendly learning documentation. Unlike conversational AI tools that answer specific questions, Code Guro proactively creates a complete curriculum tailored to your specific codebase.
Recommended for production use:
python3 -m pip install --user code-guroFor development in a virtual environment:
pip install code-guroNote: Using
--userinstalls to your user directory and avoids conflicts with system packages. This is the recommended method for production use.
Requirements:
- Python 3.8 or higher
- Internet connection (for LLM API calls)
- API key from one of the supported providers:
- Anthropic Claude: console.anthropic.com
- OpenAI GPT: platform.openai.com/api-keys
- Google Gemini: aistudio.google.com/app/apikey
To upgrade to the latest version:
# If you installed with --user flag (recommended for production use)
python3 -m pip install --upgrade --user code-guro
# If you installed in a virtual environment
pip install --upgrade code-guro
# Force cache refresh if upgrade doesn't work
python3 -m pip install --upgrade --no-cache-dir --user code-guroTo check your current version:
code-guro --versionNote: If you have multiple installations (user-level, venv, system-wide), you may need to upgrade each separately or uninstall duplicates. Run which code-guro to see which installation is being used.
What's new in recent versions:
- v0.5.0 (Phase 1 UX Improvements) - Interactive setup wizard, smart defaults for zero-argument invocation, improved console output with emojis and milestones, secure API key storage in config file
- v0.4.2 - Added logo branding to HTML output, fixed Mermaid diagram syntax errors
- v0.4.1 - Fixed version string display issue (hotfix for v0.4.0)
- v0.4.0 - Left sidebar navigation, improved dark mode for Mermaid diagrams, enhanced mobile UX
- v0.3.1 - Fixed section 04 generation for large codebases, improved HTML output cleanliness
- v0.3.0 - Redesigned HTML output with modern aesthetic, improved accessibility
- v0.2.0 - Dual-format output (HTML + markdown), chunked analysis for large codebases
- v0.1.0 - Initial release
See CHANGELOG.md for detailed release notes.
code-guro configureYou'll be prompted to select a provider (Anthropic, OpenAI, or Google) and guided through:
- Selecting your preferred provider with cost and use-case information
- Entering your API key (will be hidden as you type)
- Immediate validation to ensure the key works
Your API key will be stored securely in ~/.config/code-guro/config.json with file permissions set to 0o600 (readable only by you).
Alternative: Environment variables (still supported for backwards compatibility and CI/CD):
For Anthropic Claude:
export ANTHROPIC_API_KEY="your-api-key-here"For OpenAI GPT-4o:
export OPENAI_API_KEY="your-api-key-here"For Google Gemini:
export GOOGLE_API_KEY="your-api-key-here"You can add these to your ~/.zshrc or ~/.bashrc to make them permanent.
Simplest way:
cd /path/to/your/project
code-guroCode Guro will automatically detect your project, show a preview (files, frameworks, estimated cost), and ask for confirmation before analyzing.
Explicit path:
# Analyze current directory (generates both HTML and markdown)
code-guro analyze .
# Analyze a specific path
code-guro analyze /path/to/project
# Analyze from GitHub
code-guro analyze https://github.com/user/repo
# Generate only markdown (no HTML)
code-guro analyze . --markdown-only# Explain a specific folder
code-guro explain ./src/auth
# Interactive mode for follow-up questions
code-guro explain ./src/auth --interactive
# Print explanation to console instead of file
code-guro explain ./src/auth --output consoleBy default, Code Guro generates both HTML and markdown documentation in a clean code-guro-output/ directory:
code-guro-output/
├── html/
│ ├── 00-overview.html # Executive summary: what the app does, tech stack
│ ├── 01-getting-oriented.html # File structure, extensions glossary, entry points
│ ├── 02-architecture.html # Patterns, conventions, architectural decisions
│ ├── 03-core-files.html # The 20% of files that matter most
│ ├── 04-deep-dive-[module].html # Deep dives for each major module
│ ├── 05-quality-analysis.html # What's good, what's risky, potential pitfalls
│ └── 06-next-steps.html # Suggested exploration paths, follow-up commands
└── markdown/
├── 00-overview.md
├── 01-getting-oriented.md
├── 02-architecture.md
├── 03-core-files.md
├── 04-deep-dive-[module].md
├── 05-quality-analysis.md
└── 06-next-steps.md
Each document includes:
- Beginner-friendly explanations
- Visual diagrams (Mermaid) - fully rendered in HTML files; markdown shows code (renders on GitHub/GitLab)
- Code snippets with inline comments
- Glossary of technical terms
Recommended: Open the HTML files in your browser for the best experience with fully rendered Mermaid diagrams, styling, and navigation.
Note for large codebases (>150K tokens): The markdown folder may also contain internal analysis files (prefixed with _) such as _analysis-notes.md and _chunk-XX-analysis.md. These files document the chunked analysis process and are kept for debugging purposes, but are excluded from the user-facing HTML output to keep navigation clean.
Since code-guro-output/ contains generated documentation that can be recreated at any time, you may want to add it to your .gitignore:
echo "code-guro-output/" >> .gitignoreHowever, some users prefer to commit the documentation for:
- GitHub Pages hosting
- Team collaboration without requiring API keys
- Historical reference of code understanding
The choice is yours!
Here's what the HTML documentation looks like when opened in your browser:
The overview page provides a high-level summary of what the application does, its key features, and the technology stack used. Perfect for getting oriented quickly.
The architecture pages include fully-rendered Mermaid diagrams that visualize system architecture, component relationships, and data flows. These diagrams help you understand how different parts of the codebase connect.
The deep dive pages provide in-depth analysis of specific modules, including API endpoints, request/response examples, and sequence diagrams showing how data flows through the system.
Set up your LLM provider and API key for first-time use.
code-guro configureAnalyze a codebase and generate documentation. Can also be invoked without arguments (code-guro) to analyze the current directory with smart defaults (see Quick Start). By default, generates both HTML and markdown in organized subdirectories.
code-guro analyze . # Current directory (both formats)
code-guro analyze /path/to/project # Specific path (both formats)
code-guro analyze https://github.com/user/repo # GitHub URL (both formats)
code-guro analyze . --markdown-only # Only markdown, no HTMLOptions:
--markdown-only- Generate only markdown files without HTML (default: generates both formats)--no-emoji- Disable emoji output in console (default: emojis enabled)
Convert existing markdown-only output to include HTML files. Useful if you previously ran analysis with --markdown-only and now want HTML.
code-guro convert # Convert from default directory (code-guro-output)
code-guro convert ./code-guro-output # Convert from specific directoryThis command:
- Moves markdown files into
markdown/subdirectory - Generates HTML files in
html/subdirectory - Preserves the original markdown files
Get a detailed explanation of a specific file or folder.
code-guro explain ./src/auth # Analyze a folder
code-guro explain ./src/app.py # Analyze a single fileOptions:
-i, --interactive- Launch interactive Q&A mode--output [file|console]- Where to output (default: file)
Display the current version.
Show help information.
Code Guro provides enhanced context for these frameworks:
| Framework | Detection Method |
|---|---|
| Next.js | package.json with "next", next.config.js |
| React | package.json with "react", .jsx/.tsx files |
| Vue.js | package.json with "vue", .vue files |
| Django | requirements.txt with "Django", manage.py |
| Flask | requirements.txt with "Flask", app.py patterns |
| Express.js | package.json with "express" |
| Ruby on Rails | Gemfile with "rails", config/routes.rb |
When a framework is detected, the documentation includes:
- Framework-specific architecture patterns
- Common conventions and best practices
- Known gotchas and pitfalls
Code Guro estimates API costs before running analysis based on:
- Token count of files to analyze
- Provider pricing (varies by selected LLM provider)
Cost confirmation:
- For estimates under $1.00: Proceeds automatically
- For estimates over $1.00: Asks for confirmation before continuing
Typical costs:
- Small project (10-50 files): $0.05 - $0.30
- Medium project (50-200 files): $0.30 - $1.00
- Large project (200+ files): $1.00 - $5.00
The --interactive flag launches a conversational Q&A session:
code-guro explain ./src/auth --interactiveYou can ask questions like:
- "Why was this pattern used?"
- "What does this function do?"
- "How does this connect to the database?"
- "What would happen if I changed X?"
Type exit or quit to end the session. Your conversation is saved to code-guro-output/explain-[path]-session.md.
Run code-guro configure to set up your API key, or set the CLAUDE_API_KEY environment variable.
Code Guro requires an internet connection for Claude API calls and GitHub cloning. Check your network connection.
For large codebases, you'll be asked to confirm before proceeding. You can:
- Enter
yto continue - Enter
nto cancel - Try analyzing a specific subdirectory instead
Files larger than 1MB are skipped to avoid excessive API costs. This is typically fine since large files are often generated code, dependencies, or data files.
Ensure the repository URL is correct and the repository is public. Private repositories are not currently supported.
# Clone the repository
git clone https://github.com/nicoladevera/code-guro.git
cd code-guro
# Create virtual environment
python3 -m venv venv
source venv/bin/activate
# Install in development mode
pip install -e ".[dev]"# Run all tests
pytest
# Run with coverage report
pytest --cov=code_guro --cov-report=term
# Generate detailed HTML coverage report
pytest --cov=code_guro --cov-report=html
# Then open htmlcov/index.html in your browserTest Coverage: 84% (51 tests covering dual-format output, CLI commands, and generators)
All tests use mocked API calls, so they run fast and work offline without requiring API keys.
IMPORTANT: Always run quality checks before committing to prevent CI failures:
# Recommended: Run all checks at once
make quality
# Or run individually:
black src/ # Format code
ruff check src/ --fix # Fix linting issues
pytest # Run testsPre-commit hooks (recommended):
# Install pre-commit hooks (one-time setup)
pre-commit install
# Now checks run automatically before each commit
# To run manually on all files:
pre-commit run --all-filesThe pre-commit hooks will:
- Auto-format code with Black (100 char line length)
- Auto-fix import sorting and remove unused imports
- Run Ruff linter with auto-fix
- Prevent commits if issues remain
MIT
Code Guro is a personal project maintained by @nicoladevera. The code is public and open source (MIT license), but I'm not accepting pull requests at this time.
- Bug reports: Please open a GitHub Issue
- Forking: Encouraged! Build your own variant if you need different features
- Development docs: See CONTRIBUTING.md for setup and code quality guidelines
For context on this approach, see the project philosophy in CONTRIBUTING.md.
Built with:
- Anthropic Claude API
- Click - CLI framework
- Rich - Terminal formatting
- tiktoken - Token counting