Operator OS
All pages

Integrations

Tools and integrations

What this layer is / Why it matters

Claude is only as useful as what it can reach: your mail, calendar, files, code hosting. This layer is about connecting those things the quiet, repeatable way, so Claude can do the work without taking over your screen, and so the same setup also runs in the background (layer 5).

Core (everyone)

The decision order

Always try in this order:

  1. Connector (MCP). A ready-made plug-in managed at claude.ai. No code.
  2. CLI. A command-line tool with a saved login. Works in scheduled jobs.
  3. Browser. Claude drives Chrome. Last resort.

Why: connectors and CLIs are silent and the same every time. A browser steals focus, opens the wrong window, and cannot run while you sleep.

Turn on connectors

  1. Open claude.ai, then Settings, then Connectors.
  2. Pick Gmail, Google Calendar, Google Drive or Notion and click Connect.
  3. Sign in with the account you want Claude to see.
  4. Restart Claude Code. Connector tools load when a session starts.

Connections belong to one Claude account. If you have a personal and a work Claude account, authorize each one separately. A connector sees exactly one Google account, so write down which (in your TOOLS.md). Mixing work and personal mail through one connector is the easiest way to leak data.

Connector limits: Gmail can read and draft. Anything beyond that, such as sending or bulk changes, may need the CLI.

Your cheat-sheet

Copy integrations/TOOLS.template.md to ~/Work/_context/TOOLS.md. Fill in your accounts and tools. Claude reads it, so it stops guessing.

Browser: last resort

Use Claude in Chrome only when nothing else works (for example, downloading an attachment). Say why, then do it. Two rules:

  • Do not take screenshots while you are using the computer. A capture grabs whatever is on screen, including private windows. Verify pages with curl or by reading the page content.
  • Headless test browsers can block link clicks. If a click "does nothing", suspect the tool and open the address directly.

Advanced (developers)

Google Workspace CLI with many accounts

gws has no profiles: one config folder is one Google account. integrations/bin/gws-as fixes that:

gws-as --list
gws-as maya-work auth login -s drive,gmail,calendar
gws-as maya-work gmail +triage
gws-as --who maya-work

Profile default uses ~/.config/gws. Any other name uses ~/.config/gws-<name> with the file keyring backend, so it never touches the macOS Keychain.

The traps

  1. OAuth app in Testing mode. Google expires its refresh tokens every 7 days, so logins keep vanishing. In Google Cloud Console, open Auth Platform, Audience, and Publish app (set the app name, support email and a home page first). An unverified app shows a warning at login; click Continue.
  2. Wrong Google account at login. If your browser is already signed in elsewhere, Google may auto-pick that account. Login looks fine, but every call returns 403 "Caller does not have required permission to use project...". Run gws-as --who <profile>, then log in again in a private window.
  3. API not enabled. "Failed to get token" or 401 does not always mean lost access. The Gmail API may be off in the Google Cloud project that owns your OAuth client (not the project auth status displays). Read the real error with RUST_LOG=debug, then gcloud services enable gmail.googleapis.com --project=<project>.
  4. Keychain locked during DarkWake. A job that fires while the lid is closed can find the Keychain locked, and gws treats your login as broken. The file backend in gws-as avoids it.
  5. Never trust an agent's "I saved a draft" claim. Check Gmail directly.
  6. New profile 403s although login worked. The profile's client_secret.json may carry a project_id for the wrong project. Keep it while logging in, then try removing it.

Dev CLIs

  • gh (GitHub): gh pr create, gh run list, gh issue list.
  • vercel: npx vercel list, logs, env ls. On the free Hobby plan, only commits authored by the account owner deploy.
  • supabase: projects list, db push, functions deploy. The Supabase connector also runs SQL.

Log in once with each tool (gh auth login, vercel login, supabase login). Keep tokens out of the repo.

Lessons from real use

  • Prefer quiet tools. Driving a real browser interrupted work, opened the wrong profile, and cannot be scheduled.
  • 403 is not "expired". It was a wrong-account login three times before it was a real permission problem. Test with a live call before re-logging in.
  • A published OAuth app ended the weekly "I'm logged out" cycle. Do it on day one.
  • One mailbox per profile. Reading each mailbox directly beats forwarding everything into one inbox: forwards cost storage and hide who a message was really for.
  • Connectors load at session start. If a tool "is missing", restart the session before debugging.