Skip to main content

Create a new project

Feather asks for the app type first:Then about optional features:
  • Background jobs. Thread pool by default, optionally Redis.
  • Auto-approve users. Activate new signups immediately. Authenticated apps only.
  • Caching. Memory for development, optionally Redis for production.
  • File storage. Local filesystem for development, optionally GCS for production.
  • Email. Resend for transactional email. Authenticated apps only.
  • Display name field. Adds display_name to the User model. Authenticated apps only.
  • Admin email. Creates your first admin user. Authenticated apps only.
feather new myapp --no-prompt skips the questions and uses minimal defaults. Every question also has a flag (--app-type, --database, --jobs/--no-jobs, --cache/--no-cache, --storage/--no-storage, --email/--no-email, --auto-approve-users/--no-auto-approve-users, --admin-email), so a script can scaffold an app without a terminal; add --json to read the result back.

Set up the database

feather new generates the first migration and applies it, so there is only the admin user left to create. Commit the migration with the rest of the app: a deploy applies it, and nothing else creates your tables.
If the database was not reachable while the app was created, run the two commands it printed first:

Start the dev server

Open http://localhost:5173. Vite serves frontend assets with hot module replacement, and Flask runs on port 5000 behind the proxy. CSS and JavaScript changes appear immediately. Template and Python changes trigger a reload.
Using background jobs with the thread backend? Set FLASK_DEBUG=0 in .env. Flask’s auto-reloader kills background threads on every file change, so jobs die mid-execution each time you save. Use JOB_BACKEND=sync if you need debug mode.

​
What the scaffold gives you

Every project includes a CLAUDE.md and an AGENTS.md with the same content, written together so they cannot drift, plus a .claude/settings.json that pre-approves the read-only commands an assistant needs. Treat them as a starting point and add your own domain rules as the app grows. What makes them useful is that the rules are checkable:

​
Where to go next

Build something real

The Kanban tutorial takes this scaffold to a deployed multi-tenant app across six parts, with the prompts to hand Claude at each step.

Project structure

Where every file goes, and what auto-discovery expects.

Working with AI assistants

How the conventions files and feather check fit together.