ChatJS Documentation

ChatJS provides a wide range of tools to extend AI capabilities. Key features include:

• Web Search: Real-time search using Tavily or Firecrawl to ground responses in current information.
• Deep Research: A multi-step research agent for investigating topics and producing reports.
• Code Execution: Secure sandboxed execution of Python and JavaScript code snippets.
• Image Generation: Generation and iterative editing of images using dedicated models or multimodal LLMs.
• MCP: Support for the Model Context Protocol to extend capabilities with external tools.
• Canvas: AI-assisted creation and editing of text documents, code, and spreadsheets.
• Reasoning: Extended thinking for complex queries with collapsible chain-of-thought UI.
• Attachments: Multimodal support via drag-and-drop for images, PDFs, and documents.
• Sharing: Public link sharing with per-chat visibility controls.
• Branching: Conversation forking and sibling navigation to explore alternative paths.
• Parallel Responses: Side-by-side comparison of answers from multiple models sent simultaneously.
• Follow-up Suggestions: Contextual, clickable AI-generated questions to continue conversations.
• Projects: Workspace organization with custom instructions, icons, and colors.

ChatJS is organized into a Next.js App Router architecture with a clear separation between the UI layer, AI integration logic, and the data layer.

Core Directories

• app/: Contains the Next.js App Router, including authentication routes (auth), the main chat interface (chat), and API routes.
• components/: The UI layer, subdivided into ui/ (base shadcn/ui), chat/ (chat-specific UI), ai-elements/ (registry components), and part/ (tool result renderers).
• lib/: The core logic layer containing ai/ (SDK integration and gateways), db/ (Drizzle ORM schema and queries), models/, and stores/ (Zustand state).
• trpc/: Contains tRPC routers and procedures for type-safe API communication.
• hooks/ & providers/: React hooks and context providers.

├── app/                    # Next.js App Router
│   ├── (auth)/            # Auth routes (login, register)
│   ├── (chat)/            # Main chat interface
│   ├── api/               # API routes (chat, auth, trpc)
│   └── actions/           # Server Actions
├── components/
│   ├── ai-elements/       # AI Elements registry components
│   ├── chat/              # Chat UI components
│   ├── part/              # Tool part renderers
│   ├── settings/          # Settings pages
│   └── ui/                # shadcn/ui components
├── lib/
│   ├── ai/                # AI SDK integration, tools, prompts
│   │   └── gateways/      # Gateway abstraction (Vercel, OpenRouter)
│   ├── db/                # Database schema, queries, and data access
│   ├── models/            # Model types and utilities
│   └── stores/            # Zustand stores
├── trpc/                   # tRPC routers and procedures
├── hooks/                  # React hooks
├── providers/              # React context providers
└── evals/                  # AI evaluation tests

In ChatJS, the Runtime is the primary unit of execution. Instead of chat logic being tied to a specific URL route, a runtime is a persistent entity that manages the lifecycle of a chat independently of the UI view. This allows for features like background streaming, concurrent chats, and optimistic (provisional) UI rendering.

A runtime tracks several key properties:

• chatId: The unique identifier for the chat.
• runtimeId: The unique identifier for the runtime instance.
• projectId: The associated project.
• store: The local state instance owned by the runtime.
• persistenceStatus: Either provisional (optimistic/draft) or confirmed (persisted in DB).
• streamStatus: The current state of the AI stream (idle, submitted, streaming, complete, error, or stopped).
• pendingSubmission and submittedMessage: Data related to the current message being processed.

Every assistant response lifecycle is represented by a RunRecord.

Key Concepts

• Run vs. Message ID: Run IDs and response message IDs are separate. A RunRecord exists as soon as a request is submitted, even before an assistant message is created. The message ID is only bound once the AI SDK publishes the response.
• Concurrency: You can start multiple runs from the same user message to create assistant siblings, or start runs from different leaves to update branches concurrently. Each run has its own independent status, error, and cancellation controls.
• Run Invariant: A new live run requires a non-assistant response parent. You cannot call startRun directly from an assistant message. To branch from an assistant, you must use sendMessage to attach a new user message to that assistant node, which then triggers a new response.

Run Record Structure

A RunRecord contains:

• aborted: Boolean indicating if the run was cancelled.
• chat: The ThreadRunChat instance for that specific run.
• error: Any error encountered during the run.
• finished: A Promise that resolves when the run completes.
• spec: The ThreadRunSpec used.
• status: The current ChatStatus of the run.