whirl README

The project's README from github.com/whirlchat/whirl. As one markdown file: README.md.

The Whirl mark

Whirl

The AI chat app that sweats the details. Every top model, real memory,
living documents, and your own tools, in one fast and friendly place.

whirl.chat · Self-hosting · Architecture · Contributing

Whirl is a full-stack AI chat app built on Next.js and Convex. It's the code behind whirl.chat, published in full under the MIT license. Read it, run your own, or help make it better.

Features

Tech stack

Layer What it uses
Web app Next.js 16, React 19, Tailwind CSS v4, Motion
Backend Convex: database, functions, streaming, crons
Auth Clerk
Models OpenRouter via the AI SDK
Tooling Bun 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.

Quick start

You'll need Bun, a free Convex account, a Clerk application, and an OpenRouter API key.

git clone https://github.com/whirlchat/whirl.git
cd whirl
bun install

# 1. Create a Convex dev deployment and push the backend.
cd packages/backend
bunx convex dev            # first run walks you through creating a project

# 2. In another terminal, give the backend its secrets.
bunx convex env set CLERK_JWT_ISSUER_DOMAIN https://your-instance.clerk.accounts.dev
bunx convex env set OPENROUTER_API_KEY sk-or-v1-...

# 3. Point the web app at Convex and Clerk.
cd ../../apps/v2
cp .env.example .env.local  # then fill in the four required values

# 4. Run everything from the repo root.
cd ../..
bun run dev

Open localhost:3000 and say hi. The self-hosting guide covers each step in detail, including the Clerk JWT template Convex needs and how to deploy to production.

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

Documentation

Contributing

Bug reports, ideas, and pull requests are all welcome. Start with CONTRIBUTING.md, and please follow the code of conduct. Found a security issue? See SECURITY.md.

License

MIT © Anterra

whirl (whirlchat/whirl)

Searching Database…

510 ·GitHub
Whirl
Что это?Whirl — фулстек чат-приложение с ИИ на Next.js и Convex. Это опенсорсный код, стоящий за whirl.chat: разговоры маршрутизируются через OpenRouter к топовым моделям, плюс память, живые документы и интеграции с инструментами.
Это просто код whirl.chat или могу запустить свою копию?Это полный исходный код whirl.chat, опубликованный под MIT, так что вы можете изучать его, поднять собственный инстанс или вносить вклад обратно.
Как его запустить и какие аккаунты нужны сначала?Нужны Bun, бесплатный аккаунт Convex, приложение Clerk и ключ API OpenRouter; после их настройки откройте localhost:3000. Руководство по self-hosting описывает JWT-шаблон Clerk, который нужен Convex, и деплой в продакшен.
Что будет, если пропустить необязательные интеграции вроде биллинга или веб-поиска?Всё сверх Convex, Clerk и OpenRouter (биллинг через Autumn, веб-поиск через Exa, память через Supermemory, аналитика, трейсинг, email, агент поддержки) необязательно и настраивается отдельными ключами; если ключ не задан, Whirl просто скрывает функцию, которую он включает.
Можно ли пользоваться с телефона?Да, Whirl можно установить как мобильное веб-приложение (PWA) помимо работы в браузере на десктопе.
Что происходит с данными в заблокированных чатах?Заблокированные чаты шифруются на вашем устройстве паролем, который сервер никогда не видит, а отвечают в них только ИИ-модели с нулевым хранением данных.
Что такое живой документ в Whirl?Живые артефакты — это документы, графики и полноценные интерактивные страницы, которые остаются редактируемыми в боковой панели и делятся ссылкой, вместо статичных ответов в чате.
Как Whirl подключается к моим инструментам?Через MCP-интеграции с поддержкой OAuth, плюс устанавливаемые навыки, которые обучают Whirl новым способностям сверх базового чата.
Помнит ли Whirl что-то между разговорами?Да, у него есть долговременная память, которая переносит ваши предпочтения и проекты между чатами, опционально с опорой на сервис Supermemory.
С какими ИИ-моделями можно общаться?Все топовые модели доступны в одном разговоре через маршрутизацию OpenRouter, с настраиваемым уровнем размышлений для каждой модели.
What are similar projects?open-glean, LibreChat, onyx, boardui, searchmirror, crm, os, jevbox
Which topics is it in?ai-chat, mobile-web, billing, web-search, voice, openrouter, pwa, bun, chat, analytics, agent-memory, tailwindcss
Creator
whirlchat
Size
5.1 MB
Stars
510
Updated
CommitOct 14
Age
16d
Commits · 90 Days