# Use and adapt whirl

Use the documented interfaces and source layout for **whirl**. The sections below retain the README’s examples and configuration details.

## Features

- **Every top model** in one conversation, routed through
  [OpenRouter](https://openrouter.ai), with adjustable thinking levels.
- **Living artifacts:** documents, charts, and full interactive pages that
  stay editable in a side panel and can be shared by link.
- **Integrations** with your own tools over MCP (OAuth included), plus
  installable skills that teach Whirl new tricks.
- **Long-term memory** that carries preferences and projects across chats.
- **Live web search** and page reading for answers grounded in today's web.
- **Locked chats**, encrypted on your device with a password the server never
  sees, answered only by zero-retention models.
- **Incognito mode**, message queueing, voice input, image generation, file
  attachments, folders, sharing, and a lot of care around motion and polish.
- **Light and dark mode**, accent colors, and an installable mobile web app.

## Tech stack

| Layer     | What it uses                                                         |
| --------- | -------------------------------------------------------------------- |
| Web app   | [Next.js 16](https://nextjs.org), React 19, Tailwind CSS v4, Motion  |
| Backend   | [Convex](https://convex.dev): database, functions, streaming, crons  |
| Auth      | [Clerk](https://clerk.com)                                           |
| Models    | [OpenRouter](https://openrouter.ai) via the [AI SDK](https://ai-sdk.dev) |
| Tooling   | [Bun](https://bun.sh) workspaces, TypeScript                         |

Everything beyond Convex, Clerk, and OpenRouter is **optional** and switches
on with its own keys: billing (Autumn), web search (Exa), memory
(Supermemory), analytics (PostHog, Axiom), tracing (Braintrust), email
(Resend), and the support agent (Median). Leave them out and Whirl hides the
features they power. See [docs/configuration.md](https://github.com/Up-to-code/whirl/blob/main/docs/configuration.md).

## Repository layout

```
apps/
  v2/         The web app (Next.js). This is the one in production.
  console/    Admin console for models, integrations, and skills (Vite)
  mobile/     Native app (Expo)
  waitlist/   Standalone waitlist page
  remotion/   Promo video compositions
  legacy/     The previous web app, kept for reference. Not maintained.
packages/
  backend/    Convex backend: schema, functions, and the AI pipeline
docs/         Guides for self-hosting, configuration, and architecture
brand/        Logo, colors, banners, and app icons
```

## Commands in the root manifest

The captured [package.json](https://github.com/Up-to-code/whirl/blob/HEAD/package.json) declares the following scripts. Run them from the directory containing that manifest.

| Command | Script |
| --- | --- |
| `npm run dev` | `concurrently -n v2,console,convex -c cyan,magenta,yellow "bun run dev:v2" "bun run dev:console" "bun run dev:backend"` |
| `npm run build` | `bun run --cwd apps/v2 build` |

## Troubleshoot a local change

1. Reproduce the smallest example from the [quick-start guide](/docs/up-to-code-whirl/quick-start-guide).
2. Compare required configuration and dependency versions with the README.
3. Check the linked issue tracker for the same error. Include the command, runtime version, and relevant error when reporting a problem; omit credentials.

## Source and help

- [GitHub repository](https://github.com/Up-to-code/whirl)
- [Original README](https://github.com/Up-to-code/whirl/blob/main/README.md)
- [Issues and existing reports](https://github.com/Up-to-code/whirl/issues)
- [Open the project website](https://whirl.chat)

The catalog identifies the license as **MIT**. Read the repository license before redistributing source or assets.

This catalog entry is a fork. The README may describe upstream packages, domains, or release procedures; those destinations do not establish a separate release of this fork.