@camunda/copilot-chat

React component library for embedding Camunda Copilot chat interface into web applications.

Installation

npm install @camunda/copilot-chat

Peer Dependencies:

npm install react react-dom

Styling

The library ships precompiled CSS (including its own Tailwind v4 utilities, scoped under .copilot-chat-root so they cannot leak into the host document):

import '@camunda/copilot-chat/style.css';

Components are built on @camunda/design-system (a runtime dependency, kept external to the bundle). Consumers must import the design-system stylesheet themselves:

import '@camunda/design-system/styles.css';

Quick Start

import {
  CopilotConversationPanel,
  createFixtureClient,
} from '@camunda/copilot-chat';
import '@camunda/copilot-chat/style.css';
import { useState } from 'react';

const client = createFixtureClient();

function App() {
  const [conversationId, setConversationId] = useState<string | null>(null);

  return (
    <CopilotConversationPanel
      client={client}
      conversationId={conversationId}
      onConversationStarted={setConversationId}
      onSelectConversation={setConversationId}
    />
  );
}

Pass onClose when the panel is used in a sidecar. It adds a close button to the header in both the chat list and an open chat; the host callback should close the sidecar and return focus to its opener.

Conversation context

Pass projectName for the selected conversation's project to show its name in the header. The project chip explains Copilot's project access; pass onOpenProject(projectId) to show a "Go to project" action in its popup. If the project name cannot be loaded, pass projectNameUnavailable rather than displaying a project ID as its name. The host must still provide editor context in postMessage; these props only describe the project.

Selection context

Pass selectionContext={{ projectId, count }} to CopilotConversationPanel when a BPMN editor has selected elements. A positive count appears as a read-only "1 element selected" or "N elements selected" pill in the composer's prompt-input toolbar; omit the prop or pass count: 0 to hide it. For a pinned conversation, the indicator appears only when the loaded conversation's origin artifact belongs to projectId. It remains hidden while that origin is loading or belongs to a different project. The host is responsible for supplying the selected elements as context when the message is sent.

Reviewing proposed changes

CopilotConversationPanel accepts a renderReview(candidate, { approve, reject }) callback for host-owned review flows. When provided, its return value replaces the inline approve/reject controls for pending candidates. Hosts should present the candidate's changes (including their before and content snapshots) before calling approve; the exported CandidateReview renders BPMN diagrams and text diffs. Both actions return promises, so the host can display progress and keep the review open if an action fails. While a proposal awaits approval or rejection, the composer is disabled for that conversation. Other conversations remain available. The backend also rejects new turns until the proposal is resolved.

While a turn is running, the message input and suggestions are disabled and no additional message can be submitted. Stop remains available; sending resumes after the turn finishes or is stopped, provided no proposal awaits review. Rejected submissions show an inline error and preserve the draft for retry. Messages are not queued or automatically used to interrupt a running turn.

Applied changes offer a Restore action. It opens a confirmation dialog naming the affected files before restoring their earlier state. Cancel or Escape leaves them unchanged; restoring preserves chat history. Failed restores remain in the dialog with an error and can be retried.

Async CopilotClient adapters should call the optional third observe argument after each connection or reconnection. The panel refreshes its snapshot at that point to recover events missed while connecting. The HTTP adapter does this on SSE open; two-argument synchronous adapters remain supported.

CandidateReview.onReviewReady reports true only when every artifact is ready. Fixture scripts must supply before for modifications to support restore; otherwise approval has no checkpoint. Only created files restore to absence.

Conversation steps

Assistant messages can include message steps for intermediate agent progress. Their description holds the message text. Intermediate messages remain visible alongside tool steps in event order, including after completion or interruption. If the turn ends with a message, only that last message is removed from the steps and becomes the assistant reply in content. Optional groupId metadata in older snapshots does not nest rows. Message rows show text directly beside a neutral dot, without a generic "Progress" label.

Shell-tool lint steps, including combined layout/lint steps, use a neutral wrench and their original activity label even when the check returns an error. They do not show red failure styling, a "(failed)" suffix, or a warning badge. The stored step status remains error; lint findings stay in the assistant's explanation. Other failed operations retain their failure presentation. This presentation rule applies both to live steps and to reopened conversation history.

Documentation

• Repository README
• Development Guide

License

Camunda License 1.0 - See LICENSE file for details.