DirScribe is a lightweight yet powerful CLI tool and Python library for exporting directory structures in either text or JSON format. It helps you optionally include file contents, detect programming languages, skip hidden items, limit file reading by size, show metadata (size and modification time), and output results directly to your terminal or a file.
Created by: Kazuki Kawamura (Caspy /ˈkæspi/, かすぴー)
License: MIT License
One of DirScribe's key features is how easily it can include file contents by extension.
- If you run
dirscribe /path -e .py .txt, it includes only.pyand.txtfiles' contents. - If you run
dirscribe /path -ewith no arguments, it includes all file contents (new in v0.1.2). - If you omit
-eentirely, no file contents are included—just the directory tree.
Another new feature in v0.1.2 is --clip, which copies the final output (text or JSON) to your clipboard for quick sharing.
Another new feature in v0.1.3 is --exclude-extensions, which allows you to completely skip certain file types in the output (e.g., --exclude-extensions .md .rst). You can also copy the result to your clipboard with --clip (requires pyperclip, which is now installed automatically).
Example:
dirscribe /path/to/your_project -e .py --clipThis command shows all .py file contents (skipping other extensions) and copies the result to your clipboard.
Below is a quick text-based preview if you scan a sample project:
📁 your_project/
📄 main.py (Python)
def calculate_total(items):
return sum(item.price for item in items)
def main():
print("Processing orders...")
📁 templates/
📄 index.html (HTML)
<!DOCTYPE html>
<html>
<head><title>My App</title></head>
<body><h1>Welcome</h1></body>
</html>
📄 style.css (CSS)
body {
margin: 0;
padding: 20px;
font-family: sans-serif;
}
If you prefer JSON:
dirscribe /path/to/your_project --output-format jsonYou get:
{
"type": "directory",
"name": "your_project",
"path": "absolute/path/your_project",
"children": [
{
"type": "file",
"name": "main.py",
"path": "...",
"language": "Python",
"content": "...",
...
},
...
]
}- Key Features
- Why DirScribe?
- Installation
- Quick Start
- Command-Line Usage
- Python Library Usage
- Use Cases
- AI Tools Integration
- Contributing
- License
-
Text or JSON Output
- Choose between a human-readable tree format or a structured JSON representation for advanced integrations.
-
File Content Inclusion
- Display the contents of files for specific extensions (e.g., .py, .js, .txt).
- Tip: With v0.1.2, if you add
-ewith no extensions, all file contents are included.
-
Exclude Extensions
- Use --exclude-extensions (new in v0.1.3) to completely skip unwanted file types.
-
Language Detection
- Show the programming language name (e.g., .py -> Python) alongside file names.
-
Skip Hidden
- Omit hidden files and directories (names starting with a dot).
-
Maximum Size Limit
- Automatically skip file content if a file exceeds a specified byte-size.
-
Metadata Display
- Show file size and last modification timestamp in the output.
-
Clipboard Copy
- Use
--clipto copy the output directly to your clipboard (requires pyperclip).
- Use
-
Save to File
- Output can be redirected to a file rather than just printing to the console.
-
Highly Configurable
- Combine various options to fit your exact needs.
-
Instant Documentation
- Quickly generate a snapshot of your codebase – perfect for onboarding new team members or archiving project structures.
-
Efficient Code Reviews
- Include file contents up to a specified size, letting you skim important files without diving deeply into each folder.
-
Language Insights
- Recognize the languages used in your project at a glance.
-
Scriptable
- Integrate DirScribe into CI/CD pipelines or other automated workflows to maintain updated structure maps.
-
Open Source & Community-Driven
- MIT-licensed, easily extended, and continuously improved by the community.
You can install DirScribe by cloning the repository and running:
pip install .If you're actively editing the source, you might prefer:
pip install -e .This sets up DirScribe in "editable" mode so changes in the code take immediate effect.
If DirScribe is published on PyPI in the future, you'll be able to do:
pip install dirscribedirectly.
Generate a text listing of a directory:
dirscribe /path/to/projectGenerate a JSON output and save it to a file:
dirscribe /path/to/project --output-format json --output-file project_structure.jsonInclude all file contents (no matter the extension):
dirscribe /path/to/project -eCopy the result to your clipboard (also new in 0.1.2):
dirscribe /path/to/project --clipThat's it! Mix and match the options below for your needs.
Once installed, you can run dirscribe:
dirscribe [DIRECTORY] [OPTIONS]
-
-e, --extensions <EXT ...>- Specify which file extensions to include content for (e.g.,
-e .py .js). - If you pass
-ewith no extensions, DirScribe will include the contents of all files. - If you omit
-eentirely, it includes no file contents.
- Specify which file extensions to include content for (e.g.,
-
--detect-language- Enables language detection based on file extensions (e.g., .py -> Python).
-
--skip-hidden- Skips files and directories whose names begin with
..
- Skips files and directories whose names begin with
-
--max-size <BYTES>- Maximum file size (in bytes) to read. Files larger than this are ignored.
-
--show-metadata- Displays file metadata (size in bytes, last modification time) next to file content.
-
--output-format <text|json>- Output either a text-based tree or JSON structure. Defaults to text.
-
--output-file <FILE>- Write the output to the specified file instead of printing to stdout.
-
--clip- Copy the final output to your clipboard (requires pyperclip).
dirscribe /path/to/src \
-e .py .html \
--detect-language \
--skip-hidden \
--max-size 2000 \
--show-metadata \
--output-format text \
--output-file output.txtWhat this does:
- Recursively scans
/path/to/src - Shows contents of files with .py or .html extension (up to 2000 bytes)
- Skips hidden items (names starting with a dot)
- Displays file size & last modified time
- Identifies language names where possible
- Renders as a textual tree
- Saves it to output.txt (instead of printing to the terminal)
DirScribe can also be used as a library:
from pathlib import Path
from dirscribe.core import export_directory_structure
def main():
directory = Path("/path/to/src")
# Export directory structure as text (list of lines)
lines = export_directory_structure(
target_dir=directory,
include_extensions=[".py", ".html"],
skip_hidden=True,
max_size=2000,
show_metadata=True,
detect_language=True,
output_format="text",
output_file=None
)
# If output_format="text" and output_file=None, you get a list of lines
for line in lines:
print(line)
if __name__ == "__main__":
main()-
target_dir(Path)- The folder you want to scan.
-
include_extensions(List[str], optional)- File extensions for which file contents should be included.
- Pass None or use
-ewith no args to include all files.
-
skip_hidden(bool, default=False)- Skip hidden files and directories.
-
max_size(int, optional)- Skip content for files larger than this size.
-
show_metadata(bool, default=False)- Show file size and last modification time.
-
detect_language(bool, default=False)- Attach a language field based on file extension (e.g., .py -> Python).
-
output_format(str, default="text")- Either "text" or "json".
-
output_file(Path, optional)- If provided, the data is written to that file. Returns empty list/string.
- If
output_format="text"andoutput_file=None, returns a list of text lines. - If
output_format="json"andoutput_file=None, returns a JSON string. - If
output_fileis set, writes to that file and returns an empty list or empty string.
Generate a tree-like structure of your source code, optionally with file contents. Great for sharing with collaborators or creating "at-a-glance" docs.
Quickly see which files exist, their languages, and read short/medium files directly.
Skip hidden or large files, or selectively scan certain file types.
Save a JSON manifest of your repository structure as part of your build artifacts. Compare structure between builds or track changes over time.
Leverage DirScribe's JSON or text output in custom pipelines or scripts.
DirScribe's output is perfect for feeding into ChatGPT or other AI tools to analyze or summarize a project's structure:
- Generate a text or JSON snapshot:
dirscribe /path/to/src --output-format text > structure.txt-
Copy/paste structure.txt into ChatGPT (or your AI tool).
-
Ask questions like:
- "Give me an overview of this project."
- "Identify potential security concerns."
- "Suggest improvements or refactoring ideas."
By providing AI with a precise structure (and optionally file contents), you can quickly gain insights or documentation without manual exploration.
We welcome contributions, suggestions, and bug reports! See our CONTRIBUTING.md to learn how to propose changes or open pull requests. We also encourage you to open an issue for any problems or feature requests.
Ways to help:
- Code contributions (new features, bug fixes, refactoring)
- Documentation improvements (clarify instructions, add examples)
- Language mapping expansions (add more file extensions to LANGUAGE_MAP)
- Feedback and testing on different OS environments or large-scale projects
If you find DirScribe valuable, please star the repository and share it with fellow developers!
This project is distributed under the MIT License. © 2025 Kazuki Kawamura