# How to Fork and Clone the Corsair Repository: Complete Setup Guide for Contributors

> Learn how to fork and clone the corsairdev/corsair repository with this complete setup guide. Follow our steps for a smooth contributor experience and get started contributing today.

- Repository: [corsairdev/corsair](https://github.com/corsairdev/corsair)
- Tags: getting-started
- Published: 2026-09-01

---

**To fork and clone Corsair, delete any existing fork on GitHub, create a fresh fork of `corsairdev/corsair`, clone it to a new local directory, and run `pnpm install` from the repository root to install dependencies.**

Corsair is an open-source integration platform organized as a **monorepo** containing core packages and plugin packages. Whether you're fixing a bug, adding a feature, or building a new integration, you'll need to properly fork and clone the repository before you can contribute. This guide walks through the exact workflow specified in the official contribution documentation.

## Understanding the Corsair Repository Structure

Before diving into commands, it helps to understand how the codebase is organized. The monorepo splits functionality across several key areas:

- **Core package** (`packages/corsair`) — houses the shared framework, database adapters, and authentication logic
- **MCP package** (`packages/mcp`) — Model Context Protocol implementation
- **CLI package** (`packages/cli`) — command-line tooling
- **UI package** (`packages/ui`) — user interface components
- **Studio package** (`packages/studio`) — development environment
- **Plugin packages** (`packages/*`) — each integration (Slack, Gmail, HubSpot, etc.) lives in its own folder

The `demo/testing` directory provides a sandbox for running plugins locally during development.

## Step-by-Step Fork and Clone Process

The **CONTRIBUTING.md** file at the repository root specifies a clean workflow to avoid merge conflicts and stale code issues. Follow these steps exactly as implemented in `corsairdev/corsair`:

### 1. Remove Any Existing Fork

If you've previously forked Corsair, delete that fork through the GitHub UI before creating a new one. This prevents surprise merge conflicts from outdated branches.

### 2. Fork the Repository on GitHub

Navigate to [`github.com/corsairdev/corsair`](https://github.com/corsairdev/corsair) and click the **Fork** button. This creates your personal copy under your GitHub username.

### 3. Clone Your Fork Locally

Use a fresh directory name that indicates your work. Avoid reusing old checkouts.

```bash
git clone https://github.com/<your-username>/corsair.git corsair-<integration-slug>
cd corsair-<integration-slug>

```

### 4. Install Dependencies

Corsair requires **Node.js 22+** and **pnpm 10**. From the repository root, run:

```bash
pnpm install

```

After installation, these root-level scripts become available:

```bash
pnpm typecheck   # Run TypeScript type-checking across all packages

pnpm lint        # Lint the entire codebase

pnpm build       # Compile all packages

pnpm test        # Execute the test suite

```

## Working with the Monorepo After Setup

Once you've forked and cloned Corsair, you'll interact with the workspace through pnpm. The top-level [`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json) defines workspace configuration and aggregates scripts across all packages.

### Generating a New Plugin

If your contribution involves a new integration, use the built-in generator rather than creating files manually:

```bash
pnpm run generate:plugin MyNewPlugin

```

This scaffolds the plugin structure in `packages/`. After generation, you must register the plugin in two locations per the codebase conventions:

1. Add to [`demo/testing/src/server/corsair.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/server/corsair.ts) — registers the plugin with the local server
2. Add calls to [`demo/testing/src/scripts/test-script.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/scripts/test-script.ts) — enables local testing

## Key Configuration Files for Development

These files anchor your understanding of the Corsair fork and clone setup:

| File | Purpose |
|------|---------|
| [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) | Authoritative guide for fork, clone, and contribution workflow |
| [`README.md`](https://github.com/corsairdev/corsair/blob/main/README.md) | High-level project description and platform rationale |
| [`package.json`](https://github.com/corsairdev/corsair/blob/main/package.json) | Top-level workspace configuration and script definitions |
| [`packages/corsair/package.json`](https://github.com/corsairdev/corsair/blob/main/packages/corsair/package.json) | Core library dependencies and entry points |
| [`demo/testing/README.md`](https://github.com/corsairdev/corsair/blob/main/demo/testing/README.md) | Instructions for running the local test sandbox |
| [`scripts/generate-plugin.ts`](https://github.com/corsairdev/corsair/blob/main/scripts/generate-plugin.ts) | Source code for the plugin scaffolding CLI |
| [`docs/guides/create-your-own-plugin.md`](https://github.com/corsairdev/corsair/blob/main/docs/guides/create-your-own-plugin.md) | Step-by-step plugin creation guide |

## Summary

- **Fork fresh** — delete old forks on GitHub to prevent merge conflicts
- **Clone to a new directory** — don't reuse stale checkouts
- **Install with pnpm** — requires Node 22+ and pnpm 10
- **Understand the layout** — core packages in `packages/corsair*`, plugins in `packages/*`
- **Use the generator** — `pnpm run generate:plugin` scaffolds new integrations

## Frequently Asked Questions

### Do I need to delete my existing Corsair fork every time I contribute?

Yes, according to the official [`CONTRIBUTING.md`](https://github.com/corsairdev/corsair/blob/main/CONTRIBUTING.md) at the repository root, you should delete any existing fork before creating a new one. This eliminates the risk of stale branches and unexpected merge conflicts when syncing with upstream changes. The workflow is designed for a completely fresh start.

### What Node.js version does Corsair require?

Corsair requires **Node.js 22 or higher**, along with **pnpm 10**. The `pnpm install` command at the repository root installs dependencies across all workspace packages. Running `pnpm build`, `pnpm test`, or other root-level scripts validates your environment setup.

### Can I clone Corsair into an existing directory with old code?

No — the contribution guide explicitly recommends cloning into a **new directory** with a descriptive name like `corsair-<integration-slug>`. Reusing old checkouts can introduce configuration drift and hidden state issues that complicate debugging.

### How do I test my changes after forking and cloning Corsair?

Use the `demo/testing` sandbox. Register your plugin in [`demo/testing/src/server/corsair.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/server/corsair.ts) and add test calls to [`demo/testing/src/scripts/test-script.ts`](https://github.com/corsairdev/corsair/blob/main/demo/testing/src/scripts/test-script.ts). Run `pnpm build` to compile changes, then execute your test script to verify behavior locally before submitting a pull request.