Skip to main content
Use Claude Code to build your plugin. Run the steps below in your terminal, then paste the prompt from the guide into Claude Code. It will fill in the real API calls for you.
The fastest way to build a custom plugin is to use the built-in generator. It scaffolds the full directory structure, wires up types, and registers your plugin. Then you (or Claude Code) fill in the real API calls.
1

Fork or clone the Corsair repo

Plugins live inside the monorepo alongside the core library.
2

Run the plugin generator

Pass your plugin name in PascalCase, for example Stripe, GoogleCalendar, or HubSpot.
For example:
This creates packages/stripe/ with the full plugin structure:
It also automatically registers your plugin in packages/corsair/core/constants.ts.
3

Choose your auth type

Open packages/<yourplugin>/index.ts and update the auth type to match the API you’re integrating with.API key (most REST APIs):
OAuth 2 (Google, GitHub, etc.):
Also update the defaultAuthType constant and authConfig to match:
4

Let Claude Code implement it

Point Claude Code at the API docs for your integration and let it do the heavy lifting.Open Claude Code in the repo root and give it a prompt like:
Claude Code can read the scaffold, understand the patterns from existing plugins (e.g. packages/github/), and produce a working starting point.
5

Typecheck and build

Fix any type errors, then register the plugin in your app the same way as any other Corsair plugin:
src/server/corsair.ts
6

Test your plugin

The repo includes a ready-made testing sandbox at demo/testing/. Add your plugin there and run scripts against it without setting up a new project.1. Add your plugin as a workspace dependency in demo/testing/package.json:
demo/testing/package.json
Then run pnpm install from the repo root to link it.2. Register your plugin in the test corsair instance:
demo/testing/src/server/corsair.ts
3. Write your test in demo/testing/src/scripts/test-script.ts:
demo/testing/src/scripts/test-script.ts
4. Run the script:
Build watch required In a separate terminal, run the build watcher in your plugin package so changes are picked up immediately:
Without this, the test sandbox will be running stale compiled output.

Tips

  • Look at existing plugins for reference. packages/github/ and packages/resend/ are good examples at different complexity levels.
  • Auth headers go in client.ts inside the HEADERS config object. Most APIs use Authorization: Bearer <key> or Authorization: <key>.
  • Webhook signature verification: update the TODO in webhooks/types.ts with the HMAC logic for your provider. Check it against the raw body (request.rawBody), not re-serialized JSON. When a check fails, return { success: false, error } instead of throwing: processWebhook reports it as a refusal (400), while a thrown error becomes a 500 that the sender retries.
  • Errors from client.ts: let core’s ApiError through unchanged, as the scaffold does. Its status and retryAfter are what error handlers match and what core reads to refresh an OAuth token after a 401. Wrapping it in a new error hides both.
  • Rate limits: core’s request() already retries a 429 three times and honors Retry-After. Keep the scaffold’s RATE_LIMIT_ERROR handler at maxRetries: 0 unless the endpoint needs more, or the attempts multiply.
  • Mark reads as reads: give each endpoint that only reads riskLevel: 'read' in the plugin’s endpoint meta (the scaffold’s example.get shows it). For OAuth plugins, core refreshes the token once and repeats a read that comes back 401. It leaves writes alone, because repeating one could send a request twice. If your endpoints already decide which 401s deserve a refresh, set refreshOnUnauthorized: false on the plugin.
  • Database entities: define Zod schemas in schema/database.ts for any data you want to cache locally. Leave entities: {} empty if you only need live API calls.