CLI

Create a new ChatJS app:

npx @chat-js/cli@latest create my-app

The CLI walks you through gateway, features, and auth choices, generates chat.config.ts, and lists the env vars required by your selections.

Features

• 120+ Models: Claude, GPT, Gemini, Grok via one API
• Auth: GitHub, Google, anonymous. Ready to go.
• Attachments: Images, PDFs, docs. Drag and drop.
• Native EVE Runtime: Durable conversations, approvals, and recovery
• Branching: Fork conversations, explore alternatives
• Sharing: Share conversations with public links
• Web Search: Real-time web search integration
• Image Generation: AI-powered image creation
• Code Execution: Run code snippets in sandbox
• MCP: Model Context Protocol support
• Desktop App: Package as a native macOS, Windows, or Linux app with Electron

Stack

• Next.js - App Router, React Server Components
• TypeScript - Full type safety
• AI SDK - The AI Toolkit for TypeScript
• AI Gateway - Unified access to 120+ AI models
• Better Auth - Authentication & authorization
• Drizzle ORM - Type-safe database queries
• PostgreSQL - Primary database
• EVE - Durable conversation runtime
• Vercel Blob - Blob storage
• Shadcn/UI - Beautiful, accessible components
• Tailwind CSS - Styling
• tRPC - End-to-end type-safe APIs
• Zod - Schema validation
• Motion - Animations
• t3-env - Environment variables
• Pino - Structured Logging
• Langfuse - LLM observability & analytics
• Vercel Analytics - Web analytics
• Oxlint and Oxfmt - Code linting and formatting
• Ultracite - Oxlint and Oxfmt presets for humans and AI
• Streamdown - Markdown for AI streaming
• AI Elements - AI-native Components
• AI SDK Tools - Developer tools for AI SDK

Monorepo Layout

• apps/site: Landing page (chatjs.dev)
• apps/chat: Next.js chat app (demo.chatjs.dev)
• apps/docs: Blume docs (chatjs.dev/docs)
• packages/cli: interactive scaffold CLI

Development

• bun dev: run chat app with debugging overlays disabled
• bun dev:query: run chat with React Query Devtools
• bun dev:scan: run chat with React Scan
• bun dev:debug: run chat with both tools
• bun dev:info: print this worktree's assigned app URLs
• bun dev:docs: run docs
• bun lint: check repository-wide Oxlint rules and Oxfmt formatting, plus docs health
• bun format: format the repository with Oxfmt
• bun lint:fix: apply safe Oxlint fixes
• bun test:types: type-check the workspaces

Ultracite supplies the Oxlint and Oxfmt presets. All files receive the full presets. Necessary exceptions are documented at the affected source lines rather than disabled through file-wide baselines. Oxfmt skips build output and the five generated registration indexes whose exact content hashes are verified by chat-js sync.

Stop the dev server before switching debug commands, then reload the page. Both integrations remain available without reinstalling anything; React Scan loads from its existing CDN script. These flags only enable tools in development.

Set CHATJS_DEV_SLOT in .env.worktree.local to reserve a stable range of ten ports per worktree. Within each range, chat uses offset 0, Electron uses 1, and the site uses 2, as configured in .worktree-env.json. The local file is ignored by Git and kept separate from Vercel-managed .env.local. Run bun dev:info instead of assuming a port.

Native Eve runtime

EVE is the sole ChatJS conversation runtime. It owns the durable transcript, execution state, approvals, checkpoints, and stream recovery. ChatJS owns authenticated access, conversation metadata, projects, sharing, files, documents, and billing evidence around that runtime. Historical ChatJS conversations are not imported.

Local EVE development requires Node 24+, Bun, ChatJS and Workflow World Postgres configuration, and the EVE gateway secret specified by the app environment schema. Use isolated local databases while developing or validating lifecycle changes.

The EVE-only runtime does not itself establish production readiness. Provider deletion coverage and guest-hosting readiness remain release gates. See the migration report for the current boundary and historical validation evidence.

Releases

Releases are driven by Changesets for the whole repository.

• Add a changeset for each releasable package you change.
• Merge the generated version PR from the Changesets workflow.
• Public packages such as @chat-js/cli publish to npm.
• Desktop installers for @chat-js/electron publish to GitHub Releases.

License

Apache-2.0

Local EVE runtime

bun dev starts the local application with its EVE runtime. Keep its configured databases isolated from shared environments.

For unattended local development on macOS:

bun dev:service start   # launchd supervision for this checkout; also starts at login
bun dev:health         # bounded ChatJS + Eve + database readiness check
bun dev:service status # process state and log location
bun dev:service stop   # stop this checkout and remove its login startup entry

Stop a manually running bun dev before starting the service. Each checkout has its own service identity and worktree port. The supervisor checks readiness every ten seconds. Startup gets three minutes initially, then six and at most ten minutes after consecutive unsuccessful launches, so slow compilation can finish. Eve's development startup timeout is also ten minutes. Once healthy, the runtime must remain unavailable for two minutes across at least three failed checks before it is replaced. A successful readiness check resets the startup allowance; process exits still trigger recovery immediately. Restarts back off to sixty seconds. Node heaps are capped at 4 GiB per process; this is not a total system memory cap. Logs are retained under ~/Library/Logs/ChatJS/ (the status command prints the checkout's directory). The Mac must be awake and the database/network available; supervision cannot make a sleeping laptop serve traffic. bun dev:service stop leaves other checkouts alone.