gpt-folder-tree

Create complete project folder structures from GPT-style ASCII trees — instantly.

gpt-folder-tree is a lightweight Python utility that converts ASCII folder trees (like those generated by ChatGPT or written in README files) into real directories and files on your filesystem.

Perfect for:

• Bootstrapping new projects
• Recreating documented folder structures
• Automating scaffolding for frameworks, microservices, or libraries
• Turning design docs into real codebases

---

✨ Features

• 📂 Parse GPT / Unix-style ASCII folder trees
• 🧪 Dry-run mode to preview what will be created
• ⚡ Create folders and files automatically
• 🧩 Minimal, dependency-free, and fast
• 🐍 Pythonic API — easy to integrate into tools or CLIs

---

📦 Installation

# Install using pip
pip install gpt-folder-tree

# Install using uv
uv add gpt-folder-tree

---

🚀 Quick Start

1. Import the library

from gpt_folder_tree import parse_tree, create_tree, dry_run

---

2. Define your folder structure (ASCII format)

gpt_ascii_text = """
project/
├── app/
│   ├── __init__.py
│   ├── main.py
│   ├── config.py
│   ├── database/
│   │   ├── __init__.py
│   │   ├── connection.py
│   │   └── models.py
│   ├── api/
│   │   ├── __init__.py
│   │   ├── v1/
│   │   │   ├── __init__.py
│   │   │   ├── routes.py
│   │   │   └── schemas.py
│   ├── services/
│   │   ├── __init__.py
│   │   ├── auth_service.py
│   │   ├── user_service.py
│   │   └── email_service.py
│   ├── core/
│   │   ├── __init__.py
│   │   ├── security.py
│   │   └── dependencies.py
│   ├── utils/
│   │   ├── __init__.py
│   │   └── helpers.py
├── tests/
│   ├── __init__.py
│   ├── test_main.py
│   ├── test_auth.py
│   └── test_users.py
├── alembic/
│   ├── env.py
│   └── versions/
├── scripts/
│   └── seed_db.py
├── requirements.txt
├── .env
├── README.md
└── Dockerfile
"""

---

3. Parse the tree

tree = parse_tree(gpt_ascii_text)

---

4. (Optional) Dry run — preview what will be created

dry_run(tree)

Output example:

CREATE DIR  ./project
CREATE DIR  ./project/app
CREATE FILE ./project/app/main.py
...

---

5. Create the folders & files

create_tree(tree)

✅ Your entire project structure is now created on disk.

---

🧠 How It Works

• Directories are detected by a trailing /
• Files are created as empty files
• Indentation depth determines parent-child relationships
• Compatible with GPT-generated trees and Unix-style layouts

---

🗂 API Reference

parse_tree(text: str) -> Node

Parses an ASCII tree string into an internal tree structure.

---

dry_run(node: Node, base_path: str = ".")

Prints what would be created without touching the filesystem.

---

create_tree(node: Node, base_path: str = ".")

Creates all directories and files on disk.

---

⚠️ Notes & Best Practices

• Run dry_run() before create_tree() for safety
• Avoid running in sensitive directories (e.g., /, home root)
• ASCII tree must be properly indented (4 spaces per level)

---

🤝 Contributing

Contributions, issues, and feature requests are welcome. This project is intentionally simple — clarity over complexity.

---

⭐ Why This Exists

Because copying folder structures from ChatGPT, README files, or documentation should not require manual folder creation.

Turn ideas into structure. Instantly.