🌲 prompt2tree (pt)

The AI-native project scaffolder. Convert raw LLM text trees into physical directory structures and initial boilerplate files in milliseconds.

---

💡 Why prompt2tree?

When using AI coding assistants (ChatGPT, Claude, Cursor, DeepSeek), asking agents to create individual folders and files burns thousands of context tokens and introduces latency or rate-limit delays.

prompt2tree solves this. Request a visual folder tree from your LLM, copy the string, and run pt -c (or pt structure.txt). Your entire project architecture is scaffolded instantly on your local machine for zero token cost.

---

⚡ Quick Start

1. Installation

pip install prompt2tree

To enable direct OS clipboard reading, install with the clip extra:

pip install "prompt2tree[clip]"

---

2. Usage Workflows

Option A: Directly from Clipboard (Fastest)

Copy any tree output from ChatGPT or Claude, then run:

pt -c
# or
prompt2tree --clip

Option B: From a Text File

pt structure.txt

If no arguments are passed, pt automatically looks for structure.txt in the working directory.

Option C: Piping via Stdin

cat structure.txt | pt

---

✨ Key Features

• 🧹 LLM Output Sanitization: Automatically strips Markdown backticks (```), conversational chatter, and inline explanatory comments (main.py # application entrypoint).
• 🌲 Universal Tree Support: Parses Unicode box-drawing trees (├──, └──), ASCII pipe/hyphen variants (|--, \--), and plain tab/space-indented hierarchies.
• 📄 Smart Boilerplate Auto-Fill: Automatically populates common files (.gitignore, .env.example, README.md, pyproject.toml, package.json, Dockerfile, __init__.py) with valid base templates instead of leaving 0-byte empty files.
• ⚡ Dual Executable Names: Run as prompt2tree or the two-letter shorthand pt.
• 📦 Zero Core Dependencies: Built with pure Python standard library modules (pathlib, argparse, re).

---

📂 Example Input & Output

Given raw text copied from an LLM prompt:

Here is your recommended project structure:

```text
social_media_crew/
├── .env.example
├── pyproject.toml
├── README.md
├── src/
│   └── social_media_crew/
│       ├── __init__.py
│       ├── main.py
│       └── config/
│           ├── agents.yaml
│           └── tasks.yaml
└── tests/
    └── test_models.py

Running `pt structure.txt` creates the filesystem structure:

```text
🌲 prompt2tree complete! Created 4 directories and 7 files.

---

🛠️ CLI Reference

Option	Short	Description
[file]		Path to text file containing tree structure (defaults to structure.txt)
--clip	-c	Read tree structure directly from OS clipboard
--version	-v	Show program version and exit
--help	-h	Show help message and exit

---

📄 Automated Boilerplate Defaults

prompt2tree detects key configuration filenames and populates them automatically:

• .gitignore $\rightarrow$ Standard Python __pycache__, .env, .venv rules.
• .env.example $\rightarrow$ Placeholder environment variables (PORT, DATABASE_URL, SECRET_KEY).
• README.md $\rightarrow$ Default project title heading and prompt2tree footer.
• pyproject.toml $\rightarrow$ Minimal valid setuptools build table.
• package.json $\rightarrow$ Valid minimal JSON package schema.
• Dockerfile $\rightarrow$ Starter Python container configuration.

---

🤝 Contributing

Contributions, bug reports, and feature ideas are welcome.

If you'd like to improve prompt2tree:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/your-improvement)
3. Make your changes and test them locally
4. Commit your work (git commit -m "Add your improvement")
5. Push the branch (git push origin feature/your-improvement)
6. Open a pull request with a clear description of the change

For larger changes, please open an issue first so the maintainers can review the idea and direction before you start.

---

📜 License

Distributed under the MIT License. See LICENSE for details.