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