Comp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.
Connections — rules for AI agents
Covers /settings/connections and everything under it: the index, per-connection
pages, the add-connection picker, and identity matching.
Read docs/design.md first. Read docs/api.md before touching apps/api, and
docs/agent.md before touching apps/agent. The Paper file is
app.paper.design/file/01KZ72S23CM00WXN6S1MP68M03/1-0, page crm - grim.
The one rule that governs everything here
A connection is a capability. An automation is an agent.
A connection page shows what a connection can do, who it is wired to, and which
agents use it. It never owns, authors, or edits an automation. Automations are
built in the agent builder chat by tagging the integration, and they live at
/agents/:agentId.
This is already true in code: builderResource.kind in
apps/api/src/conversations/conversations.contracts.ts is
["integration", "company", "contact", "deal"], and the composer picker in
apps/app/components/agent-builder/agent-composer.tsx is labelled "Tag CRM
records and integrations" with ids shaped google:calendar, google:gmail.
A new integration becomes taggable by extending that enum's id space, not by
building a second authoring surface.
If you find yourself adding a toggle, a trigger builder, or an "Edit automation" form to a settings page, stop — that work belongs in the builder.
Removing a connection is an owner or admin decision
A connection is shared. One person disconnecting Slack stops every agent that
posts to it and clears the cached channel list for everybody, so
SlackConnectionService.disconnect asks canManageConnections (@crm/auth)
after AgentAccessService.assertMember, and slack.status returns canManage
so the button is disabled for the same people the service refuses. Being signed
in is not authorisation: AuthMiddleware only proves a session exists.
Everything additive — joining a channel, creating one, refreshing people — stays open to any workspace member, because the agent builder needs it and Slack can undo it.
Connecting Slack is refused at the OAuth endpoints, not in the UI
Connecting is the same decision as disconnecting, because replaceSlackConnection
deletes every other Slack account row: a second person connecting replaces the
workspace's Slack, and every deployed agent then reads from and posts to whichever
Slack they installed. Hiding the button is not enough — authClient.linkSocial
is one POST.
slackConnectGuard (packages/auth/src/slack-connect.ts) is Better Auth's
hooks.before, and it asks the same canManageConnections the API does. It
covers all three doors: /link-social, /sign-in/social (Slack is a connection,
never a sign-in method, and that endpoint needs no session) and
/callback/slack. The callback is the one that matters — refusing there
happens before the code is exchanged, so a refused attempt writes no
SlackWorkspaceGrant user token and deletes no bot token. Google and Microsoft
sign in on different paths and never reach the guard.
slackOAuthCallback redirects the registered /oauth2/callback/slack URL to the guarded callback.
It preserves the code and state query parameters. Existing Slack app registrations keep their redirect URL.
A workspace with no owner and no admin lets any member connect. There is nobody left to ask, and a fresh install must not be locked out of its first connection.
Direction is the organising idea
Every connection declares what it brings in and what it sends. Use those two words. Not arrows, not "inbound/outbound", not scope tokens.
Sends earns its place by being reassuring when it is empty. HubSpot reads
"Nothing, so nothing here can change HubSpot" — that is the guarantee a migration
needs, stated where someone will look for it.
Destinations: derived or chosen
When an agent sends something, its destination is one of two kinds. Getting this distinction wrong is what makes an automation feel like it works by magic.
Derived — follows from the record, so never ask. The deal's owner. The channel that belongs to this deal. Say so explicitly in the UI ("The person who booked, at the email they booked with. Nothing to choose.") so the absence of a control reads as deliberate.
Chosen — cannot be inferred, so must be asked exactly once. A standing
channel like #sales. A naming pattern for channels the agent creates
(#deal-{company}). A billing contact.
Chosen destinations are collected in the builder conversation with the Questionnaire, not in a settings form. See "The Questionnaire" below.
Slack needs two grants, not one
A bot token cannot add itself to a private channel. No Slack scope grants that.
The workspace must also hand over a user token (xoxp-), which the app then
uses to act as the person who connected Slack.
- Public channel — the bot self-joins with
conversations.join. Bot token only. - Private channel — only a user token can invite the bot. Both tokens.
The bot token lives on Account. The user token lives on SlackWorkspaceGrant,
keyed by Slack team id, because the grant belongs to the workspace and not to the
person who clicked Connect. packages/auth/src/slack-grant.ts writes it, and
apps/agent/agent/lib/slack-connection.ts is the only place that reads either.
A missing user grant is a capability that is off, not an error. The connection page names it, and the private-channel row falls back to asking a human.
The cached row does not choose the token. joinSlackChannel
(apps/agent/agent/lib/slack-membership.ts) reads the channel from Slack with
conversations.info before it picks a path. slackChannel.isPrivate and
isMember are a cache, and a cache is wrong the moment somebody adds the bot in
Slack — or the moment a new column arrives with a default, which classifies every
existing row as public and non-member until the inventory next runs. A bot that
cannot see the channel at all is read as private and not a member, which is the
only safe reading. When Slack and the row disagree the row is corrected and a
slack-people-match task is queued, so the connection page stops showing the
stale classification too.
Nothing else calls Slack to read the channel list. The agent builder reads
the cached rows and, when they are older than SLACK.inventory.staleMs, queues
the same background task rather than waiting on a round trip
(apps/agent/agent/lib/slack-people.ts). A builder chat that blocks on Slack is
a builder chat that is as slow as Slack is.
The connections page also recovers a missing channel inventory. When Slack is
connected and an unfiltered channel read returns no rows, the API queues the
same durable agent task. It never calls Slack itself. A completed empty fill is
valid for SLACK_INVENTORY.throttleMs. A fill from before the current Slack
connection does not count, because a reconnect can select another workspace.
Permissions are shown in groups, not one line each
Sixteen scopes read as noise. Group them by what they touch — people, channels it
can read, messages it can send, channels it can change — and give each group a
count of how many reach the whole workspace. SLACK_SCOPE_GROUPS in
packages/auth/src/slack-scopes.ts owns both the grouping and the plain wording.
The catalogue is the single source. auth.ts builds its scope request from it and
the page renders from it, so the screen cannot promise something the app never
asked for.
Identity matching is connection-level
"Message whoever owns the deal" needs a CRM user and a Slack member. Those are two identities. Match on email, show the result, and let a human fix it.
An unmatched person must be allowed. The automation stops and says so rather than guessing at a similar name — and the connection page surfaces the count so the gap is visible before it bites.
The Questionnaire
The strongest pattern in this work. When the builder cannot derive something, it asks in chat rather than failing or guessing.
Reuse packages/ui/src/components/questionnaire.tsx — Questionnaire,
QuestionnaireItem, QuestionnaireTitle, QuestionnaireDescription,
QuestionnaireChoices, QuestionnaireChoice, QuestionnaireActions,
QuestionnaireSubmit. It is wired through agent-clarification-composer.tsx and
builderQuestionResponseInput.
Rules for a question:
- Ask only what cannot be derived. Say which parts you already worked out.
- Title is the question in plain words. Description says why it is being asked ("This one is a standing channel, so it is the same every time").
- Choices carry a fact that helps decide — member counts, last activity — not decoration.
- Always offer an escape ("Search for another channel").
- Footnote the constraint that shapes the list ("Only channels Slack has been added to").
- The submit label restates the answer: "Use #sales", not "Continue".
Failure is on the surface
Nobody owns these automations day to day, and a broken one currently sits for a week or two. So every connection surface leads with liveness, not configuration: "Last call arrived 31 minutes ago", "1 call needs a look", "3 of 4 matched".
An automation you cannot see rot in is one nobody will own.
Irreversible things are bounded in writing
Anything that messages a customer states its own limits next to the switch: "It stops the moment Stripe reports the payment, and never messages the same deal twice in a day." "It runs once per deal." An agent that DMs people about money needs its guardrails legible to whoever turns it on.
Layout
Every connection page renders through ConnectionPage, which is PageShell
with width="narrow". The shell owns the gutters, the top and bottom padding
and the column width, so connection pages line up with every other settings
page. Do not add a page wrapper of your own.
Metrics inside the column are tokens. Never a literal.
| Token | Value | Use |
|---|---|---|
--spacing-page-gap |
24px | Gap within flat sections |
--spacing-block-inline |
20px | Inset within legacy content blocks |
--container-page-wide |
1120px | Two-column or table pages |
--container-narrow |
560px | Empty states, dialogs |
--container-sheet |
640px | Edit sheet over a page |
--height-tool-panel |
400–640px | Scrollable tool inventories |
Page headers and section headers align with the column edge.
Shared SettingsCard components own their content padding and footer spacing.
Shared component sizes take precedence over the legacy content tokens above.
Use SettingsColumn between settings cards and PageSection for flat tool inventories.
Do not add an inset to page headers to match card content.
Connection status, synchronization choices, revocation, and deletion use separate settings cards. Tool access, permissions, and agent usage use flat page sections. Connection pickers retain cards for independent connection choices.
Brand marks
packages/ui/src/components/brand-logos/ has claude, eve, github, google,
microsoft, nextjs, slack, stripe, vercel. Stripe is there — use it.
Missing from the repo and living only in Paper: hubspot (hubspot icon
L5E-0), docusign (docusign logo L5Z-0), ergo (ergo logo KJJ-0).
Extract their path data into brand-logos/*.tsx shaped like stripe.tsx when
building these screens.
Until a mark exists, EntityLogo falls back to an initials monogram on
bg-muted — that is correct behaviour, not a placeholder to design around. Only
icon marks are used at these sizes; the wordmarks stay unused.
Docusign is spelled with a lowercase s since its 2024 rebrand. The note-taker is Ergo.
MCP connections
Clerk, Cloudflare, Linear, Neon, PlanetScale, Prisma, Supabase, and Vercel use the shared MCP connection flow. An owner or admin chooses read-only or read-and-write access. The API stores OAuth tokens in encrypted form. The API never returns tokens to the browser.
The agent builder lists only connected platforms. Each deployed version stores exact tool names and fingerprints. The deployment review shows each tool and its call kind. Changed tools stop until a new version receives review. Disconnecting a platform blocks the next tool call. The agent resolves MCP tools from the deployed version at session start. The model never receives disconnected, changed, unreviewed, or undeployed tools. Model-facing results stop at 16 KiB. Archived results stop below 32 KiB.
The chat compiles every connected provider result into the shared provider card. The compiler handles arrays, common collection objects, records, and short scalar results. The compiler removes secret fields, large text fields, unsafe links, and raw JSON walls. Known marks render automatically. Unknown marks use the approved initials fallback. Provider-specific result components are not required for new catalog entries.
Supabase read-only access also uses the hosted server's read_only=true mode.
Treat SQL execution, logs, keys, deployments, secrets, billing, and branch changes as risky.
Vercel accepts only reviewed MCP clients. Keep the Vercel connection unavailable in production until Comp AI CRM receives approval.