MCPInstall

copilotkit-debug

by copilotkitCode Quality & Workflow

Use when diagnosing CopilotKit issues -- runtime connectivity failures, agent not responding, streaming errors, tool execution problems, transcription failures, version mismatches, and AG-UI event tracing.

Installs
2.8K
Last 24h
—
Trending rank
—
Security
Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/copilotkit/copilotkit --skill copilotkit-debug
  1. 01

    Install

    Run the command in your project. The CLI asks which agents to install for.

  2. 02

    Describe the task

    Ask your agent for something this skill covers. It loads copilotkit-debug automatically when relevant.

  3. 03

    Review the result

    The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

CopilotKit Debugging Skill

When to Use

Invoke this skill when:

  • The CopilotKit runtime is unreachable or returning errors
  • Agents fail to connect, respond, or stream events
  • Frontend tools are not executing or returning results
  • Transcription (voice) is failing
  • Version mismatch errors appear between packages
  • AG-UI SSE events are malformed or missing
  • CORS errors block browser requests to the runtime

Diagnostic Workflow

Step 1: Gather Information

Before proposing any fix, collect:

  1. Package versions -- Run npm ls @copilotkit/runtime @copilotkit/react-core @copilotkit/core @ag-ui/client (or the v1 equivalents). Version mismatches between runtime and React packages are a common root cause.
  2. Runtime mode -- Is this SSE mode (CopilotSseRuntime) or Intelligence mode (CopilotIntelligenceRuntime)? Check the runtime constructor.
  3. Transport configuration -- What is runtimeUrl set to on the CopilotKit provider (from @copilotkit/react-core/v2)? Does it match the basePath in createCopilotRuntimeHandler?
  4. Agent type -- Is the agent a BuiltInAgent, LangGraphAgent, A2AAgent, or custom AbstractAgent?
  5. Error messages -- Collect the exact error from browser console and server logs. CopilotKit uses structured error codes (see references/error-patterns.md).
  6. Browser network tab -- Check the /info request (runtime discovery), the /agent/:id/run SSE stream, and any CORS preflight failures.

Step 2: Check Logs and Error Codes

CopilotKit has three error code systems:

  • V1 error codes -- Legacy error codes from the v1 runtime layer (@copilotkit/runtime). Codes like NETWORK_ERROR, AGENT_NOT_FOUND, API_NOT_FOUND. Still surfaced in some contexts since @copilotkit/* packages wrap v2 internally.
  • V2 CopilotKitCoreErrorCode -- Used by @copilotkit/core. Codes like runtime_info_fetch_failed, agent_connect_failed, agent_run_failed.
  • TranscriptionErrorCode -- Used by both v1 and v2 for voice transcription. Codes like service_not_configured, rate_limited, auth_failed.

Match the error code to the catalog in references/error-patterns.md for root cause and resolution.

Step 3: Trace AG-UI Events

For streaming/agent issues, trace the AG-UI event flow:

  1. RunStartedEvent -- Confirms the agent run was initiated
  2. TextMessageStartEvent / TextMessageChunkEvent / TextMessageEndEvent -- Text streaming
  3. ToolCallStartEvent / ToolCallArgsEvent / ToolCallEndEvent -- Tool invocations
  4. ToolCallResultEvent -- Tool results flowing back
  5. StateSnapshotEvent / StateDeltaEvent -- Agent state synchronization
  6. ReasoningStartEvent / ReasoningMessageContentEvent / ReasoningMessageEndEvent -- Reasoning tokens (can cause stalls, see issue #3323)
  7. RunFinishedEvent -- Successful completion
  8. RunErrorEvent -- Agent-level error

Enable the CopilotKit Web Inspector (@copilotkit/web-inspector) to see events in real time. Or check the SSE stream directly in the browser Network tab -- each event is a data: line in the text/event-stream response.

Step 4: Identify Root Cause

Use the reference documents to match symptoms to known issues:

  • references/runtime-debugging.md -- Connectivity, CORS, transport, SSE streaming
  • references/agent-debugging.md -- Agent discovery, state sync, tool execution, AG-UI protocol
  • references/error-patterns.md -- Complete error code catalog with resolutions
  • references/quick-workflows.md -- Step-by-step diagnostic sequences for common scenarios

Step 5: Fix and Verify

  1. Apply the fix
  2. Verify the /info endpoint returns the expected agent list
  3. Confirm the SSE stream produces a complete event sequence (RunStarted through RunFinished)
  4. Check the browser console for any remaining structured errors

Using mcp-docs for Live Documentation Lookups

During debugging, use the copilotkit-docs MCP server to look up the latest CopilotKit documentation. This server provides two tools: search-docs (search documentation) and search-code (search source code examples).

MCP Setup

Claude Code: The MCP server is auto-configured by the plugin's .mcp.json -- no manual setup needed. The agent can call the search-docs and search-code tools from the copilotkit-docs server directly.

Codex: Add the following to your .codex/config.toml:

[mcp_servers.copilotkit-docs]
type = "http"
url = "https://mcp.copilotkit.ai/mcp"

Tool Usage

The search-docs and search-code tools are invoked as MCP tool calls (not CLI commands). Examples of what to search for during debugging:

search-docs("AGENT_NOT_FOUND")
search-docs("CopilotRuntime configuration")
search-docs("AG-UI protocol events")
search-docs("troubleshooting common issues")
search-docs("CORS configuration copilotkit")
search-code("CopilotRuntime error handling")

The official troubleshooting docs are at:

  • https://docs.copilotkit.ai/troubleshooting/common-issues
  • https://docs.copilotkit.ai/coagents/troubleshooting/common-issues

Key File Locations in the CopilotKit Codebase

ComponentPath
Legacy error classes & codespackages/shared/src/utils/errors.ts
V2 Core error codespackages/core/src/core/core.ts (CopilotKitCoreErrorCode enum)
V2 Transcription errorspackages/shared/src/transcription-errors.ts
Runtime SSE responsepackages/runtime/src/v2/runtime/handlers/shared/sse-response.ts
Runtime info endpointpackages/runtime/src/v2/runtime/handlers/get-runtime-info.ts
Runtime CORS configpackages/runtime/src/v2/runtime/core/fetch-cors.ts
CopilotKit Intelligence clientpackages/runtime/src/v2/runtime/intelligence-platform/client.ts
BuiltInAgentpackages/runtime/src/agent/index.ts
Web Inspectorpackages/web-inspector/src/index.ts

FAQ

What does the copilotkit-debug skill do?

Use when diagnosing CopilotKit issues -- runtime connectivity failures, agent not responding, streaming errors, tool execution problems, transcription failures, version mismatches, and AG-UI event tracing.

How do I install copilotkit-debug?

Run npx skills add https://github.com/copilotkit/copilotkit --skill copilotkit-debug in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/copilotkit-debug/ (personal) or .claude/skills/copilotkit-debug/ (project).

Which AI agents can use copilotkit-debug?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is copilotkit-debug safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains copilotkit-debug?

It is published by copilotkit in copilotkit/copilotkit. It has 2,789 recorded installs.

More from copilotkit/copilotkit

View all →

copilotkit-develop

copilotkit/copilotkit

Use when building AI-powered features with CopilotKit v2 -- adding chat interfaces, registering frontend tools, sharing application context with agents, handling agent interrupts, and working with the CopilotKit runtime.

Frontend & Design2.8K installs

copilotkit-agui

copilotkit/copilotkit

Use when building custom agent backends, implementing the AG-UI protocol, debugging streaming issues, or understanding how agents communicate with frontends. Covers event types, SSE transport, AbstractAgent/HttpAgent patterns, state synchronization, tool calls, and human-in-the-loop flows.

Frontend & Design2.8K installs

react-core

copilotkit/copilotkit

@copilotkit/react-core — mount the CopilotKit provider (from @copilotkit/react-core/v2) in a Next.js App Router / React Router v7 / TanStack Start / SPA app, drop in CopilotChat/CopilotPopup/CopilotSidebar (v2 chat components ship from react-core/v2 — NOT react-ui, which is CSS-only in v2), access and subscribe to agents with useAgent / useAgentContext / useCapabilities, switch between multiple agents, manage durable Intelligence threads with useThreads, register browser-side tools via useFrontendTool, render tool calls with useRenderTool / useComponent / useDefaultRenderTool, gate execution with useHumanInTheLoop, wire file attachments with useAttachments, configure suggestion pills, and register activity- and custom-message renderers. Load the reference under references/ that matches your task.

Frontend & Design2.8K installs

runtime

copilotkit/copilotkit

@copilotkit/runtime — mount a fetch-native CopilotRuntime on any JS server, wire middleware, pick an AgentRunner, instantiate BuiltInAgent (Factory Mode with TanStack AI is the preferred default) or plug in any of 12 external agent frameworks (Mastra, LangGraph, CrewAI Crews/Flows, PydanticAI, ADK, LlamaIndex, Agno, AWS Strands, MS Agent Framework, AG2, A2A), enable Intelligence mode for durable threads + websocket, register server-side tools via defineTool, and wire voice transcription. Uses the fetch-based createCopilotRuntimeHandler primitive — the Express/Hono adapters are discouraged. Load the reference under references/ that matches your task.

Backend & APIs2.7K installs

copilotkit-setup

copilotkit/copilotkit

Use when adding CopilotKit to an existing project or bootstrapping a new CopilotKit project from scratch. Covers framework detection, package installation, runtime wiring (managed Intelligence or self-hosted SSE), provider setup, and first working chat integration.

2.7K installs

copilotkit-integrations

copilotkit/copilotkit

Use when wiring an external agent framework (LangGraph, CrewAI, PydanticAI, Mastra, ADK, LlamaIndex, Agno, Strands, Microsoft Agent Framework, or others) into a CopilotKit application via the AG-UI protocol.

Frontend & Design2.7K installs

Popular code quality & workflow skills

View category →

grill-me

mattpocock/skills

A relentless interview to sharpen a plan or design.

Code Quality & Workflow1.4M installs

improve-codebase-architecture

mattpocock/skills

Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.

Code Quality & Workflow1.2M installs

handoff

mattpocock/skills

Compact the current conversation into a handoff document for another agent to pick up.

Code Quality & Workflow1.1M installs

domain-modeling

mattpocock/skills

Build and sharpen a project's domain model. Use when discussing codebase terminology, writing or editing a GLOSSARY.md, or recording or editing an ADR.

Code Quality & Workflow890.6K installs

codebase-design

mattpocock/skills

Shared vocabulary for designing deep modules. Use when the user wants to design or improve a module's interface, find deepening opportunities, decide where a seam goes, make code more testable or AI-navigable, or when another skill needs the deep-module vocabulary.

Code Quality & Workflow863.8K installs

diagnosing-bugs

mattpocock/skills

Diagnosis loop for hard bugs and performance regressions. Use when the user says "diagnose"/"debug this", or reports something broken/throwing/failing/slow.

Code Quality & Workflow848.4K installs