/connect

name: connect
description: Connect, check and manage your app integrations — Google and Linear are reviewed and ready; hundreds more (Slack, Notion, GitHub and others) connect with an extra confirmation. OAuth or paste-a-key, tokens stored encrypted on your machine.

Connect

Connect Dex to the apps you use, see what's working, and fix anything that's broken — all from one conversational command. Dex owns the OAuth runtime and stores every token **encrypted on your machine, never sent to a relay**.

Your sign-ins are **encrypted and kept on your machine** — never sent to our servers. Like other command-line tools that store logins, they are **not protected from other software running on your Mac as you**: a program running under your account could read them. That's the normal trade-off for a command-line tool, not a Dex-specific weakness. The **Dex desktop app closes this gap** when it ships — it adds a fingerprint check, and only the app can unlock the keys. Be honest about this if a user asks how safe their sign-ins are; never imply the command-line version can stop software already running as them, and never call it "secure", "safe", or "protected from malware".

This skill is a friendly driver over the connection manager CLI. You run the CLI verbs; you translate the output into plain language and clear next actions.

What This Enables

`/connect` is the front door for every integration:

• **See what's connected** — a health sweep of all your connections, with each one mapped to a next action (reconnect, refresh, or nothing needed)
• **Connect a new app** — two paths:
• **OAuth (Class A, 279 apps)** — before browser sign-in, the user must register their own app in the provider's developer console unless they already have one saved. Dex then guides browser consent, remembers the login locally, and auto-refreshes the token.
• **Paste a key (Class B, 348 apps)** — Linear, GitHub PATs, and other API-key services. No OAuth app or consent screen — paste the secret.
• **Reconnect** — when a token is revoked or expires beyond refresh, re-run the OAuth flow
• **Disconnect** — remove a connection and delete its local token
• **Find a provider** — fuzzy-search 831 catalog entries by name; 627 can be connected today (279 with OAuth/browser sign-in, 348 with a key)

The connection manager lives at: `core/integrations/connection-manager/`

All commands below are run from the dex-core root (paths are relative to it).

Privacy

• **Tokens are stored AES-256-GCM encrypted on-device** under `{DEX_VAULT}/System/credentials/` (the encryption key lives in macOS Keychain; non-Mac systems and explicitly configured test environments use a local key file).
• That directory is **gitignored** — credentials are never committed.
• **Nothing is sent to a relay.** Dex talks directly to the provider for authorization, token exchange, refresh, and any live check.
• The OAuth catalog (provider URLs, scopes, quirks) is consumed as **config data only** — it carries no credentials.
• `{DEX_VAULT}` means the vault configured by `DEX_VAULT` or `VAULT_PATH`. Dex stops and asks for a vault if neither is set; it does not guess a default folder.

When to Run

• User types `/connect`
• User asks to connect, link, or set up an app (Gmail, Google Calendar, Slack, Linear, GitHub, Jira, etc.)
• User asks "what's connected?", "is my Google still working?", or "what needs reconnecting?"
• User asks to disconnect or remove an integration
• A `/daily-plan` heads-up nudge surfaced a `needs_reauth` or `expired` connection

---

Setup Flow

Step 0: Is It Already Available Through Claude? (Check This First)

**Before sending anyone through a Dex connection flow, check whether the tool is already reachable through Claude's own connectors.** If Dex is running inside Claude, the user (or their company) has very likely already approved connectors there — Calendar, Gmail, Drive, Slack, and more — and Dex can simply *use* them. They show up as available tools (e.g. `Google Calendar`, `Gmail`, `Google Drive`). There's nothing to connect: the consent already happened in Claude, the company already approved it, and no Dex token is needed.

So the best first move is to look at what's already there:

• If the tool the user wants is already available via a Claude connector → **use it directly. Don't run a connection flow.** Just tell them "Good news — your Calendar's already connected through Claude, so I can read it right now. Want me to take a look at your day?"
• If it's *not* available through Claude → that's when Dex's own connection manager earns its place (Steps 1–7 below).

**This Dex flow is for two audiences:** people using Dex **outside** Claude (where there are no Claude connectors), and people who want a tool their **company hasn't given them** through Claude. For everyone else inside Claude, the connectors they already have are the fastest path — lead with those.

When something genuinely needs connecting, use the gaps as a friendly prompt: *"I can see your Calendar and Gmail through Claude already. I can't see Slack — want to connect that one through Dex?"*

Step 1: Check What's Already Connected

Run the health sweep (this covers Dex's *own* connections — the ones not coming from Claude):

node core/integrations/connection-manager/connect.cjs status

This first says whether the encryption key is in macOS Keychain or in the vault folder, then prints one row per connection with an icon and a status. The statuses are exactly: `connected` · `expiring` · `expired` · `needs_reauth` · `not_connected`.

**Explain the key line only if it says "vault folder" — and be straight about it.** Keychain is the normal case and needs no comment; mentioning it just adds noise. If the key is in the vault folder (non-Mac machines, or where the Keychain isn't available), say what that actually means for them in one sentence: the key sits in the same folder as the connections it unlocks, so anyone who gets a copy