OpenMuse uses @copilotkit/react-native/headless for its custom native and web interface. Chat messages, tool cards and task-linked documents render through CopilotKit's AG-UI agent and tool hooks.
Every workspace mode requires a CopilotKit Intelligence project key before the API will start. Create or select a project:
npx copilotkit@latest login
npx copilotkit@latest project selectKeep the generated key in the API server environment and restart the API:
CPK_INTELLIGENCE_API_KEY=your-project-keyNever put the key in an EXPO_PUBLIC_, NEXT_PUBLIC_, or VITE_ variable. The server constructs CopilotKitIntelligence, and identifyUser resolves the owner from the verified OpenMuse session. The existing deployment is a single-user workspace; its access key must not be shared as a multi-user login. See CopilotKit's runtime setup for project-key configuration.
With this configuration, the conversation menu uses CopilotKit's native useThreads hook to list, rename, archive, restore and paginate conversations. The server saves an owner-bound main thread ID and provisions it through Intelligence before the first message, so reloading during the first run retains the same conversation. Side chats create a fresh client thread ID and persist on their first run. Selecting a saved conversation mounts a private useAgent({ agentId, runtimeAgentId, threadId }) instance and calls copilotkit.connectAgent to replay the thread. Visited chats remain mounted during navigation, preserving their drafts and queues. Stop explicitly requests copilotkit.stopAgent.
The composer stays editable during replies. Follow-ups enter a visible, removable queue and run in order after the current reply and its persistence finish. Stopping or failing a reply pauses the queue; SDK errors emitted without rejecting the run promise still stop subsequent sends. The queue lives in the open app, not a durable server inbox. Delegated tasks remain separate server work. See the interaction design.
Rich tool messages retain task IDs. The renderer fetches current task status, browser previews, PDF links and structured artifacts from the authenticated task endpoint. Expiring file/preview URLs are generated by the server rather than stored in thread messages. New Intelligence conversations never load or overwrite /api/conversation.
The API fails at startup with a missing-key error when the key is unset. Existing local sample history is not automatically uploaded to Intelligence.
Automatic thread naming is disabled; conversations can be renamed in the menu. Intelligence is a separately configured service, not bundled with this MIT-licensed application. See headless threads for the platform lifecycle and hosting options.
The Computer control below the avatar opens a persistent workspace with browser sessions and files. Browser cards show actual worker screenshots; Open browser opens the existing interactive console for takeover. PDFs open in the native/web readers. Tasks can read public pages, monitor changes and collect PDFs using the same worker.
Opening a session renews its short-lived console access. Refresh connection renews access without navigating; Reopen keeps the saved profile and uses the address in the input. The console reports live/disconnected state, preserves unsent text after an error, and pauses preview polling when hidden. Closing a session retains its profile and downloads.
Run the browser worker using the BROWSER_WORKER_URL and WORKER_TOKEN setup in the README. Browser profiles persist on disk. The optional Linux computer adds real command execution, saved output, editable files, and PDF transfer. CopilotKit's built-in conversation and task-worker tools use this same computer; remote AG-UI backends must supply their own equivalent tools. Interactive reservations still require user takeover; autonomous booking, checkout, graphical desktops and per-user VM isolation are not implemented. The OpenBot adapter remains an extension point for other computer backends.
The Rich Threads route tests run against the real CopilotKit runtime with a mocked Intelligence service boundary. They cover session enforcement, owner scoping, pagination, rename, archive, rich message preservation and provider failures. They do not replace a live account test for Intelligence WebSocket persistence/replay. That test requires a configured project key.