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…

509 ·GitHub
这是什么?Whirl 是一个基于 Next.js 和 Convex 构建的全栈 AI 聊天应用。它是 whirl.chat 背后的开源代码,通过 OpenRouter 把对话路由到顶级模型,同时提供记忆、活文档和工具集成。
这只是 whirl.chat 的代码,还是我可以运行自己的副本?它是 whirl.chat 背后的完整源码,以 MIT 许可发布,你可以阅读它、自托管自己的实例,或者回馈贡献。
怎么让它跑起来?我需要先准备哪些账号?你需要 Bun、一个免费的 Convex 账号、一个 Clerk 应用和一个 OpenRouter API 密钥;配置好之后打开 localhost:3000。自托管指南介绍了 Convex 所需的 Clerk JWT 模板和生产环境部署。
如果我跳过账单或网页搜索这类可选集成,会怎么样?Convex、Clerk 和 OpenRouter 之外的一切(通过 Autumn 计费、通过 Exa 网页搜索、通过 Supermemory 记忆,以及分析、追踪、邮件、支持智能体)都是可选的,并且各自使用单独的密钥;如果缺少某个密钥,Whirl 只会隐藏它所支持的对应功能。
我能在手机上使用它吗?可以,除了在桌面浏览器中运行,Whirl 还可以作为移动网页应用(PWA)安装。
锁定聊天中的数据会怎样处理?锁定聊天在你的设备上用服务器永远看不到的密码进行加密,并且只由零保留的 AI 模型来回答。
Whirl 中的活文档是什么?活文档是可以在侧边面板中持续编辑、并能通过链接分享的文档、图表和完整的交互式页面,而不是静态的聊天回复。
Whirl 怎么连接我自己的工具?通过支持 OAuth 的 MCP 集成,以及可安装的技能——后者能教会 Whirl 基础聊天之外的新能力。
Whirl 能跨对话记住东西吗?能,它具有长期记忆,可以在聊天之间保留你的偏好和项目,还可以选择由 Supermemory 服务提供支持。
我可以和哪些 AI 模型对话?所有顶级模型都可以在同一场对话中使用,通过 OpenRouter 路由,每个模型的思考等级都可以调节。
What are similar projects?open-glean, LibreChat, onyx, boardui, searchmirror, crm, os, jevbox
Creator
whirlchat
Size
5.1 MB
Stars
509
Updated
CommitOct 14
Age
16d
Commits · 90 Days