copilotkit-contribute

---
name: copilotkit-contribute
description: >
  Use when contributing to the CopilotKit open-source project — forking,
  cloning, setting up the monorepo, creating branches, running tests, and
  submitting pull requests against CopilotKit/CopilotKit.
version: 1.0.0
---

# 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](../copilotkit-debug/SKILL.md#mcp-setup) 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](references/contribution-guide.md) — full onboarding walkthrough
- [Repo Structure](references/repo-structure.md) — package layout and architecture
- [Testing Guide](references/testing-guide.md) — Vitest setup, running tests, coverage
- [PR Guidelines](references/pr-guidelines.md) — CI checks, review process, expectations