copilotkit-react-patterns

# CopilotKit React Patterns

Best practices for building agentic React applications with CopilotKit. Contains 25 rules across 6 categories, prioritized by impact to guide code generation and refactoring. Covers both v1 (`@copilotkit/react-core`) and v2 (`@copilotkit/react-core/v2`) APIs.

## When to Apply

Reference these guidelines when:
- Setting up `CopilotKit` provider in a React application
- Using agent hooks (useAgent, useFrontendTool, useCopilotAction)
- Rendering tool calls or custom messages from agents
- Managing shared state between UI and agents via useCopilotReadable or useCoAgent
- Building chat interfaces with CopilotChat, CopilotSidebar, or CopilotPopup
- Configuring suggestions for proactive agent assistance

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Provider Setup | CRITICAL | `provider-` |
| 2 | Agent Hooks | HIGH | `agent-` |
| 3 | Tool Rendering | HIGH | `tool-` |
| 4 | Context & State | MEDIUM | `state-` |
| 5 | Chat UI | MEDIUM | `ui-` |
| 6 | Suggestions | LOW | `suggestions-` |

## Quick Reference

### 1. Provider Setup (CRITICAL)

- `provider-runtime-url` - Always configure runtimeUrl to connect to your agent backend
- `provider-single-endpoint` - Configure the agent prop for CoAgent routing
- `provider-nested-providers` - Scope agent configurations with nested CopilotKit providers
- `provider-tool-registration` - Register tools via hooks inside provider, not as props when possible

### 2. Agent Hooks (HIGH)

- `agent-use-agent-updates` - Specify update subscriptions to avoid unnecessary re-renders
- `agent-agent-id` - Always pass agentId when running multiple agents
- `agent-context-description` - Write descriptive context values for useCopilotReadable
- `agent-frontend-tool-deps` - Declare dependency arrays for useFrontendTool
- `agent-stable-tool-handlers` - Use useCallback for tool handler functions

### 3. Tool Rendering (HIGH)

- `tool-typed-args` - Defin...

# CopilotKit React Patterns

A structured skill for CopilotKit React best practices, optimized for agents and LLMs.

## Structure

- `rules/` - Individual rule files (one per rule)
  - `_sections.md` - Section metadata (titles, impacts, descriptions)
  - `_template.md` - Template for creating new rules
  - `{prefix}-{name}.md` - Individual rule files
- `metadata.json` - Document metadata (version, organization, abstract)
- __`AGENTS.md`__ - Compiled output (generated)

## Categories

| # | Category | Rules | Prefix |
|---|----------|-------|--------|
| 1 | Provider Setup | 4 | `provider-` |
| 2 | Agent Hooks | 5 | `agent-` |
| 3 | Tool Rendering | 5 | `tool-` |
| 4 | Context & State | 4 | `state-` |
| 5 | Chat UI | 4 | `ui-` |
| 6 | Suggestions | 3 | `suggestions-` |

## Getting Started

```bash
pnpm install
pnpm build
pnpm validate
```