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, listens from Spotify, and more. Every connector self-describes via a manifest, so the Admin SPA can render its config UI, the sync workers can schedule it, and the agent can query it without any per-connector code hardcoded into those surfaces.

Built-in connectors

Connector	Auth	Multi-account	Substrate	Notes
GitHub	OAuth (device flow)	no	—	Pull requests + issues. Historical backfill.
Google	OAuth (auth code)	yes	—	Unified Gmail + Calendar + Drive. Email/Drive attachments become searchable documents.
Google Analytics	OAuth (reuses Google)	yes	ga_metrics	GA4 web analytics, routed per property.
Strava	OAuth (auth code)	yes	activities	Workout history.
Spotify	OAuth (PKCE)	yes	listens	Recently-played listening history.
Last.fm	API key + username	no	scrobbles	Public scrobble history (fills the gap for any player that scrobbles).
WHOOP	OAuth (auth code)	yes	metrics	Recovery, strain, sleep, and workout records.
Peloton	Username + password	no	workouts	No OAuth available; credentials stored encrypted.
Linear	OAuth (auth code)	no	—	Issues + comments, plus webhooks for live updates.
Beeper	Local OAuth (dynamic registration)	no	—	Chat history across Beeper-connected networks.
Granola	API key (bearer)	no	—	Meeting notes via Granola’s public API.
Readwise	API key (bearer)	no	—	Highlights + Reader documents.
Reddit	OAuth (auth code)	yes	—	Saved/upvoted posts, your comments, subscribed subreddits.
Substack	RSS (no auth)	no	—	Polls public feeds for followed publications.
iMessage	Edge	no	—	Local chat.db push for people not on Beeper.
Apple Notes	Edge	no	—	Pushed by the macOS app.
Apple Photos	Edge	no	—	OCR + on-device identity.
Apple Files	Edge	no	—	File changes, with privacy-sensitive paths hard-skipped.
Apple HealthKit	Edge (iOS)	no	metrics	Workouts, samples, and sleep pushed from the iPhone app.
Safari	Edge	no	—	History, bookmarks, and reading list.
Google Maps Timeline	Import-fed	no	visits	Populated from a Google Takeout export — no live API.
AI Sessions	Edge	no	—	Captures local AI coding sessions as project evidence (off by default).

Connectors carry a tier: core connectors load on both the Desktop client and the Admin SPA; community connectors load on the Admin SPA only. Read the live roster from GET /api/v1/connectors (optionally filtered with ?tier=core|community).

The connector model

Each connector ships one manifest. Beyond its name and labels, the manifest declares:

• authType — oauth, api_key, edge, streaming, or import-fed. This drives the per-connector card the Admin SPA renders.
• tier — core or community (the surface gate above).
• filterSchema — a JSON Schema for the per-rule filters, so the Sync Rules editor renders a form with no per-connector UI work.
• multiAccount / sources — drive the per-account / per-source UX (Google, for example, covers Gmail, Calendar, and Drive as three sources).
• substrateTable + emitters — for high-frequency event streams (see Substrate connectors).
• backfill — when present, the SPA offers a “Backfill…” affordance to pull history.
• writeIntents — third-party write actions exposed to the propose-and-confirm external-action surface.
• mesh resolvers + “back to source” openers — so a stored item can be opened in its original app or service.

Because every connector reads from this one declaration, adding a connector doesn’t require touching the Admin SPA, the sync scheduler, or the agent’s query tools.

Authentication models

• OAuth — interactive flow; application credentials live encrypted in the oauth_apps table, never in environment files. Variants include device flow (GitHub), auth-code (Google, Strava, Linear, Reddit, WHOOP), PKCE (Spotify, Tidal), and dynamic client registration (Beeper).
• API key — you paste a token, stored encrypted (Granola, Readwise, Last.fm).
• Edge — the data lives on your device; the macOS sidecar or iOS app pushes it to Carabase (the Apple connectors, iMessage, AI Sessions).
• Import-fed — no live API at all; the only ingest path is a one-shot import (Google Maps Timeline, via Google Takeout).

Sync rules

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

{
  "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 unioned, and harvest/timeline are OR’d. The Admin SPA’s Sync Rules page renders each rule’s filter form from the connector’s filterSchema.

A few routing features worth knowing:

• Catch-all routing (fail-closed) — unmatched items are dropped unless you explicitly enable a catch-all, and only for connectors that declare one.
• Dry-run preview — POST /api/v1/sync-rules/:name/preview shows what a rule would match without writing anything.
• Prose rules — written at /admin/policy-rules, these refine an item’s routing after it’s ingested (off by default).

Edge harvesters

Some signal is only available locally — iMessage history, Apple Notes, or your file changes live on your Mac, not in any cloud. For these, Carabase uses an edge harvester push pattern:

1. The Desktop client (or any local script) reads the local source.
2. It pairs once via POST /api/v1/harvester-devices/pairing-codes then POST /api/v1/harvester-devices/claim, receiving a bearer token.
3. It pushes data to POST /api/v1/<connector>/sync with that token.

Multiple devices can register against the same workspace, so two Macs can both push into the same host. See Edge harvesters for the full pairing protocol.

Substrate connectors

High-frequency streams — workouts, listens, recovery metrics, location visits — declare a substrate table plus periodic emitters. Every observation is written to the substrate table first, regardless of whether any sync rule matches; the rule only controls whether the connector additionally creates daily-note entries, folio commits, or timeline injections on top.

Substrate data is queryable by the agent via carabase_query_timeseries, so trend and “how much did I…” questions stay accurate even when nothing was routed into your notes. The import-fed Google Maps Timeline connector follows the same model — its substrate is populated by the Takeout importer instead of a sync loop.