{"id":15130791,"url":"https://github.com/shaneholloman/codemapper","last_synced_at":"2025-07-27T07:30:36.362Z","repository":{"id":257791168,"uuid":"861165982","full_name":"shaneholloman/codemapper","owner":"shaneholloman","description":"Perfect for AI Prompts. CodeMapper is a python script that creates a comprehensive Markdown document representing the structure and contents of any given code base","archived":false,"fork":false,"pushed_at":"2025-05-20T02:03:13.000Z","size":85417,"stargazers_count":24,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-23T08:53:58.299Z","etag":null,"topics":["ai","markdown","prompting","python"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/shaneholloman.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.md","contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["shaneholloman"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"lfx_crowdfunding":null,"polar":null,"buy_me_a_coffee":null,"thanks_dev":null,"custom":null}},"created_at":"2024-09-22T07:12:03.000Z","updated_at":"2025-07-15T10:24:52.000Z","dependencies_parsed_at":null,"dependency_job_id":"c8488028-c98b-4e09-b231-dcf50785201b","html_url":"https://github.com/shaneholloman/codemapper","commit_stats":{"total_commits":82,"total_committers":1,"mean_commits":82.0,"dds":0.0,"last_synced_commit":"0256ad12e15fa3791cbc54419a2aa350eff4019c"},"previous_names":["shaneholloman/codemapper"],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/shaneholloman/codemapper","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaneholloman%2Fcodemapper","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaneholloman%2Fcodemapper/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaneholloman%2Fcodemapper/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaneholloman%2Fcodemapper/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/shaneholloman","download_url":"https://codeload.github.com/shaneholloman/codemapper/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/shaneholloman%2Fcodemapper/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267324218,"owners_count":24069351,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-27T02:00:11.917Z","response_time":82,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","markdown","prompting","python"],"created_at":"2024-09-26T03:06:16.887Z","updated_at":"2025-07-27T07:30:36.355Z","avatar_url":"https://github.com/shaneholloman.png","language":"Python","funding_links":["https://github.com/sponsors/shaneholloman"],"categories":["Code Analysis \u0026 Search","Python"],"sub_categories":["Other IDEs"],"readme":"# CodeMapper\n\n[![Total Downloads](https://static.pepy.tech/badge/codemapper)](https://pypistats.org/packages/codemapper)\n[![Pylint](https://github.com/shaneholloman/codemapper/actions/workflows/pylint.yml/badge.svg)](https://github.com/shaneholloman/codemapper/actions/workflows/pylint.yml)\n[![PyTest](https://github.com/shaneholloman/codemapper/actions/workflows/pytest.yml/badge.svg)](https://github.com/shaneholloman/codemapper/actions/workflows/pytest.yml)\n[![TODO](https://img.shields.io/badge/✔%20Todo-44-purple)](docs/todo.md)\n\n\u003cimg src=\"codemapper-logo.svg\" width=\"150\" alt=\"logo\"\u003e\n\n\u003c!-- TOC --\u003e\n\n- [CodeMapper](#codemapper)\n  - [Overview](#overview)\n  - [Key Features](#key-features)\n  - [AI Chat Integration](#ai-chat-integration)\n  - [Use Cases](#use-cases)\n    - [For AI Engineers](#for-ai-engineers)\n    - [For Hobbyists](#for-hobbyists)\n  - [Getting Started](#getting-started)\n  - [Example Output](#example-output)\n  - [Future Development](#future-development)\n  - [Target Audiences](#target-audiences)\n    - [AI Engineers Will Appreciate](#ai-engineers-will-appreciate)\n    - [Hobbyists Will Value](#hobbyists-will-value)\n  - [Installation Options](#installation-options)\n  - [Contributing](#contributing)\n  - [Resources](#resources)\n  - [License](#license)\n  - [Acknowledgments](#acknowledgments)\n  - [Version History](#version-history)\n\n\u003c!-- /TOC --\u003e\n\n## Overview\n\n\u003e [!IMPORTANT]\n\u003e CodeMapper: Bridging Code Understanding for AI and Human Analysis\n\u003e\n\u003e Install: `uv tool install codemapper` to your system. This will add a binary to your path. Zero conflicts with other tools. Of course you may use the traditional `pip install codemapper` as well.\n\nCodeMapper is a powerful Python tool that transforms complex codebases into navigable, single-file Markdown artifacts, with a unique ability to bootstrap AI chat prompts for code analysis. Designed with both AI engineers and hobbyist developers in mind, it serves as a bridge between traditional code exploration and modern AI-assisted development workflows. Whether you're training large language models, conducting interactive AI-assisted code reviews, or simply trying to understand a new project, CodeMapper provides a unified, accessible view of your codebase that's optimized for both human readability and AI consumption.\n\n```mermaid\nflowchart TB\n    %% Styles\n    classDef core fill:#3498db,stroke:#2980b9,color:white\n    classDef input fill:#2ecc71,stroke:#27ae60,color:white\n    classDef output fill:#e67e22,stroke:#d35400,color:white\n    classDef ai fill:#9b59b6,stroke:#8e44ad,color:white\n    classDef util fill:#95a5a6,stroke:#7f8c8d,color:white\n    classDef config fill:#f1c40f,stroke:#f39c12,color:black\n    classDef test fill:#e74c3c,stroke:#c0392b,color:white\n    classDef docs fill:#1abc9c,stroke:#16a085,color:white\n    classDef wip fill:#34495e,stroke:#2c3e50,color:white\n\n    %% Input Layer\n    subgraph InputSources\n        FS[\"Local File System\"]:::input\n        GH[\"GitHub Repository\"]:::input\n        CF[\"Configuration Files\"]:::input\n    end\n\n    %% Core Processing\n    subgraph CoreEngine\n        MAIN[\"Main Entry Point\"]:::core\n        DOC[\"Documentation Processor\"]:::core\n        CONF[\"Configuration Handler\"]:::core\n        UTIL[\"Utility Functions\"]:::core\n    end\n\n    %% Processing Layer\n    subgraph ProcessingLayers\n        FTA[\"File Tree Analysis\"]:::core\n        CP[\"Content Processing\"]:::core\n        DE[\"Documentation Extraction\"]:::core\n        SH[\"Syntax Highlighting\"]:::core\n        GI[\"Git Integration\"]:::core\n    end\n\n    %% Output Layer\n    subgraph OutputGenerators\n        CG[\"CodeMap Generator\"]:::output\n        DG[\"DocMap Generator\"]:::output\n        AI[\"AI Chat Integration\"]:::ai\n    end\n\n    %% Support Systems\n    subgraph SupportSystems\n        CICD[\"CI/CD Pipeline\"]:::util\n        TEST[\"Testing Framework\"]:::test\n        DOCS[\"Documentation System\"]:::docs\n        WIP[\"Work in Progress Features\"]:::wip\n    end\n\n    %% Configuration\n    subgraph ConfigSystem\n        PC[\"Project Config\"]:::config\n        DEP[\"Dependencies\"]:::config\n        GC[\"Git Config\"]:::config\n    end\n\n    %% Relationships\n    InputSources --\u003e CoreEngine\n    CoreEngine --\u003e ProcessingLayers\n    ProcessingLayers --\u003e OutputGenerators\n    CoreEngine -.-\u003e SupportSystems\n    ConfigSystem --\u003e CoreEngine\n\n    %% Click Events\n    click MAIN \"https://github.com/shaneholloman/codemapper/blob/main/src/codemapper/main.py\"\n    click DOC \"https://github.com/shaneholloman/codemapper/blob/main/src/codemapper/docmap.py\"\n    click CONF \"https://github.com/shaneholloman/codemapper/blob/main/src/codemapper/config.py\"\n    click UTIL \"https://github.com/shaneholloman/codemapper/blob/main/src/codemapper/utils.py\"\n    click CICD \"https://github.com/shaneholloman/codemapper/tree/main/.github/workflows\"\n    click TEST \"https://github.com/shaneholloman/codemapper/tree/main/tests\"\n    click DOCS \"https://github.com/shaneholloman/codemapper/tree/main/docs\"\n    click WIP \"https://github.com/shaneholloman/codemapper/tree/main/wip\"\n    click PC \"https://github.com/shaneholloman/codemapper/blob/main/pyproject.toml\"\n    click DEP \"https://github.com/shaneholloman/codemapper/blob/main/requirements.txt\"\n    click GC \"https://github.com/shaneholloman/codemapper/blob/main/.gitignore\"\n\n    %% Legend\n    subgraph Legend\n        L1[\"Core Components\"]:::core\n        L2[\"Input Handlers\"]:::input\n        L3[\"Output Generators\"]:::output\n        L4[\"AI Integration\"]:::ai\n        L5[\"Utility Functions\"]:::util\n        L6[\"Configuration\"]:::config\n        L7[\"Testing\"]:::test\n        L8[\"Documentation\"]:::docs\n        L9[\"Work in Progress\"]:::wip\n    end\n```\n\n## Key Features\n\n- **Unified Code Visualization**: Automatically generates a comprehensive Markdown representation of your entire codebase, including:\n  - Complete directory structure visualization\n  - Syntax-highlighted code content\n  - Intelligent file categorization\n  - Documentation aggregation\n\n- **AI Integration Optimizations**:\n  - Structured output format ideal for LLM training and analysis\n  - Consistent formatting for improved token efficiency\n  - Built-in support for common documentation patterns\n  - Metadata preservation for enhanced context\n\n- **Git-Aware Processing**:\n  - Respects `.gitignore` rules by default\n  - Direct GitHub repository URL support\n  - Handles large repositories efficiently\n  - Smart binary file detection\n  - We always shallow clone for speed!\n\n- **Customization Options**:\n  - Exclude and Include dir options for fine-grained control\n  - Always excludes .venv, .conda and node_modules directories\n\n- **Documentation Focus**:\n  - Dedicated DocMap generation for documentation-heavy projects\n  - README file prioritization\n  - Support for multiple documentation directory conventions\n  - Markdown-native output for universal compatibility\n\n## AI Chat Integration\n\nCodeMapper excels at bootstrapping AI chat interactions for code analysis. When you need to understand, debug, or enhance your code with AI assistance:\n\n1. Generate a codemap of your project\n2. Copy the generated markdown into your AI chat\n3. Start asking detailed questions about your codebase\n\nThe AI assistant receives:\n\n- Complete project structure\n- All file contents with proper syntax highlighting\n- Documentation in context\n- Clear navigation structure\n\nThis enables the AI to provide more accurate, contextual responses about your code without manual file copying or context limitations.\n\n## Use Cases\n\n### For AI Engineers\n\n- **AI Chat Prompt Bootstrapping**: Instantly generate context-rich prompts for AI chat interactions about your code\n- **Interactive Code Analysis**: Seamlessly feed comprehensive codebase context to AI assistants\n- **Training Data Preparation**: Generate consistently formatted codebase representations for model training\n- **Documentation Generation**: Train models on well-structured documentation patterns\n- **Code Understanding**: Feed entire codebases to LLMs for comprehensive analysis\n\n\u003e [!TIP]\n\u003e Example AI Chat Workflow:\n\n```bash\n# Generate a codemap for your project\ncodemapper /path/to/project_or_repo\n\n# The generated codemap can be directly used in AI chat prompts:\n\"Here's my project structure and code, help me understand the dependency flow:\n[paste or add to you project knowledge *_codemap.md content]\"\n```\n\n### For Hobbyists\n\n- **Project Exploration**: Quickly understand new codebases without complex IDE setup\n- **Documentation Creation**: Generate comprehensive project documentation automatically\n- **Code Reviews**: Facilitate easier code reviews with a unified view\n- **Learning Tool**: Study and understand how different projects are structured\n\n## Getting Started\n\n```bash\n# Install from PyPI\npip install codemapper\n\n# Basic usage\ncodemapper /path/to/project\n\n# Generate documentation map\ncodemapper --docs /path/to/project\n\n# Process GitHub repository\ncodemapper https://github.com/username/repo\n```\n\n## Example Output\n\nCodeMapper generates two main types of outputs:\n\n1. **CodeMap** (`project_codemap.md`):\n   - Complete directory tree\n   - File contents with syntax highlighting\n   - Smart handling of binary and large files\n   - Navigation-optimized structure\n\n2. **DocMap** (`project_docmap.md`):\n   - Documentation-focused view\n   - README files\n   - Documentation directory contents\n   - Structured for easy consumption\n\n## Future Development\n\n\u003e [!NOTE]\n\u003e CodeMapper welcomes help while actively focused on:\n\n[ToDos](docs/todo.md)\n\n- Expanded format support (XML, JSON, YAML, RST)\n- Enhanced AI integration capabilities\n- Real-time code change tracking\n- Collaborative annotation features\n- Intelligent code pattern recognition\n- API access for programmatic integration\n\n## Target Audiences\n\n### AI Engineers Will Appreciate\n\n- Consistent, clean output format for training data\n- Efficient handling of large repositories\n- Structured metadata preservation\n- Integration-ready design\n\n### Hobbyists Will Value\n\n- Simple, straightforward installation\n- Clear, readable output\n- No complex configuration required\n- Immediate utility for project understanding\n\n## Installation Options\n\n```bash\n# For basic traditional installation\npip install codemapper\n\n# Preferred installation\nuv tool install codemapper\n\n# For development installation\ngit clone https://github.com/shaneholloman/codemapper\ncd codemapper\nuv venv\nuv sync\nuv pip install -e .\n```\n\n## Contributing\n\nCodeMapper welcomes contributions from both AI engineers and hobbyist developers. The project maintains a balance between sophisticated features for AI integration and accessibility for general use.\n\nVisit the [GitHub repository](https://github.com/shaneholloman/codemapper) to:\n\n- Report issues\n- Submit feature requests\n- Contribute code\n- Join the discussion\n\n## Resources\n\n- [GitHub Repository](https://github.com/shaneholloman/codemapper)\n- [PyPI Package](https://pypi.org/project/codemapper/)\n- [Issue Tracker](https://github.com/shaneholloman/codemapper/issues)\n- [Changelog](https://github.com/shaneholloman/codemapper/blob/main/changelog.md)\n\nCodeMapper represents a bridge between traditional code exploration and modern AI-assisted development, making codebases more accessible and understandable for everyone from AI researchers to hobbyist developers.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- Thanks to the `pathspec` and `chardet` libraries for enhancing CodeMapper's functionality.\n\n## Version History\n\nFor a detailed version history, please refer to the [changelog.md](changelog.md).\n\n---\n\nIf you find CodeMapper useful, don't forget to star this repository!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaneholloman%2Fcodemapper","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fshaneholloman%2Fcodemapper","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fshaneholloman%2Fcodemapper/lists"}