Project file map generator for AI-assisted development.
Scans a directory and prints a clean, annotated tree that you can paste directly into any AI chat. Instead of uploading your entire codebase, share the map first — then only send the files the AI actually asks for.
Live Demo: paracci.github.io/aitree
webapp/
├── src/
│ ├── components/
│ │ ├── Header.jsx [4KB]
│ │ └── Footer.jsx [2KB]
│ ├── App.jsx [8KB]
│ └── index.js [1KB]
├── public/
│ └── index.html [3KB]
└── package.json [1KB]
# 2 directories, 6 files (18KB total)
#
# File types:
# .jsx 3 ███
# .js 1 █
# .html 1 █
# .json 1 █
Via pip (recommended):
pip install paracci-aitreeOne-liner (Linux / macOS):
curl -fsSL https://raw.githubusercontent.com/paracci/aitree/main/install.sh | bashOne-liner (Windows PowerShell):
irm https://raw.githubusercontent.com/paracci/aitree/main/install.ps1 | iexFrom source:
git clone https://github.com/paracci/aitree.git
cd aitree
pip install .Optional dependencies — install only what you need:
pip install "paracci-aitree[live]" # --live mode (watchdog)
pip install "paracci-aitree[tokens]" # --tokens (tiktoken)
pip install "paracci-aitree[git]" # --git-changed (gitpython)
pip install "paracci-aitree[mcp]" # MCP server (mcp)
pip install "paracci-aitree[all]" # everything + clipboard (pyperclip)aitree [path] [options]path defaults to the current directory if omitted.
| Flag | Description |
|---|---|
| (none) | Print tree to stdout |
--save |
Save to _aitree.txt (or _aitree.json / _aitree.md) |
--copy |
Copy output to clipboard |
--live |
Watch for changes and auto-update the saved file |
--serve |
Launch the web UI in your browser |
| Flag | Description |
|---|---|
--format text |
Plain text with # comments (default) |
--format json |
Structured JSON with tree + stats + meta |
--format markdown |
Markdown with fenced code block + stats table |
| Flag | Description |
|---|---|
--depth N |
Limit tree depth (e.g. --depth 2) |
--include GLOB |
Show only matching files (repeatable) |
--exclude GLOB |
Hide matching files (repeatable) |
--no-gitignore |
Skip .gitignore / .aitreeignore parsing |
--git-changed |
Show only git-changed / untracked files |
| Flag | Description |
|---|---|
--tokens |
Append estimated token count to output |
--version |
Show version and exit |
aitree . # current directory → stdout
aitree ~/projects/webapp # specific path → stdout
aitree . --save # save to _aitree.txt
aitree . --copy # copy to clipboard
aitree . --depth 2 # top 2 levels only
aitree . --include "*.py" # Python files only
aitree . --include "*.py" --include "*.js" # multiple patterns
aitree . --exclude "*.test.*" # hide test files
aitree . --git-changed # only modified/untracked files
aitree . --format json --save # save as _aitree.json
aitree . --format markdown --save # save as _aitree.md
aitree . --tokens # append token count
aitree . --live # watch for changes
aitree . --live --depth 2 --git-changed # live + depth + git filter
aitree . --serve # open web UI
aitree . --serve --port 8080 # web UI on a custom port1. aitree . --copy
2. Paste into your AI chat
3. Ask "Which files do you need?"
4. Send only those files
--serve launches a local web server and opens a professional, interactive explorer in your browser.
- Real-time Search: Instant tree filtering with match highlighting.
- Syntax Highlighting: Auto-detection for 30+ languages (via highlight.js).
- Themes: Switch between Dark (Tokyo Night) and Light (GitHub) modes.
- File Preview: Click any file to see content with line numbers and word-wrap.
- Interactive Tree: Fast collapse/expand, depth control, and file-type icons.
- Live Reload: UI auto-refreshes when your project files change.
- Responsive Layout: Resizable sidebar and mobile-friendly design.
aitree . --serve
aitree . --serve --port 8080AITree ships a Model Context Protocol server so AI assistants (Claude Desktop, etc.) can call it as a tool.
# Install MCP dependency
pip install "paracci-aitree[mcp]"
# Start the server
aitree-mcp| Tool | Description |
|---|---|
aitree_get_tree |
Generate a file tree for a local path or GitHub URL |
aitree_get_stats |
Return structured JSON statistics for a path |
aitree_get_changed |
List git-changed / untracked files |
aitree_read_file |
Read the contents of a file inside the project |
aitree_read_file lets an AI assistant fetch any file it spotted in the tree — without leaving the conversation:
aitree_get_tree(path=".", format="text")
aitree_read_file(path=".", file="src/auth/login.py")
{
"mcpServers": {
"aitree": {
"command": "aitree-mcp"
}
}
}Pass a GitHub repository URL instead of a local path:
aitree https://github.com/owner/repo
aitree https://github.com/owner/repo --depth 2
aitree https://github.com/owner/private-repo --token ghp_xxxxWorks entirely via the GitHub API — no cloning required.
Create .aitreeignore in your project root — same syntax as .gitignore:
# .aitreeignore
*.secret
config/local.json
private/
AITree reads .aitreeignore first, then .gitignore. Use --no-gitignore to skip both.
| Category | Examples |
|---|---|
| VCS & editors | .git, .idea, .vscode, .svn |
| Dependencies | node_modules, .venv, venv, env |
| Build output | dist, build, target, out, bin |
| Cache | __pycache__, .pytest_cache, .mypy_cache |
| Binary & temp | .pyc, .class, .exe, .log, .tmp |
| OS files | .DS_Store, Thumbs.db |
--live watches the directory with watchdog and regenerates the output file whenever the structure actually changes. False positives (editor auto-saves, antivirus touches, etc.) are filtered out via content hashing and a 1-second debounce.
🟢 AITree LIVE — Watching: /home/user/projects/webapp [depth=2, git-changed]
Updates trigger only on real changes.
Press Ctrl+C to stop.
[14:32:10] Updated — initial snapshot
[14:33:05] Updated — filesystem change (3 false events skipped)
Combines with any filter flag: --depth, --include, --exclude, --git-changed.
| Platform | Tested |
|---|---|
| Linux | ✅ |
| macOS | ✅ |
| Windows | ✅ |
| WSL | ✅ |
Requires Python 3.10+.