spawnio 1.0.7

---

Contents

• The Problem Spawn Solves
• Features
• Prerequisites
• Installation
• Usage
• Project Templates
  • 1. Backend API
  • 2. CLI Application
  • 3. Automation Tool
  • 4. AI Chatbot
  • 5. AI Agent
  • 6. RAG System
  • 7. Data Project
  • 8. MCP Server
• Bring Your Own Structure
• Other Commands
  • spawn doctor
  • spawn version
  • Publish to GitHub
• Running the Tests
• Roadmap
• Contributing
• License

---

The Problem Spawn Solves

Every new Python project starts with the same manual ritual:

mkdir my-project && cd my-project
mkdir src tests docs
touch README.md .gitignore
git init
python -m venv .venv && source .venv/bin/activate
...

It's repetitive. It's inconsistent. And you haven't written a single line of real code yet.

Spawn collapses all of that into one command: spawn create

---

Features

Feature	What it does
Intent-based templates	Backend API (FastAPI / Flask / Django), CLI Application (Typer / Click / Argparse), Automation Tool, AI Chatbot, AI Agent, RAG System, Data Project (Analysis / Dashboard / ETL / Machine Learning), MCP Server
Bring your own structure	Paste any folder layout — Tree, Markdown list, or Indented — and Spawn builds exactly that, no blueprint required
Extras system	Opt-in ruff, pytest, Docker, GitHub Actions — installed and wired automatically
Dependency installation	uv add runs automatically with the right packages for your choices
Git + uv	Optionally runs git init, uv init, and uv venv
Non-interactive mode	Scaffold with --name/--template/etc. flags or a --config JSON file — zero prompts, safe for scripts and agents
Agent context files	Every project ships an AGENTS.md; add --claude-md for an identical CLAUDE.md alongside it
Arrow-key menus	Every prompt in spawn create is arrow-key/spacebar driven, not typed numbers
GitHub publishing	Connects your project to an existing GitHub repo and pushes the initial commit
spawn doctor	Scores your project's health out of 100, with per-category breakdowns and a prioritized next step

---

Prerequisites

• Python 3.12+ — Download here

  pip install spawnio will silently return "no matching distribution" on Python < 3.12. If you're using uv, run uv python install 3.12 to get a compatible interpreter in seconds.

• uv — Install guide
• Git — Download here

First time with uv? Run pip install uv or check their quickstart.

---

Installation

Option 1 — Install from PyPI (recommended)

pip install spawnio

or, using uv:

uv tool install spawnio

or run it without installing:

uvx --from spawnio spawn create

You can now run spawn from anywhere on your machine.

Option 2 — Install from source (for contributing)

git clone https://github.com/Abhiix0/spawn.git
cd spawn
uv sync
uv tool install .

---

Usage

Quick overview — spawn with no arguments

Running spawn with no arguments shows the banner, the installed version, and the list of available commands — useful when you just want a reminder of what's available without starting a project flow.

SPAWN — scaffold your next project
v1.0.6

Commands
  create    Scaffold a new project
  doctor    Check the health of a project directory
  version   Show the installed version

Run spawn COMMAND --help for details on a command.

---

spawn create

spawn create

Spawn walks you through a short prompt sequence. The number of steps depends on the template you pick.

Step 1 — Name your project

Project Name: my-api

Spawn rejects names with spaces or special characters, and tells you immediately if that directory already exists.

Step 2 — Pick a template

Use the arrow keys to move, Enter to select — the same pattern every prompt in Spawn follows.

? Choose a template (Use arrow keys)
 » Backend API
   CLI Application
   Automation Tool
   AI Chatbot
   AI Agent
   RAG System
   Data Project
   MCP Server
   Custom Structure

Step 3 — Additional prompts (template-dependent — framework, provider, project type, and/or extras, depending on what you picked. See Project Templates below for each one's exact flow.)

Step 4 — Git

Initialize Git? [Y/n]: Y

That's it. Spawn generates the project, installs dependencies, and shows you exactly what to run next.

╭────── ✨ Project Created Successfully ──────╮
│                                              │
│  Project      my-api                         │
│  Template     Backend API                    │
│  Git          ✓ Enabled                      │
│  UV           ✓ Initialized                  │
│  Virtual Env  ✓ Created                      │
│                                              │
│  Next Steps                                  │
│    cd my-api                                 │
│    uv run uvicorn app.main:app --reload      │
│                                              │
╰──────────────────────────────────────────────╯

---

Project Templates

Every template below follows the same shape: best for, structure, prompts you'll see, available extras, and how to run it.

1. Backend API

Best for: REST APIs, microservices, backend web apps.

my-api/
├── app/
│   ├── api/routes/health.py   # GET / → {"status": "running"}
│   ├── core/config.py         # pydantic-settings config
│   ├── models/
│   ├── schemas/
│   ├── services/
│   └── main.py
├── tests/
│   └── test_health.py
├── .env.example
├── README.md
└── .gitignore

Prompts:

? Choose a framework (Use arrow keys)
 » fastapi
   flask
   django

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ docker
 ○ github-actions

Available extras: ruff pytest docker github-actions

Run it:

Framework	Start command
FastAPI	uv run uvicorn app.main:app --reload
Flask	uv run python run.py
Django	uv run python manage.py runserver

cd my-api
uv run uvicorn app.main:app --reload
# GET http://localhost:8000/ → {"status": "running"}

---

2. CLI Application

Best for: developer tools, automation commands, project generators, setup wizards.

my-cli/
├── src/
│   ├── commands/
│   ├── prompts/     # Interactive type only
│   ├── ui/           # Interactive type only
│   ├── utils/
│   └── main.py
├── tests/
├── README.md
└── .gitignore

Prompts:

? Choose CLI Type (Use arrow keys)
 » utility
   interactive

? Choose a framework (Use arrow keys)
 » typer
   click
   argparse

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ github-actions

Available extras: ruff pytest github-actions

Run it:

cd my-cli
uv run python -m src.main hello       # Utility
uv run python -m src.main greet       # Interactive

---

3. Automation Tool

Best for: scheduled jobs, data pipelines, reporting systems, integration automation.

my-automation/
├── src/
│   ├── workflows/
│   ├── tasks/
│   ├── integrations/
│   ├── utils/
│   └── main.py
├── logs/
├── tests/
├── .env.example
└── README.md

Prompts:

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ github-actions

Available extras: ruff pytest github-actions

Run it:

cd my-automation
uv run python -m src.main

---

4. AI Chatbot

Best for: customer support bots, study assistants, conversational AI tools.

my-chatbot/
├── src/
│   ├── chatbot/
│   ├── providers/
│   ├── prompts/
│   ├── memory/
│   ├── config/
│   └── main.py
├── tests/
├── .env.example
└── README.md

Prompts:

? Choose a framework (Use arrow keys)
 » pydantic-ai
   openai-sdk
   litellm

? Choose a provider (Use arrow keys)
 » openai
   anthropic
   gemini
   openrouter
   ollama
   groq

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ rich
 ○ github-actions

Available extras: ruff pytest rich github-actions

Run it:

cd my-chatbot
# Add your provider's API key to .env
uv run python -m src.main

---

5. AI Agent

Best for: task automation, research assistants, tool-calling workflows.

my-agent/
├── src/
│   ├── agent/
│   ├── tools/
│   ├── prompts/
│   ├── config/
│   └── main.py
├── tests/
├── .env.example
└── README.md

Prompts:

? Choose a framework (Use arrow keys)
 » pydantic-ai
   openai-agents

? Choose a provider (Use arrow keys)
 » openai
   anthropic
   gemini
   openrouter
   ollama
   groq

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ github-actions

If you pick openai-agents, only openai and openrouter appear as provider choices — the list is filtered per framework.

Available extras: ruff pytest github-actions

Run it:

cd my-agent
# Add your provider's API key to .env
uv run python -m src.main

Every generated AI Agent project ships with one working tool (a calculator), so you can see tool-calling work immediately — no external services or extra setup beyond your chosen provider's API key.

---

6. RAG System

Best for: documentation Q&A, knowledge base search, document retrieval.

my-rag/
├── data/
│   └── sample_knowledge.md
├── src/
│   ├── knowledge/
│   ├── ingestion/
│   ├── retrieval/
│   ├── config/
│   └── main.py
├── tests/
├── chroma_db/        # created on first run
├── .env.example
└── README.md

Prompts:

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ github-actions

RAG System uses a fixed stack — LlamaIndex + ChromaDB + OpenAI — so there's no framework or provider prompt, unlike Chatbot and Agent. On first run, it automatically ingests documents from data/ into a local ChromaDB index, then lets you ask questions against them. Requires an OPENAI_API_KEY (used for both the LLM and embeddings).

Available extras: ruff pytest github-actions

Run it:

cd my-rag
# Add OPENAI_API_KEY to .env
uv run python -m src.main
# Documents are ingested automatically on first run

---

7. Data Project

Best for: exploratory data analysis, internal dashboards, data cleaning pipelines, quick ML prototyping.

my-data-project/
├── data/
├── notebooks/    # Data Analysis
├── reports/      # Data Analysis
├── dashboard/    # Dashboard
├── pipelines/    # ETL Pipeline
├── models/       # Machine Learning
├── experiments/  # Machine Learning
├── src/
├── tests/
└── .env.example  # ETL Pipeline

Prompts:

? Choose Project Type (Use arrow keys)
 » Data Analysis
   Dashboard
   ETL Pipeline
   Machine Learning

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ github-actions

Available extras: ruff pytest github-actions

Run it:

Type	Ships with	Start command
Data Analysis	Sample CSV + starter notebook (summary stats, saved chart)	uv run jupyter notebook
Dashboard	Streamlit app with sidebar filter + Plotly chart	uv run streamlit run dashboard/app.py
ETL Pipeline	Intentionally messy sample CSV + cleaning script (INPUT_PATH/OUTPUT_PATH via .env)	uv run python -m pipelines.run
Machine Learning	Labeled sample dataset + training script (RandomForestClassifier, logs to experiments/)	uv run python src/train.py

# Example — Machine Learning
cd my-data-project
uv run python src/train.py
# Test accuracy: 1.0000
# Model saved to models/model.joblib
# Experiment logged to experiments/20260711_113233.json

---

8. MCP Server

Best for: exposing tools and data to Claude Desktop, Claude Code, or any MCP-compatible client.

my-mcp-server/
├── src/
│   ├── server.py   # FastMCP instance, one example tool + resource
│   └── __init__.py
├── tests/
│   └── test_server.py
├── .env.example
└── README.md

Prompts:

? Choose extras (space to toggle, enter to confirm)
 ● ruff
 ● pytest
 ○ github-actions

MCP Server uses a fixed stack — the official mcp Python SDK's FastMCP — so there's no framework or provider prompt, the same as RAG System.

Available extras: ruff pytest github-actions

Run it:

cd my-mcp-server
uv run python -m src.server
# Waits on stdio for an MCP client to connect

Then add it to your MCP client's config — see the generated project's own README.md for the exact JSON snippet.

---

Bring Your Own Structure

None of the eight templates above fit? Custom Structure shows up as the last option in the same spawn create picker — it's not a separate command, just a different path through the same flow.

Paste any of three text formats — Unix tree output, a Markdown list, or plain indented hierarchy — and Spawn parses it, previews the detected folders and files, then creates the structure with the same Git and uv setup as every other template.

spawn create
# → Custom Structure

Paste your project structure.
Supported formats: Tree (├──/└──), Markdown list (- item), Indented hierarchy
Finish with Ctrl+D (Ctrl+Z then Enter on Windows)

app/
├── api/
├── services/
└── tests/
README.md
.gitignore
^Z

Detected
Folders : 4
Files   : 2

Initialize Git? [Y/n]: Y
Initialize uv? [Y/n]: Y
Dependencies (comma separated, optional): fastapi, uvicorn

? Optional Setup (space to toggle, enter to confirm)
 ● Ruff
 ● Pytest
 ○ Pre-commit
 ○ Dockerfile

Additional ignore patterns (optional, comma separated): data/, *.csv

Proceed? [Y/n]: Y

What Spawn does automatically when it sees these files:

• README.md — generated with your project name, a structure tree, and setup instructions (not left empty)
• .gitignore — populated with Python defaults (.venv/, __pycache__/, .pytest_cache/, .mypy_cache/, .ruff_cache/, etc.) plus any patterns you added, deduplicated

The Dependencies prompt (shown only when uv is enabled) installs packages immediately via uv add.

The Optional Setup menu installs dev tools via uv add --dev and generates their config files: ruff.toml, tests/__init__.py, .pre-commit-config.yaml, and/or Dockerfile.

Non-Interactive Mode

Skip all prompts by passing flags directly or pointing to a JSON config file.

Using flags:

spawn create --name my-api --template backend-api --framework fastapi --extras ruff,pytest --git

Using a config file:

{
  "name": "my-api",
  "template": "backend-api",
  "framework": "fastapi",
  "extras": ["ruff", "pytest"],
  "git": true,
  "uv": true
}

spawn create --config spawn.json

--config takes precedence over individual flags. Add --dry-run to either form to validate the config and print it without creating any files.

Custom Structure is interactive-only in this version.

---

Other Commands

spawn doctor

Scores your project's health out of 100 — per-category breakdowns, tiered recommendations, and a single prioritized next step.

spawn doctor
spawn doctor ./path/to/project

╭─────────────── 🏥 Project Health Report ─────────────────╮
│                                                           │
│  🟡 Good                                                  │
│  Some improvements recommended.                           │
│                                                           │
│  Project Score: 82%                                       │
│                                                           │
│  Documentation — 67                                       │
│  Version Control — 100                                    │
│  Configuration — 75                                       │
│  Testing — 80                                             │
│  Automation — 50                                          │
│  Code Quality — 100                                       │
│                                                           │
╰───────────────────────────────────────────────────────────╯

╭──────────────────── Recommendations ───────────────────────╮
│                                                            │
│  Critical                                                  │
│    • Initialize a git repository with 'git init'.          │
│                                                            │
│  Recommended                                               │
│    • Add a CHANGELOG.md to document project history.       │
│    • Configure GitHub Actions for CI/CD.                   │
│                                                            │
│  Optional                                                  │
│    • Add a Dockerfile for containerized deployment.        │
│                                                            │
╰────────────────────────────────────────────────────────────╯

╭──────────────────── 🎯 Next Best Step ─────────────────────╮
│                                                             │
│  Initialize a git repository with 'git init'.               │
│  Estimated effort: 30 seconds                               │
│                                                             │
╰─────────────────────────────────────────────────────────────╯

Checks span six categories — Documentation, Version Control, Configuration, Testing, Automation, and Code Quality (Ruff, type checking, pre-commit) — all filesystem-based, nothing is executed or sent over the network.

spawn version

spawn version
# → Spawn v1.0.7

Publish to GitHub

After creation, if Git was enabled, Spawn asks:

Publish to GitHub? [y/N]: y
Repository URL: https://github.com/your-username/my-project

Spawn stages all files, creates the initial commit, renames the branch to main, adds the remote, and pushes.

The repository must already exist on GitHub. Spawn connects to it — it does not create it.

---

Running the Tests

uv run pytest

All tests should pass. If they don't, please open an issue.

---

Roadmap

Shipped

Version	Highlight
v1.0.7	Fixed UTF-8 console crash on Windows when stdout is redirected/piped, added Windows reserved device name validation (CON, PRN, AUX, NUL, COM1–9, LPT1–9), clarified Python 3.12 requirement
v1.0.6	Removed duplicate banner from spawn create; spawn alone now shows the banner and command overview
v1.0.5	Published to PyPI as spawnio; arrow-key selection menus, no-args banner, consistent Ctrl+C handling
v1.0.4	AGENTS.md / CLAUDE.md generation for every project, --claude-md opt-in
v1.0.3	MCP Server intent — official mcp SDK, one working tool + resource
v1.0.2	Non-interactive mode — --name/--template flags or --config JSON
v1.0.1	Custom Structure: dependency install, optional dev tooling setup, smart README/.gitignore generation
v1.0.0	Custom Structure workflow (paste any folder layout) + Doctor 2.0 (per-category scores, tiered recommendations)
v0.9.0	Data Project intent — analysis, dashboard, ETL, ML sub-types
v0.8.0	RAG System intent — LlamaIndex + ChromaDB
v0.7.0	AI Agent intent — tool-calling with PydanticAI / OpenAI Agents SDK
v0.6.0	AI Chatbot intent — 3 frameworks, 6 providers, runtime memory
v0.5.0	Automation Tool intent — workflows, logging, working example out of the box
v0.4.0	CLI Application intent — Typer/Click/Argparse, Utility/Interactive types
v0.3.0	Backend API intent — FastAPI/Flask/Django, extras system, .spawn/meta.json
v0.2.0	GitHub publishing from the CLI, spawn doctor health checker, CI workflow
v0.1.0	Initial release — spawn create, 4 templates, Git + uv integration

---

What's next

Nothing formally scheduled yet. Ideas under consideration live in Issues; open one if there's something you'd want to see.

For the full version history, see CHANGELOG.md.

---

Contributing

Contributions are welcome. Whether it's a bug fix, a new intent, or something from the roadmap — here's how to get started.

Adding a new intent

1. Create the intent directory

src/spawn/templates/your_intent/
├── __init__.py    ← subclass BaseTemplate
└── content.py     ← all file content as string constants

2. Register it

In src/spawn/core/registry.py, add a TemplateMetadata entry to TEMPLATES with your slug, display name, description, template class, and any available_frameworks or available_extras.

3. Write tests

Add coverage in tests/test_templates.py and tests/test_generator.py. Mock initialize_uv and install_packages in generator tests.

Before submitting a PR

uv run pytest        # must pass
uv run ruff check .  # must be clean

---

License

This project is open source under the MIT License.

---