Crew

An AI-powered engineering project planner. A user enters a plain-English description; five LangGraph agents — Planner, Architect, Coder, Reviewer, and Deployer — collaborate to produce a fully written, reviewed, tested, and deployed codebase, streamed live to the browser via SSE.

Prerequisites

• uv — Python package manager
• Python 3.11+
• A Gemini API key

Setup

1. Install uv (if not already installed):

   curl -LsSf https://astral.sh/uv/install.sh | sh

2. Clone / navigate to the project:

   cd crew

3. Create a virtual environment and install dependencies:

   uv sync

4. Configure environment variables:

   Create a .env file in the project root:

   cp .env.example .env   # or create it manually

   Add your Gemini API key:

   GEMINI_API_KEY=your_gemini_api_key_here

Running

Option 1 — via uv run (recommended)

uv run crew

With a custom recursion limit:

uv run crew --recursion-limit 50

Option 2 — via Python directly

uv run python src/main.py

Usage

When prompted, enter your project description:

Enter your project prompt: Build a REST API for a todo app using FastAPI and PostgreSQL

The agent will plan and generate the project files inside the generated_project/ directory.

Project Structure

crew/
├── pyproject.toml       # Python project metadata and dependencies
├── cloudbuild.yaml      # GCP Cloud Build / Cloud Run deployment
├── .env                 # Environment variables (not committed)
└── src/
    ├── main.py          # CLI entry point
    ├── api/
    │   ├── generate.py      # FastAPI SSE endpoint
    │   └── requirements.txt # Python dependencies
    ├── frontend/
    │   ├── app/
    │   │   ├── layout.tsx       # Root layout
    │   │   ├── page.tsx         # Main UI (prompt input + live stream display)
    │   │   ├── types.ts         # Shared TypeScript interfaces
    │   │   ├── constants.ts     # Fonts, example prompts, shared styles
    │   │   ├── hooks/
    │   │   │   └── useAgentStream.ts  # SSE state + fetch logic
    │   │   └── components/
    │   │       ├── AgentPipeline.tsx  # Live pipeline stepper
    │   │       ├── PlanCard.tsx
    │   │       ├── TaskList.tsx
    │   │       ├── FilesSection.tsx
    │   │       ├── ReviewSection.tsx
    │   │       └── DeploymentSection.tsx
    │   ├── next.config.ts   # API proxy for local development
    │   └── package.json     # Next.js dependencies
    └── agent/
        ├── graph.py         # LangGraph StateGraph (5-agent pipeline)
        ├── gke_tools.py     # GCP/GKE deployment tools
        ├── dockerfiles.py   # Dockerfile templates per tech stack
        ├── prompts.py       # System prompt builders per agent role
        ├── states.py        # Pydantic state models + GraphState TypedDict
        └── tools.py         # Sandboxed file I/O tools

---

Agent Pipeline

Five specialised agents run in sequence; the Coder loops until all files are written, and the Reviewer can send files back to the Coder for up to two revision rounds:

planner → architect → coder ↩ (loop) → reviewer → deployer → END
                   ↘ END (plan mode)   ↗ (revision, max 2 rounds)

Agent	Role	Output
Planner	Turns the user prompt into a structured project plan	Plan (name, description, techstack, features, files)
Architect	Breaks the plan into an ordered file-level task list; always schedules a final test-writing task	TaskPlan (ordered ImplementationTask list)
Coder	Implements one file per loop iteration using tool calls; writes test file as final task	Files written to generated_project/
Reviewer	Reads all generated files and produces a code review; routes back to Coder if errors found	ReviewResult (findings, severity, quality rating)
Deployer	Builds a Docker image via Cloud Build and deploys to GKE	DeploymentResult (live URL, TTL, namespace)

SSE event sequence streamed to the browser: plan → architecture → file_written (×N) → review → deployed → done

---

Running the Web UI (local development)

Two terminals are required: one for the Python API and one for the Next.js frontend.

Terminal 1 — Python API

source .venv/bin/activate
uvicorn src.api.generate:app --reload --port 8000

Terminal 2 — Next.js frontend

cd src/frontend

# Install Node dependencies (once)
npm install

# Create local env file pointing at the API
echo "NEXT_PUBLIC_API_URL=http://localhost:8000" > .env.local

# Start the dev server
npm run dev

Open http://localhost:3000, enter a project description, and watch the agent stream its progress in real time.

Note: Generated project files are written to /tmp/generated_project/ when running via the API.
When using the CLI (uv run crew), files are written to ./generated_project/ in the current directory.

---

Deploying to GCP

The app runs on Google Cloud Run (API + frontend) with user projects deployed to GKE via Cloud Build.

1. Set GEMINI_API_KEY as a Cloud Run environment variable or Secret Manager secret.
2. GOOGLE_CLOUD_PROJECT is auto-detected from the GCE metadata server — no manual configuration needed on Cloud Run.
3. Trigger a build and deploy with gcloud builds submit using cloudbuild.yaml.

Generated files in /tmp/ are ephemeral — they are lost after each request completes.

---

Development

Add a Python dependency:

uv add <package-name>

Add a frontend dependency:

cd src/frontend && npm install <package-name>

Linting & Formatting

uv run ruff check .        # check for issues
uv run ruff check . --fix  # auto-fix safe issues
uv run ruff format .       # format code (black-compatible)

Run both before committing:

uv run ruff check . --fix && uv run ruff format .