Creating a project

A project is a containerized workspace with its own filesystem, dev server, and AI agent context. This page covers what you can configure when you spin one up.

The dashboard

Project creation starts at the dashboard. The hero is a single prompt box — type what you want to build and the agent handles the rest. There is no wizard; Swarmz infers a sensible default from your prompt and drops you straight into the editor.

The flow exposes four optional controls before submission:

• Prompt — what you want to build (required)
• Framework — the starter stack (defaults to vite-react)
• Knowledge presets — docs and patterns to attach to the agent
• Skills — granular agent behaviours
• GitHub — import an existing repo instead of starting fresh

Hit submit and Swarmz generates a project name, provisions a container, scaffolds the framework, and opens the editor. Your first prompt is queued automatically so the agent starts building as soon as the workspace boots.

Naming rules

Project names are auto-generated from your first prompt, but you can rename anytime from project settings. Names must be 1 to 60 characters, lowercase letters, numbers, and hyphens only. They show in your dashboard and become part of the live preview URL.

If the generated title clashes with another project in your workspace, Swarmz appends a short hash. Renaming does not change the preview subdomain — that stays fixed for the lifetime of the project.

Framework choice

The framework controls what gets scaffolded into /workspace on the first boot. The agent's system prompt is also tuned per framework so it writes idiomatic code from the first turn.

vite-react (default) — a Vite + React 18 + TypeScript SPA with Tailwind, shadcn/ui, and React Router preconfigured. Pick this for dashboards, internal tools, or anything that doesn't need SSR. HMR is instant and the preview ships in seconds.

next-app — Next.js 15 with the App Router, TypeScript, Tailwind, and a server-component-first layout. Use it when you need SSR, RSC streaming, route handlers, or middleware. The agent is primed on App Router conventions so it never reaches for pages/.

remix — Remix with Vite, nested routing, and progressive-enhancement-friendly forms. Good fit for content-heavy apps where you want loaders and actions over client fetching.

astro — Astro with islands architecture, MDX support, and a content collection scaffold. The right pick for marketing sites, blogs, and docs where zero-JS-by-default matters.

blank — an empty container with package.json, .gitignore, and nothing else. Use it when you're importing from GitHub or want full control over the stack.

The first prompt

The first prompt is more important than any other input. Swarmz uses it for three things: the project name, the agent's seed context, and the initial scaffold beyond the framework template.

A clear prompt yields a clean scaffold. A vague prompt yields a generic landing page.

Build a landing page for a coffee subscription service with email signup.

From that, the agent scaffolds a hero, tier comparison, sign-up form wired to a placeholder action, footer, and dark theme — all in the chosen framework's idioms. Compare with make me a coffee site, which gets you a coffee-cup emoji and not much else.

For tips on writing prompts that produce specific output, see the AI agent docs.

Knowledge presets

Knowledge presets are curated bundles of facts the agent loads into context — API references, schema docs, framework conventions, integration patterns. They are not behaviour modifiers; they are documentation the agent can cite verbatim.

Attach a preset when your project depends on something the agent might not know cold: a Supabase project schema, Next.js App Router server-action quirks, Stripe webhook signatures, your in-house design tokens. The picker shows only published template-kind presets; internal guardrails are loaded automatically and never surface in the UI.

You can attach presets at creation or toggle them later from Project Settings > Knowledge. Each preset is fetched on demand by the agent via the ai-knowledge edge function, cached for five minutes, and counts toward the model's context window — so attach what you need and skip the rest.

Skills

Skills are granular agent capabilities that change how the agent works rather than what it knows. Where knowledge presets are facts, skills are behaviours.

Examples:

• shadcn/ui patterns — the agent prefers shadcn/ui primitives and matches your existing component conventions
• tailwind-expert — produces tighter, more idiomatic Tailwind class lists
• accessibility-first — adds ARIA attributes, focus traps, and keyboard handlers by default
• test-driven — writes a Vitest spec before implementation

Toggle skills per project from Settings > Skills. They stack — enabling shadcn/ui and accessibility-first together gives you accessible shadcn/ui components.

Importing from GitHub

If you have an existing codebase, connect GitHub during project creation and point Swarmz at the repo. Instead of running the framework scaffold, the agent clones your repo into the container, runs npm install (or pnpm, auto-detected), and starts the dev server. From there it works on your real code — every commit, branch, and file is yours.

Two-way sync keeps the container and the remote in step: pushes from Swarmz become commits on a branch you choose, and pulls bring upstream changes back into the container. You can link a repo at creation or after, from Settings > Integrations > GitHub. See the GitHub integration guide for the connection flow and permission scopes.

Project limits per plan

Active project counts are enforced at creation time:

Archived projects do not count against the limit. Archive a project from its card menu or from Settings > Danger zone; archiving stops the container, freezes the file tree, and removes the project from your active count without deleting any data. Restore at any time. Deleted projects are unrecoverable after 30 days.