copilotkit__copilotkit/CLAUDE.md

General Guidelines for working with Nx

• When running tasks (for example build, lint, test, e2e, etc.), always prefer running the task through nx (i.e. nx run, nx run-many, nx affected) instead of using the underlying tooling directly
• You have access to the Nx MCP server and its tools, use them to help the user
• When answering questions about the repository, use the nx_workspace tool first to gain an understanding of the workspace architecture where applicable.
• When working in individual projects, use the nx_project_details mcp tool to analyze and understand the specific project structure and dependencies
• For questions around nx configuration, best practices or if you're unsure, use the nx_docs tool to get relevant, up-to-date docs. Always use this instead of assuming things about nx configuration
• If the user needs help with an Nx configuration or project graph error, use the nx_workspace tool to get any errors
• For Nx plugin best practices, check node_modules/@nx/<plugin>/PLUGIN.md. Not all plugins have this file - proceed without it if unavailable.

Working under showcase/? Read showcase/AGENTS.md FIRST — it defines the non-negotiable iron rules for showcase cells.

CopilotKit

AI agent framework with three layers: Frontend (React/Angular/Vanilla) → Runtime (Express/Hono) → Agent (LangGraph/CrewAI/BuiltIn/Custom), communicating via the AG-UI protocol (event-based SSE).

Essentials

• Nx monorepo — always run tasks through nx (nx run, nx run-many, nx affected), never the underlying tooling directly.
• Flat package structure — all packages live directly under packages/ (no v1/ or v2/ subdirectories). Every package uses the @copilotkit/ scope.
• Simplicity — prefer the simplest correct solution. For non-trivial changes, consider if there's a cleaner approach before committing.
• No changesets — releases are conventional-commit-driven (scripts/release/ reads commit subjects). This repo migrated off Changesets; never create .changeset/* files — nothing consumes them and CI fails on them. Describe the change in the commit subject instead, and leave package.json versions and CHANGELOG.md files to the release tooling.
• Worktrees — always work in a git worktree for isolation. See Git & PRs for the full workflow.
• Documentation lives in shell-docs — author all CopilotKit docs in showcase/shell-docs/src/content/. The top-level docs/ path is only a symlink to showcase/shell-docs/; never recreate the old docs/content/docs/ tree. AG-UI protocol docs are authored upstream in ag-ui-protocol/ag-ui, not here. See Documentation.

Reference (read when relevant to your task)

• Architecture & Packages — package roles, request lifecycle, core concepts (AG-UI, ProxiedAgent, AgentRunner, tools, context, multi-agent)
• Hook Development — checklist for creating new hooks (docs, tests, JSDoc)
• Workflow & Process — when to plan, when to fix autonomously, verification, self-improvement loop, this should be your default mindset when working on any task
• Git & PRs — worktree workflow, branching, creating PRs
• Documentation — where to author docs (CopilotKit → shell-docs; AG-UI → upstream); docs/ is retired