Creating a New Project
Use the New Project wizard to scaffold a project from a Project Starter with AI-powered coding rules and an optional agent team.
Overview
In addition to adding existing folders, PandaOS can create new projects from a Project Starter. The wizard generates coding rule files that guide PandaOS's behavior, framework conventions, file patterns, best practices, so every session starts with the right context.
Opening the Wizard
Click the New Project tile on the Dashboard, then choose Create New Project.
The wizard walks you through Start, Configure, Agents, and Finalize. Configure is skipped when the starter has nothing to configure, and a Supabase or Database step appears in between when your choices call for one.
Step 1: Start
Pick a starting point. Start Fresh sits above the divider; the Project Starters follow below it, grouped under category headings.
| Starting point | Category | Description |
|---|---|---|
| Start Fresh | , | Empty project, no starter files or rules |
| Full-Stack App | Development | A web application with a database and a backend |
| Website | Development | Static sites with no database and no backend, a landing page, a personal homepage, a docs site, or a quick local tool |
| Analyze Data | Data | Notebooks and queries against a database, Supabase, or local files |
| Data Warehouse | Data | dbt and SQL pipelines with a layered warehouse architecture |
Step 2: Configure
Choose the technology stack for your project. Your choices determine which coding rules are generated. Start Fresh skips this step entirely, and each starter shows only the options that apply to it.
Framework (Full-Stack App)
Choose Next.js 16, React + FastAPI, Django, or select Other and type any framework name (Remix, Nuxt, SvelteKit, etc.). The generated rules include framework-specific conventions.
Database
| Option | Description |
|---|---|
| Supabase | Generates rules for Supabase Auth, Row Level Security, and the Supabase client |
| Other | Type a custom database (Drizzle + Postgres, Prisma, Firebase, etc.) |
| None | No database rules |
Deployment
| Option | Description |
|---|---|
| Vercel | Rules for Vercel deployment conventions, edge functions, and environment variables |
| GCP Cloud Run | Rules for containerized Cloud Run services, runtime ports, secrets, IAM, revisions, and rollout safety |
| Azure Container Apps | Rules for Azure Container Apps ingress, secrets, managed identity, revisions, scaling, and rollout safety |
| Other | Type a custom platform (AWS, Cloudflare, Railway, etc.) |
| None | No deployment rules |
Package Manager
Choose pnpm or npm. The generated rules reference the correct commands (pnpm add vs npm install).
Website
A static site has no database and no backend, so this starter shows a different set of options and skips the Supabase and Database steps entirely.
| Option | Choices |
|---|---|
| Framework | Astro, Vite + React, Next.js (static export), Vue / Nuxt, SvelteKit, Hugo, Plain HTML, or type your own |
| Site Type | Landing page, Blog / personal, Docs, or Local tool, this shapes the generated rules as much as the framework does |
| Content | Markdown files, a Git CMS (Decap, TinaCMS, Keystatic), a headless CMS fetched at build time, or content written directly in the components |
| Deployment | Vercel, Cloudflare, Netlify, GitHub Pages, your own, or none |
| Package Manager | pnpm or npm, hidden for Hugo and Plain HTML, which have no Node toolchain |
The Content options adapt to the framework: one with no file-based content layer, such as Vite + React, only offers a headless CMS or content in code.
The generated rules cover what static hosting actually demands, build-time environment variables are baked into the bundle and therefore public, forms need a third-party endpoint, and anything that has to stay fresh is either fetched in the browser or needs a rebuild. If a project outgrows those constraints, it wants the Full-Stack App starter instead.
Step 3: Agents
Configure an AI development team that structures how PandaOS works on your project. When enabled, PandaOS follows a multi-agent workflow with planning, design, build, and review phases.
Master Toggle
PandaOS Team, enable or disable the structured workflow. When off, PandaOS works in freeform mode with no enforced phases.
Agent Configuration
| Agent | Description |
|---|---|
| UX Designer | Creates HTML mockups before building. PandaOS produces a visual prototype first, then implements the real code. |
| Parallel Mode | Uses sub-agents for speed. PandaOS delegates independent tasks to run simultaneously. |
Testing Level
| Level | What It Does |
|---|---|
| Basic | Runs linting and type checks after implementation |
| Advanced | Linting + type checks + Playwright E2E tests for bigger features |
| None | No automated checks, manual verification only |
Code Review Level
| Level | Description |
|---|---|
| Light | Quick sanity check, catches obvious issues |
| Standard | Balanced review covering correctness, style, and edge cases |
| Strict | Thorough review including security, performance, and test coverage |
What Gets Created
Team configuration generates editable Markdown files in your project:
.pandaos/team/, Agent instruction files (designer, builder, reviewer).pandaos/features/, Feature tracking directory
You can customize these files after project creation to adjust agent behavior.
Step 4: Finalize
Summary
A tag row shows your selected configuration (e.g., "Next.js 16 + Supabase + Vercel + pnpm + Team").
Parent Folder
Choose where the project folder will be created. Type a path (supports ~ expansion) or click the folder icon to browse.
Project Name
Enter the folder name for your new project (e.g., my-app). The full path is shown below (e.g., ~/Projects/my-app/).
Start Building Immediately
When enabled (default), PandaOS opens a chat for the new project with a short message already in the box and a Getting started guide attached to it. Nothing is sent automatically, you review it first.
Send the message as it is and PandaOS walks you through the setup: it asks what you're building (purpose, audience, design language, color scheme), checks that the tools your stack needs are installed, scaffolds the project, and installs dependencies. It then registers every dev server the project needs, both of them for a split frontend/backend app, so each one gets a start button on the project overview, and builds a first real page or screen.
If the result is something you can look at, PandaOS opens it in the built-in browser as soon as it renders, so you watch the project come together rather than reading about it.
Prefer to describe the project yourself? Replace the text with your own pitch and send that instead, the guide treats it as your answers and only asks about what's still missing. You can also click the attachment to read or edit the guide, or remove it entirely.
What Happens After Creation
Everything below happens on its own once you click Create Project.
Tip: The generated rule files are plain Markdown. You can edit them at any time to refine PandaOS's behavior, add your own conventions, remove sections that don't apply, or add entirely new rules.
- A new folder is created at your chosen location
- Coding rule files are generated in
.pandaos/principles/based on your stack choices - If Team is enabled, agent files are created in
.pandaos/team/ - The project is registered in PandaOS and appears in the sidebar and dashboard
- If "Start building immediately" is on, a chat opens with the message and the guide ready to send