# How `chat_create` Initializes a New Chat Session and Its Metadata in Coco App

> Learn how Coco App's chat_create function initializes new chat sessions and metadata. Explore Tauri and web environment setup in this technical deep dive.

- Repository: [INFINI Labs/coco-app](https://github.com/infinilabs/coco-app)
- Tags: internals
- Published: 2026-03-04

---

**When a user submits a message in Coco App, the `createNewChat` function in [`src/hooks/useChatActions.ts`](https://github.com/infinilabs/coco-app/blob/main/src/hooks/useChatActions.ts) orchestrates session initialization by clearing UI state, generating unique timestamps, assembling query parameters, and invoking the `chat_create` command with structured metadata for both Tauri desktop and web environments.**

The Coco App chat system, maintained in the `infinilabs/coco-app` repository, uses a unified hook-based architecture to bootstrap conversational sessions. Understanding how `chat_create` initializes these sessions requires examining the client-side preparation logic that runs before any network request reaches the backend.

## The Session Initialization Flow

The initialization process begins when the UI invokes **`createNewChat`**, a React hook function that coordinates five distinct phases of session preparation before transmitting data to the server.

### Preparing the Session with `prepareChatSession`

Before constructing the network payload, `createNewChat` calls **`prepareChatSession`** (lines 281‑302 in [`src/hooks/useChatActions.ts`](https://github.com/infinilabs/coco-app/blob/main/src/hooks/useChatActions.ts)) to establish a clean execution environment. This utility performs critical housekeeping:

- Clears any pending streaming chunks via `clearAllChunkData()` to prevent message bleeding between sessions
- Resets the attachment list and UI input state
- Hides the start page and clears timeout flags
- Registers event listeners that will handle the streaming response once the session is established

This preparation ensures that each chat session starts from a deterministic state, regardless of previous interactions.

### Generating Unique Identifiers

To prevent stream collisions and enable precise session tracking, the hook generates a millisecond-precision timestamp:

```typescript
const timestamp = Date.now();

```

This timestamp (lines 50‑51) combines with a client identifier to form a unique stream ID formatted as `chat-stream-${clientId}-${timestamp}`. The composite ID travels with every request, allowing the backend to route streaming responses to the correct UI session even when multiple chats run concurrently.

### Assembling Query Parameters and Metadata

The core metadata assembly occurs in [`src/hooks/useChatActions.ts`](https://github.com/infinilabs/coco-app/blob/main/src/hooks/useChatActions.ts) (lines 54‑61), where the hook constructs a **`queryParams`** object reflecting the current UI configuration:

```typescript
const queryParams = {
  search: isSearchActive,
  deep_thinking: isDeepThinkActive,
  mcp: isMCPActive,
  datasource: sourceDataIds?.join(",") || "",
  mcp_servers: MCPIds?.join(",") || "",
  assistant_id: currentAssistant?._id || "",
};

```

Each field serves a specific function:
- **`search`**, **`deep_thinking`**, and **`mcp`** are boolean flags indicating active feature toggles
- **`datasource`** contains comma-separated IDs for external data sources the assistant should query
- **`mcp_servers`** lists active MCP (Model Context Protocol) server identifiers
- **`assistant_id`** targets a specific AI assistant when the user has multiple assistants configured

This metadata object travels with every `chat_create` invocation, ensuring the backend receives complete context about how to process the incoming message.

## Backend Invocation: Desktop vs Web

Coco App supports two runtime environments—Tauri desktop and standard web browsers—each with distinct transport mechanisms for the `chat_create` command.

### Tauri Desktop Path

When running as a desktop application, the hook invokes the backend through the Tauri bridge (lines 66‑74):

```typescript
await platformAdapter.commands("chat_create", {
  serverId,
  message: userMessage,
  attachments,
  queryParams,
  clientId: `chat-stream-${clientId}-${timestamp}`,
});

```

The payload includes:
- **`serverId`**: The active server selected in the UI dropdown
- **`message`**: The sanitized user prompt
- **`attachments`**: An array of uploaded file references
- **`queryParams`**: The metadata object assembled earlier
- **`clientId`**: The unique stream identifier combining client ID and timestamp

According to the source code in [`src/commands/servers.ts`](https://github.com/infinilabs/coco-app/blob/main/src/commands/servers.ts), this command ultimately forwards the payload to the Coco AI backend, which initializes the session and begins streaming the response through Tauri's event system.

### Web Browser Path

For browser deployments, the hook bypasses Tauri and sends a streaming HTTP POST request to `/chat/_create` (lines 78‑82 in [`src/hooks/useChatActions.ts`](https://github.com/infinilabs/coco-app/blob/main/src/hooks/useChatActions.ts)):

```typescript
await streamPost({
  url: `${apiOrigin}/chat/_create`,
  data: payload,
  headers,
});

```

The payload structure mirrors the desktop version, ensuring consistent metadata handling across platforms. The `streamPost` utility (implemented in [`src/api/streamFetch.ts`](https://github.com/infinilabs/coco-app/blob/main/src/api/streamFetch.ts)) manages Server-Sent Events (SSE) to deliver real-time tokens to the UI.

## Post-Creation State Management

After the backend acknowledges session creation, `createNewChat` performs cleanup operations (lines 76‑94):

- Calls **`resetChatState()`** to clear temporary UI flags and input buffers
- Conditionally refreshes the chat history pane by invoking `getChatHistory()` or its paginated variant, ensuring the new session appears in the sidebar immediately

The event listeners registered during `prepareChatSession` (via [`src/hooks/useWindows.ts`](https://github.com/infinilabs/coco-app/blob/main/src/hooks/useWindows.ts)) then capture the `chat-create` and `chat-create-error` events, routing the streaming content into the conversation view.

## Summary

- **Session preparation**: `prepareChatSession` in [`src/hooks/useChatActions.ts`](https://github.com/infinilabs/coco-app/blob/main/src/hooks/useChatActions.ts) clears previous state and registers streaming listeners before any network call occurs
- **Unique identification**: Each session receives a millisecond timestamp combined into a `chat-stream-${clientId}-${timestamp}` identifier to prevent collisions
- **Metadata assembly**: The `queryParams` object encapsulates UI toggles (`search`, `deep_thinking`, `mcp`), data source IDs, and the target `assistant_id` for backend routing
- **Dual transport**: Desktop builds use `platformAdapter.commands("chat_create", ...)` while web builds POST to `/chat/_create`, both carrying identical payload structures
- **State synchronization**: Post-creation hooks reset the chat state and refresh history views to maintain UI consistency

## Frequently Asked Questions

### What is the purpose of the `timestamp` variable in `createNewChat`?

The timestamp generated via `Date.now()` (lines 50‑51) creates a unique temporal identifier for each chat stream. When combined with the client ID into the format `chat-stream-${clientId}-${timestamp}`, it enables the backend to route streaming responses to the correct session and prevents race conditions when multiple chats initialize simultaneously.

### How does Coco App handle different assistant configurations during session creation?

The `queryParams` object includes an **`assistant_id`** field populated from `currentAssistant?._id` (lines 54‑61). When the user selects a specific assistant from the UI, this ID transmits to the backend via the `chat_create` payload, ensuring the server instantiates the correct model and context configuration for that particular assistant.

### Where does the actual `chat_create` command execution happen in the codebase?

While [`src/hooks/useChatActions.ts`](https://github.com/infinilabs/coco-app/blob/main/src/hooks/useChatActions.ts) contains the client-side orchestration logic that calls `platformAdapter.commands("chat_create", ...)`, the low-level command implementation resides in [`src/commands/servers.ts`](https://github.com/infinilabs/coco-app/blob/main/src/commands/servers.ts). This file handles the bridge between the TypeScript frontend and the Rust-based Tauri backend, ultimately forwarding the request to the Coco AI server.

### What happens if a user attaches files during session initialization?

The `createNewChat` function accepts an **`attachments`** array parameter that travels within the `chat_create` payload alongside the message and metadata. These attachments pass through the same transport layer (Tauri commands or HTTP POST) and are processed by the backend before the assistant begins generating its response.