om-scogo CopilotKit React Core
@copilotkit/react-core is the React frontend half of CopilotKit: it mounts a provider,
speaks AG-UI over SSE to a runtime (or directly to CopilotKit Intelligence in SPA mode), and
exposes hooks for every interaction surface.
This SKILL.md is the index. Read the reference under references/ that matches
your task — do not try to absorb the whole package from this file.
Mental model — three shells you compose
- Provider shell — the
CopilotKitprovider (from@copilotkit/react-core/v2) at or near the root (inside"use client"for Next.js App Router). CarriesruntimeUrl(orpublicLicenseKeyfor SPA),headers,credentials,properties,onError,debug,showDevConsole. - Chat shell —
CopilotChat/CopilotPopup/CopilotSidebaror a composedCopilotChatView+ slot primitives (CopilotChatInput,CopilotChatMessageView, etc.). All chat components ship from@copilotkit/react-core/v2.CopilotPaneldoes not exist — it's a common hallucination. - Hook shell — inside any component under the provider, call
useAgent,useFrontendTool,useRenderTool, etc. Every hook takes optional{ agentId }for agent-scoped registration.
When to load which reference
| Task | Reference |
|---|---|
Mount the CopilotKit provider, pick runtimeUrl vs publicLicenseKey, RSC boundary rules |
references/provider-setup.md |
Drop in CopilotChat / CopilotPopup / CopilotSidebar, compose CopilotChatView with slot primitives |
references/chat-components.md |
File / image attachments via useAttachments — drag-drop, click, paste, custom upload |
references/attachments.md |
Client-side debug tooling — showDevConsole, debug prop, lazy-loaded web inspector |
references/debug-mode.md |
Read / subscribe to an agent (useAgent) and push global context (useAgentContext) |
references/agent-access.md |
Feature-gate UI on declared agent capabilities (useCapabilities) |
references/capabilities.md |
Build a multi-agent UI (per-panel useAgent, agent-scoped tools, key-remount pattern) |
references/switching-agents.md (+ switching-agents-recipes.md for concrete layouts) |
List / rename / archive / delete durable Intelligence threads (useThreads) |
references/threads.md (requires runtime Intelligence mode) |
Register browser-side tools (useFrontendTool) |
references/client-side-tools.md |
Render per-tool UI (useRenderTool, useComponent, useDefaultRenderTool, useRenderToolCall) |
references/rendering-tool-calls.md |
Gate tool execution behind user approval (useHumanInTheLoop) |
references/human-in-the-loop.md |
Configure dynamic or static suggestion pills (useConfigureSuggestions, useSuggestions) |
references/suggestions.md |
Render non-chat activity messages (useRenderActivityMessage) |
references/rendering-activity-messages.md |
Inject custom UI before/after specific messages (useRenderCustomMessages) |
references/custom-message-renderers.md |
Invariants and gotchas (load-once, before any reference)
publicLicenseKeyis canonical.publicApiKeyis a deprecated alias — expect it in legacy code.agents__unsafe_dev_onlyandselfManagedAgentsare dev-only aliases of each other. Not production-safe. Seepackages/a2ui-rendereror thespa-without-runtimelifecycle skill for the supported SPA path.CopilotPaneldoes not exist. v2 chat components ship fromreact-core/v2— notreact-ui(v2react-uiis CSS-only).- No
useAgents()hook exists. Discover agents viacopilotkit.subscribe({ onAgentsChanged }). useRenderToolCallis a resolver (for custom chat surfaces), not a registration hook. Register withuseRenderTool/useComponent/useDefaultRenderTool.- UI-kit detection rule — any
renderor tool-call UI MUST reuse the consumer's shadcn / MUI / Chakra / Ant / Mantine primitives before writing raw JSX. This applies acrossclient-side-tools,rendering-tool-calls, andhuman-in-the-loop. - Tool-call
statusvalues are camelCase:'inProgress' | 'executing' | 'complete'. In-progress args arePartial<T>. useHumanInTheLoopsynthesized handler MUST callrespond(result)(including reject paths), otherwise the agent run hangs.respondisundefinedoutsideExecutingstatus. Unmounting mid-Executing abandons the run.useThreadserrors with'Runtime URL is not configured'outside Intelligence mode.v1 → v2migration renames:useCopilotAction→useFrontendTool+useHumanInTheLoop;imageUploadsEnabled→attachments. See thev1-to-v2-migrationlifecycle skill.
Reading order for a first-time reader
provider-setup— mount the provider.chat-components— wire a chat surface.agent-access— talk to agents.client-side-tools+rendering-tool-calls— add tool-call UI.- Anything else as your feature requires.