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

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 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.

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:

pnpm install

After installation, these root-level scripts become available:

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 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:

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 — registers the plugin with the local server
2. Add calls to 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	Authoritative guide for fork, clone, and contribution workflow
README.md	High-level project description and platform rationale
package.json	Top-level workspace configuration and script definitions
packages/corsair/package.json	Core library dependencies and entry points
demo/testing/README.md	Instructions for running the local test sandbox
scripts/generate-plugin.ts	Source code for the plugin scaffolding CLI
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 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 and add test calls to 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}