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

1. Fork and clone the CopilotKit/CopilotKit repository.
2. Install dependencies with pnpm install (requires pnpm v9.x and Node 20+).
3. Build once with pnpm build to bootstrap all packages.
4. Create a branch using the naming convention: feat/<ISSUE>-<name>, fix/<ISSUE>-<name>, or docs/<ISSUE>-<name>.
5. Develop with pnpm dev (watches all packages) or target a specific package with nx run @copilotkit/<pkg>:dev.
6. Write and run tests with nx run @copilotkit/<pkg>:test. All v2 packages use Vitest.
7. Lint and format with pnpm run lint --fix && pnpm run format.
8. Commit using conventional commit format: <type>(<scope>): <subject> (enforced by commitlint).
9. Push and open a PR against the main branch. 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 test to verify all tests pass.
• Run pnpm run build to verify the full build succeeds.
• Run pnpm run check-prettier to 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