Connectors overview

A connector is a third-party integration that pulls signal into Carabase — pull requests from GitHub, events from Calendar, emails from Gmail, meetings from Granola, etc. Every connector self-describes via a ConnectorManifest so the Admin SPA can render its config UI without hardcoding per-connector knowledge.

Built-in connectors (v0.1)

Connector	Tier	Auth	Cadence
GitHub	core	OAuth (device flow)	Hourly
Google Calendar	core	OAuth (auth code)	Every 2 hours during the day
Gmail	core	OAuth (auth code)	Every 30 minutes
Granola	core	Edge harvester	Pushed by the macOS app

Plugin-backed connectors register through the getAllMcpTools() plugin registry and can ship as their own npm packages.

Sync rules

Every connector reads its config from a sync_rules row keyed on (workspace_id, integration_name). The config is a JSONB blob:

{
  "rules": [
    {
      "id": "uuid",
      "name": "PRs from acme/main",
      "enabled": true,
      "filters": { "repos": ["acme/main"], "states": ["open"], "lookbackHours": 24 },
      "routing": {
        "folioName": "acmebase",
        "tags": ["github", "pr"],
        "harvestToGraph": true,
        "injectToTimeline": true
      }
    }
  ]
}

Multiple rules per integration are supported. When an item matches more than one rule, tags are merged, all folios are resolved, and harvest/timeline are OR’d.

The Admin SPA’s Sync Rules page renders the per-rule filter form from the connector’s filterSchema (a JSON Schema in the manifest), so adding a new connector doesn’t require any UI work.

Edge harvesters

Some signal is only available locally — Granola meeting notes are stored in ~/Library/Application Support/Granola/cache-v3.json on whichever Mac runs Granola, not in any cloud. For these, Carabase exposes an edge harvester push pattern:

1. The Desktop client (or any local script) reads the local source
2. Pairs once via POST /api/v1/harvester-devices/pairing-codes → POST /api/v1/harvester-devices/claim, getting a bearer token
3. Pushes data to POST /api/v1/granola/sync (or the relevant connector route) with the bearer token

Multiple devices can register against the same workspace — e.g. Granola on a Mac mini and a laptop both pushing into the same host.

See Edge harvesters for the full pairing protocol.

Adding a new connector

There’s a /new-connector skill in .claude/skills/new-connector/SKILL.md that scaffolds the full playbook (manifest, filter type, registry registration, cron/push wiring, tests, docs). The short version:

1. Write the manifest in src/connectors/<name>.ts (export manifest: ConnectorManifest)
2. Register it in src/services/connector-registry.ts
3. Add the cron job in src/server.ts (or the push route if it’s an edge harvester)
4. Add a corresponding <Name>Filters type in src/types/sync-rules.ts
5. Test + docs

The Admin SPA picks up the new connector automatically through the GET /api/v1/connectors endpoint.