Turn source code into clean, AI-ready Markdown context for ChatGPT, Claude, Gemini, and other LLMs.
ContextDump is a lightweight command-line utility and Python library that transforms an entire source code project into clean, structured Markdown optimized for Large Language Models (LLMs).
Instead of manually copying files into ChatGPT, Claude, Gemini, or another AI assistant, ContextDump scans your project, filters relevant files, detects languages, generates a directory tree, collects useful project statistics, and produces a single well-formatted Markdown document ready to share or prompt against.
The generated output is designed to preserve project structure while remaining easy for both humans and language models to understand.
Current capabilities include:
- 📁 Recursive project scanning
- 🌳 Project directory tree generation
- 📝 AI-friendly Markdown output
- 🎨 Automatic language detection for syntax highlighting
- 🎯 Include and exclude glob patterns
- 📊 Project statistics and token estimation
- ⚙️ Configurable rendering behaviour
- 🔊 Verbosity-aware context generation
- 📋 Optional clipboard integration
- 🧩 Importable Python API
- Python 3.11 or newer
pip install contextdumpInstall the optional clipboard dependency if you want generated output copied directly to your system clipboard.
pip install "contextdump[clipboard]"Generate a Markdown snapshot of the current directory.
contextdumpGenerate context for a specific project.
contextdump path/to/projectWrite the generated document to a file.
contextdump -o context.mdCopy the generated output to the clipboard.
contextdump --clipboardOnly include Python files.
contextdump --extensions pyExclude additional files or directories.
contextdump --exclude .venv/** tests/**Generate richer contextual output.
contextdump -vFor the complete list of supported command-line options, run:
contextdump --help# ContextDump
Generated: 2026-07-07 15:08 UTC
Project Root
/home/user/example-project
---
## Directory Tree
example-project
├── src/
│ ├── contextdump/
│ │ ├── application.py
│ │ ├── cli.py
│ │ └── templates/
│ └── tests/
├── README.md
└── pyproject.toml
---
## Summary
- Files: 27
- Lines: 2,145
- Bytes: 54,183
- Estimated tokens: 13,529
- Languages:
- python: 20
- markdown: 3
- toml: 1
---
## src/contextdump/application.py
```python
class ContextDump:
...ContextDump is both a command-line utility and an importable Python library.
from pathlib import Path
from contextdump import ContextDump
from contextdump import ContextDumpConfig
config = ContextDumpConfig(
root=Path("my_project"),
)
document = ContextDump(config).generate()
print(document)ContextDump is intentionally organised as a simple processing pipeline. Each stage has a single responsibility and communicates using strongly typed domain models.
Configuration
│
▼
ProjectScanner
│
▼
Source Files
│
├─────────────┐
▼ │
Statistics │
│ │
└──────┬──────┘
▼
Renderer Registry
│
▼
Renderer
│
▼
Generated Output
The application layer coordinates the pipeline without owning the implementation details of scanning, filtering, statistics generation, or rendering.
Renderers are selected through a registry based on the configured output format, making additional formats straightforward to introduce in future releases without changing the application layer.
- Markdown
- JSON
- XML
ContextDump can generate progressively richer context depending on the requested verbosity level.
| Command | Output |
|---|---|
contextdump |
Standard project context |
contextdump -v |
Includes additional per-file metadata |
contextdump -vv |
Reserved for future structural summaries |
The default output is intentionally concise while remaining useful for most LLM workflows. Higher verbosity levels provide additional context without changing the underlying project structure.
Configuration is currently provided through the Python API and command-line arguments.
Support for project configuration files is planned for a future release, allowing projects to define default scanning and rendering behaviour.
Configuration precedence will be:
- Built-in defaults
- Project configuration
- Command-line arguments
The architecture introduced in v0.1.0 is designed to support richer project analysis without requiring major structural changes.
Planned improvements include:
- Additional output formats (JSON, XML)
- Project configuration files
- Git-aware project scanning
- Structural source summaries
- Language-aware context enrichers
- Project symbol indexes
- Dependency summaries
- Chunked output for large repositories
Future releases will primarily focus on generating increasingly useful AI-oriented project context while maintaining a stable public API.
Contributions are welcome.
Whether you're fixing a bug, improving documentation, adding language support, or proposing a new feature, pull requests and discussions are appreciated.
If you're planning a significant architectural change, please open an issue first so the approach can be discussed before implementation begins.
Clone the repository and install it in editable mode.
git clone <repository-url>
cd contextdump
pip install -e .Install the optional clipboard dependency during development if required.
pip install -e ".[clipboard]"Run the command-line interface directly from the source tree.
contextdump --helpContextDump is guided by a few core principles.
-
Simple by default. Useful output should require little or no configuration.
-
Composable architecture. Scanning, filtering, statistics, and rendering are isolated components that can evolve independently.
-
LLM-first output. Generated documents should be readable by humans while remaining optimized for large language models.
-
Predictable behaviour. Identical inputs should produce identical output whenever practical.
-
Extensible foundation. New renderers, enrichers, and output formats should be easy to add without redesigning the application.
This project is licensed under the MIT License.
See the LICENSE file for details.