copilotkit-contribute
Contributing to CopilotKit
Important: CopilotKit's internal v2 packages use the
@copilotkit/*namespace. The public API that users install is@copilotkit/*. When contributing, you work with@copilotkit/*source but users never see that namespace.
Live Documentation (MCP)
This plugin includes an MCP server (copilotkit-docs) that provides search-docs and search-code tools for querying live CopilotKit documentation and source code.
- Claude Code: Auto-configured by the plugin's
.mcp.json-- no setup needed. - Codex: Requires manual configuration. See the copilotkit-debug skill for setup instructions.
Workflow
- Fork and clone the CopilotKit/CopilotKit repository.
- Install dependencies with
pnpm install(requires pnpm v9.x and Node 20+). - Build once with
pnpm buildto bootstrap all packages. - Create a branch using the naming convention:
feat/<ISSUE>-<name>,fix/<ISSUE>-<name>, ordocs/<ISSUE>-<name>. - Develop with
pnpm dev(watches all packages) or target a specific package withnx run @copilotkit/<pkg>:dev. - Write and run tests with
nx run @copilotkit/<pkg>:test. All v2 packages use Vitest. - Lint and format with
pnpm run lint --fix && pnpm run format. - Commit using conventional commit format:
<type>(<scope>): <subject>(enforced by commitlint). - Push and open a PR against the
mainbranch. CI builds all packages and publishes preview packages via pkg-pr-new.
Before Opening a PR
- Reach out to the maintainers first for any significant work (file an issue or ask on Discord).
- Run
pnpm run testto verify all tests pass. - Run
pnpm run buildto verify the full build succeeds. - Run
pnpm run check-prettierto verify formatting. - Ensure commit messages follow the
<type>(<scope>): <subject>format.
Quick Reference
| Task | Command |
|---|---|
| Install dependencies | pnpm install |
| Build all packages | pnpm build |
| Dev mode (all) | pnpm dev |
| Dev mode (v2 only) | pnpm dev:next |
| Run all tests | pnpm run test |
| Run v2 tests only | pnpm test:next |
| Run single package tests | nx run @copilotkit/core:test |
| Test with coverage | pnpm run test:coverage |
| Lint | pnpm run lint |
| Format | pnpm run format |
| Check formatting | pnpm run check-prettier |
| Type check | pnpm run check-types |
| Package quality checks | pnpm run check:packages |
| Dependency graph | pnpm run graph |
Key Architecture Points
- V2 (
@copilotkit/*) is the real implementation. V1 (@copilotkit/*) wraps V2. - New features always go in V2 packages under
packages/v2/. - Communication between frontend and runtime uses the AG-UI protocol (SSE-based events).
- The monorepo uses Nx for task orchestration and pnpm workspaces.
Reference Documents
- Contribution Guide — full onboarding walkthrough
- Repo Structure — package layout and architecture
- Testing Guide — Vitest setup, running tests, coverage
- PR Guidelines — CI checks, review process, expectations
More from copilotkit/skills
copilotkit
Use when building with CopilotKit — setup, development, integrations, debugging, upgrading, or contributing. Routes to the appropriate specialized skill based on the task.
285copilotkit-debug
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.
187copilotkit-agui
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.
186copilotkit-develop
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.
185copilotkit-setup
>
184copilotkit-self-update
Use when the user wants to update, refresh, or reinstall the CopilotKit agent SKILLS (the SKILL.md files that teach this agent about CopilotKit). NOT for updating the CopilotKit codebase or project — this is specifically about refreshing the skills/knowledge this agent has loaded. Triggers on "update copilotkit skills", "update skills", "refresh skills", "skills are stale", "skills are outdated", "get latest skills", "my copilotkit knowledge is wrong", "copilotkit APIs changed", "skills seem old", "wrong API names", "reinstall skills", "skills not working right", "update your copilotkit knowledge".
184