CodeMappr 🗺️
Instantly understand any codebase. One command.
What is CodeMappr?
CodeMappr is a powerful CLI tool designed to give you an instant, high-level understanding of any codebase. Whether you're jumping into a new repository for the first time or documenting an existing one, CodeMappr scans the directory structure, detects the project type, identifies the language stack, and summarizes the architecture in seconds.
Unlike many other tools, CodeMappr works entirely offline and requires no API keys. It uses heuristic-based signals to identify over 20 different project types and supports universal language detection. With three distinct output formats—interactive Terminal dashboard, portable Markdown, and a beautiful dark-themed HTML report—CodeMappr is the perfect companion for every developer's toolkit.
Demo
Screenshot 1 — Terminal View
Screenshot 2 — Markdown Export
Screenshot 3 — HTML Export
Screenshot 4 — All formats at once
Installation
pip install codemappr
Quick Start
# Scan current directory
codemappr scan
# Scan a specific path
codemappr scan /path/to/project
# Export as markdown
codemappr scan --format md
# Export as HTML
codemappr scan --format html
# Export everything at once
codemappr scan --format all
# Limit depth
codemappr scan --depth 3
# Ignore patterns
codemappr scan --ignore ".cache,temp"
Output Formats
Terminal
A rich, color-coded dashboard displayed directly in your terminal, featuring panels for project profiles, architectural summaries, and a styled directory tree.
Markdown
A portable CODEMAPPR.md file perfect for inclusion in pull requests, project documentation, or sharing via GitHub/GitLab.
HTML
A standalone, interactive CODEMAPPR.html report with a dark theme and collapsible directory trees for deep exploration of large codebases.
Supported Project Types
| Project Type | Detection Signals |
|---|---|
| Monorepo | Presence of packages/, apps/, or libs/ with multiple project configs. |
| React/Next.js | package.json with next or react dependencies, or next.config.js. |
| Vue.js | vue.config.js or presence of .vue files (e.g., App.vue). |
| Angular | angular.json configuration file and standard src/app structure. |
| Node.js API | package.json with entry points like index.js, server.js, or app.js. |
| Python Django | manage.py script along with settings.py and urls.py. |
| Python FastAPI/Flask | main.py or app.py with corresponding framework dependencies. |
| Python Package/Library | Presence of pyproject.toml or setup.py. |
| Rust | Cargo.toml manifest file. |
| Go | go.mod module file. |
| Java/Spring | pom.xml (Maven) or build.gradle (Gradle) files. |
| Android | Presence of AndroidManifest.xml. |
| Flutter/Dart | pubspec.yaml manifest file. |
| Ruby on Rails | Gemfile plus config/routes.rb and standard app/ directory. |
| PHP/Laravel | composer.json and the artisan CLI tool. |
| Docker-based | Presence of Dockerfile or docker-compose.yml. |
| Data Science/ML | .ipynb notebooks or notebooks/ directory with DS libraries (pandas, etc.). |
| Static Site | Presence of a root index.html without heavy framework signals. |
| Generic Python | Fallback for projects primarily using .py files. |
| Generic JS/TS | Fallback for projects primarily using .js or .ts files. |
Roadmap
- v1.0.0 ✅ Core scanning, detection, terminal + export
- v2.0.0 🔜 File relationship map
- v3.0.0 🔜 Structural diff / changelog
Contributing
We welcome contributions! To contribute:
- Fork the repository.
- Create a new branch for your feature or bugfix.
- Ensure all tests pass by running
pytest. - Submit a pull request with a detailed description of your changes.
All new features should be accompanied by relevant tests and documentation updates.
License
MIT
1 maintainer
Metadata
1 maintainer
Release files for codemappr 1.0.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | |
|---|---|---|---|---|
| codemappr-1.0.0.tar.gz | 18.7 kB | With provenance | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| codemappr-1.0.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 36.1 kB
Release files / codemappr-1.0.0.tar.gz
| Download URL | codemappr-1.0.0.tar.gz |
|---|---|
| Size | 18.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
5c25812b268f4fb6e2bf1b8bf30efece4dbe68726b1e1ee197c8b41fd82ade7b
|
|
BLAKE2b-256 checksum How to use checksums |
4bd3017ab0e6ca4073a1699848604aef2e289cf567a331b5d29980ac3d38a2f8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 20, 2026.
Transparency logRelease files / codemappr-1.0.0-py3-none-any.whl
| Download URL | codemappr-1.0.0-py3-none-any.whl |
|---|---|
| Size | 17.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4b9bf1b62b28760e15b63c8410a4b7a72a61ce35b2233afe935d88b35ea5cb99
|
|
BLAKE2b-256 checksum How to use checksums |
c6e2b3b1996f845297e2fedbd0567f1a54b9f2e4fe0fc879c458dac2ce5b5963
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/6.1.0 CPython/3.13.12
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 20, 2026.
Transparency logSecurity for codemappr 1.0.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
All 2 files in this release have been uploaded with provenance metadata.
Attestation for codemappr-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on May 20, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.
