codePilot Agent

From natural language requirements to a deployed application — in one CLI tool.

codePilot is an intelligent automation agent for Python/FastAPI developers. It reads your plain‑English requirements and your existing backend code, reverse‑engineers the database schema, creates the database, and generates production‑ready deployment configs — all from a single command.

---

Features

• Understands natural language — Describe your app in plain English; codePilot extracts entities, fields, endpoints, and auth requirements.
• Reverse‑engineers FastAPI code — Walks your project's AST to discover SQLAlchemy models, route handlers, database connections, and dependencies — no manual configuration needed.
• Generates database schemas — Outputs MySQL DDL or Alembic migration scripts, optionally enriched with fields from your requirements that aren't yet in the code.
• Creates the database — Connects to a MySQL server and runs your schema.
• Deploys your application — Generates Dockerfiles, docker‑compose (with MySQL), GitHub Actions workflows, Railway configs, and Render blueprints.
• Works as a pipeline — One codepilot all command runs the entire flow.

---

How it works

┌─────────────┐     ┌──────────────┐     ┌───────────────┐     ┌────────────┐     ┌──────────┐
│ Requirements │────▶│   Parse &    │────▶│  Generate     │────▶│  Create    │────▶│  Deploy  │
│  (text file) │     │   Analyze    │     │  Schema / DDL │     │  Database  │     │  (Docker │
│              │     │   Code       │     │  (MySQL /     │     │  (MySQL)   │     │  / CI)   │
│              │     │   (AST)      │     │   Alembic)    │     │            │     │          │
└─────────────┘     └──────────────┘     └───────────────┘     └────────────┘     └──────────┘

You can run any step in isolation or the whole pipeline with a single command.

---

Prerequisites

Requirement	Notes
Python ≥ 3.10	Required
MySQL server	Only needed for codepilot db / codepilot all (skip with --skip-db)
mysql CLI	Only if you want codePilot to create the database for you
Docker + docker-compose	Only if you want codePilot to deploy with containers

---

Installation

git clone <repo-url>
cd codepilot
pip install -e .

This installs the codepilot command globally.

---

Quick start

Create a requirements file and run the full pipeline:

# 1. Describe your app
cat > requirements.txt << 'EOF'
Project "BlogAPI" - A blogging platform with users and posts.
Entity User (id int, username str, email str)
Entity Post (id int, title str, content text, author_id int)
GET /posts - list all posts
POST /posts - create a post
auth required
EOF

# 2. Point the agent at your FastAPI project (skipping DB and deploy for now)
codepilot all /path/to/your/project --skip-db --no-deploy

The agent will:

1. Parse your requirements and extract entities (User, Post), fields, endpoints, and auth.
2. Analyze your FastAPI code to find SQLAlchemy models, routes, and database config.
3. Generate a schema.sql file that merges both sources.
4. Report that DB creation and deployment were skipped.

When you're ready to go further, add --db-name myapp and --run to create the database and deploy with Docker.

---

Commands

codepilot parse — Understand requirements

# From a file
codepilot parse -f requirements.txt

# From stdin
echo 'Project "TodoAPI" with Entity Task (id int, title str, done bool)' | codepilot parse

Output:

Project Spec: todoapi  |  Auth: false
Entities:
  - Task (task) fields: ['id: INTEGER', 'title: VARCHAR(255)', 'done: BOOLEAN']

---

codepilot analyze — Understand backend code

codepilot analyze /path/to/project

Scans all .py files (excluding venv/) and reports:

• Models — SQLAlchemy model names and table names
• Routes — HTTP method + path for every decorated endpoint
• Database type — MySQL / PostgreSQL / SQLite (detected from your connection string)
• Auth — Whether OAuth2/JWT libraries are imported
• Dependencies — Contents of requirements.txt, pyproject.toml, or Pipfile

Output:

Project Analysis:
  Framework: fastapi  |  DB: mysql  |  Auth: yes

Models:
  - User (users)
  - Post (posts)

Routes:
  GET    /users
  POST   /users
  GET    /posts

---

codepilot schema — Generate database schemas

# From code only
codepilot schema --path /path/to/project -o schema.sql

# From code + requirements (fields in requirements but missing from code are added)
codepilot schema --path /path/to/project --requirements reqs.txt -o schema.sql

# Generate an Alembic migration script instead of raw SQL
codepilot schema --path /path/to/project --alembic -o migrations/001_auto.py

The generated DDL includes:

• CREATE TABLE for every model with appropriate MySQL types
• AUTO_INCREMENT PRIMARY KEY (auto‑detected from your model fields)
• created_at / updated_at timestamps
• Indexes on foreign‑key columns (*_id)
• Enriched fields from requirements that don't exist in the code yet

---

codepilot db — Create the database

# Create a database
codepilot db --db-name myapp

# Create + apply a schema
codepilot db --db-name myapp --schema schema.sql

# With custom MySQL credentials
codepilot db --db-name myapp --schema schema.sql \
  --mysql-user root --mysql-password secret \
  --mysql-host 127.0.0.1 --mysql-port 3306

---

codepilot deploy — Generate deployment configs

# Docker + docker-compose (with MySQL service)
codepilot deploy /path/to/project --docker

# Docker + GitHub Actions CI/CD
codepilot deploy /path/to/project --docker --github

# Build and run immediately (detached mode)
codepilot deploy /path/to/project --docker --run --detach

# Deploy to Railway (requires Railway CLI)
codepilot deploy /path/to/project --railway --railway-token xxx

# Generate a Render blueprint (render.yaml)
codepilot deploy /path/to/project --render

What gets generated:

Flag	Files created
--docker	Dockerfile, docker-compose.yml (with MySQL 8.0 service + health check)
--github	.github/workflows/deploy.yml (runs on push to main)
--railway	Deploys directly via Railway CLI
--render	render.yaml

---

codepilot all — Run the full pipeline

# Minimal (skip DB and deploy)
codepilot all /path/to/project --skip-db --no-deploy

# Full pipeline with custom database name
codepilot all /path/to/project --db-name myapp

# Full pipeline with MySQL credentials
codepilot all /path/to/project \
  --db-name myapp \
  --mysql-user root --mysql-password secret

# Full pipeline + deploy with Docker
codepilot all /path/to/project --db-name myapp --run

Flags:

Flag	Default	Description
--db-name	(folder name)	Name of the MySQL database
--skip-db	false	Skip database creation
--no-deploy	false	Skip deployment config generation
--run	false	Run docker-compose up --build after generation
--mysql-user	root	MySQL user
--mysql-password	(empty)	MySQL password
--mysql-host	127.0.0.1	MySQL host
--mysql-port	3306	MySQL port

---

Example workflow

Let's build and deploy a blog API from scratch.

1. Describe your app

cat > blog_reqs.txt << 'EOF'
Project "BlogAPI" built with FastAPI.
Entity User (id int, name str, email str, bio text)
Entity Post (id int, title str, content text, author_id int, published bool)
Entity Comment (id int, post_id int, author_id int, body text)
GET /posts - list published posts
POST /posts - create a post
GET /posts/{id} - get a single post
POST /posts/{id}/comments - add a comment
GET /users/me - get current user
auth required
EOF

2. Run the pipeline against your FastAPI project

codepilot all /path/to/blog-api \
  --db-name blog_api \
  --mysql-user root \
  --run

codePilot will:

• Parse 3 entities and 5 endpoints from your requirements
• Analyze your FastAPI code to match models and routes
• Generate schema.sql (with any extra fields from requirements merged in)
• Create the blog_api MySQL database
• Generate a Dockerfile + docker-compose.yml
• Build and start everything with Docker

3. Visit http://localhost:8000/docs — your API is live.

---

Configuration

codePilot stores persistent config at ~/.codepilot/config.json:

{
  "RAILWAY_TOKEN": "your-token-here",
  "mysql_user": "root",
  "mysql_password": "secret"
}

You can also set these as environment variables — they take precedence over the config file.

export RAILWAY_TOKEN=xxx
export mysql_password=secret

---

Roadmap

• Support for PostgreSQL and SQLite schema generation
• Detection of Pydantic v2 models and SQLModel
• Support for Django and other Python frameworks
• Interactive mode (walk through requirements step by step)
• Export to Terraform / Pulumi for cloud infrastructure

---

License

MIT

codePilot