Chaos
Turn what you know into something people can use.
Chaos is an open platform for teaching and learning. Write lessons and put them in order as courses, then make them stick with quizzes, flashcards and live games. Connect Claude or ChatGPT and ask them to draft courses, quizzes and live sessions for you. Chaos runs no AI itself. It works in English and Arabic, is AGPL licensed, and you can try chaos.fail or host your own copy with Docker.
A typical loop: turn your notes into a lesson → add a quiz and flashcards → run the quiz as a live game in class → see who struggled and what to review.
What it does
Teach and learn
- Lessons and courses. A document-like editor with covers, icons, images, video, equations, tables, sources and citations. Put lessons in order as a course and publish it.
- Quizzes and flashcards. Answer keys, points, explanations and automatic marking. Attach them to lessons so learners can practise.
- Live games. Host a quiz on a big screen; people join from their phones with a PIN, answer against the clock and watch the leaderboard.
- Learning. Public courses and community lessons, saved lessons, progress and weak areas, and copies that keep the original author credited.
Build it with ChatGPT or Claude
- MCP connection. Connect your account once, then ask your assistant to turn notes into a course draft, write a quiz with explanations, open a live game lobby or review your weak areas. New content arrives as a draft for you to review. Setup guides: Claude, ChatGPT.
Forms, results and teams
- Forms and surveys. 16 question types, sections, branching and required rules, built in the same editor.
- Results you can use. Live summaries and charts, every response in detail, CSV, Excel and JSON export, webhooks and an HTTP API.
- Business teams. Teams with owner, admin and member roles edit shared forms, lessons, courses and folders together, and publish team-only lessons, courses, flashcards, forms, quizzes and live games. Free for a limited time.
- A look for every form. 18 themes (including Google Forms and Microsoft Forms styles), four ways to answer (page, sections, one at a time, swipe), optional sounds, your own colours and logo.
Also included: English and Arabic with right-to-left layouts, 21 templates, collaborators with roles, team-only (internal) publishing, version history and undo, opening and closing times with time zones, response limits and access codes, respondent edits with history, links, QR codes and embedding, a Max integration, and step-by-step guides at /docs.
Stack
- Next.js 16 (App Router) and React 19 for the web app
- Convex for the database, server functions, scheduling and file storage
- Clerk or self-hosted Better Auth backed by Convex for sign-in
- TypeScript everywhere; Vitest,
convex-test and Playwright for tests
Run it locally
You need Node.js 24.x, pnpm 12.10.1 (pinned in package.json), a backend deployment and a configured authentication provider. Choose Clerk + Convex, Better Auth + Convex Cloud, or Better Auth + self-hosted Convex with no required paid service. The complete setup and migration instructions are in self-hosting.
pnpm install
cp .env.example .env.local # then select and configure authentication
pnpm dev # runs next dev and convex dev together
For the default Clerk + Convex Cloud setup, on first run Convex asks you to sign in and creates a development deployment, then writes NEXT_PUBLIC_CONVEX_URL into .env.local. Leave NEXT_PUBLIC_CONVEX_SITE_URL empty when using Convex Cloud so Chaos derives the matching HTTP actions URL. Create Clerk's JWT template named convex using its Convex preset. The first backend deployment waits for its required issuer; keep pnpm dev running and set it from a second terminal:
npx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-app.clerk.accounts.dev
The app runs at http://localhost:3000. To make yourself an admin, sign in once, then run npx convex run admin:grantAdmin '{"email":"[email protected]"}'.
Email-based collaborator invitations require a verified email claim. Keep email and email_verified in the Clerk convex JWT template, with email_verified derived from {{user.email_verified}}, rather than a hardcoded value. Missing or false verification never grants invitation access. See Clerk JWT templates.
For Better Auth, set NEXT_PUBLIC_AUTH_PROVIDER=betterauth, NEXT_PUBLIC_APP_URL and both public Convex URLs. Set CHAOS_AUTH_PROVIDER=betterauth, the matching CHAOS_APP_URL and a random BETTER_AUTH_SECRET on Convex before deploying. Accounts and sessions live in Convex; no Clerk credentials, separate identity server or paid authentication service are required. Sign up at /sign-up. Existing accounts need an explicit operator binding before first use; see migration steps.
Environment variables
Every variable is listed with what it does in .env.example. The ones you need to start:
This is the beginning of the README. Read the rest at the original. Read the full README ↗
