CoopAI Owner's Manual

Congratulations on choosing CoopAI. This manual helps you get the most out of it, from your first chat to team-wide prompt libraries.

Why Coop

The context gap

Most AI coding tools only see the file you have open. CoopAI connects your code graph, Slack threads, Jira tickets, and docs so answers reflect how your org actually builds software, not just the current buffer.

By just using the beta version of CoopAI I have seen at least a 50% reduction in time I spend asking / answering questions… I spend at least 6 hours each week answering questions and cut that in half this past week. — Senior Engineer, Row Labs

Lightning Intelligence

CoopAI builds a secure cross-repo knowledge graph from webhooks and index jobs, not full monorepo copies on every laptop. Your source stays on your infrastructure.

Developer (free) includes full tool connectivity (code hosts and collaboration integrations via the admin portal), Deep-Index on up to 3 repos org-wide, workspace repos, chat, and quick actions in production mode, with AI usage capped at 80,000 tokens per 5-hour window. Pro adds unlimited Deep-Indexed repos, team seats, Collections, and higher seat-based limits.

Quick actions at a glance

Trust and data handling

See the Security page for architecture details.

Get Started

Developer (free) signup

1. Browser — Go to coop-ai.dev/signup/free, enter your work email, and create a password (or continue with Google).
2. Browser — Verify your email if prompted.
3. Extension UI — Install the VS Code extension (see below) and sign in under Settings → Account — Continue with Google or Continue with email (same address as signup).
4. Browser — Optional: open the admin portal with the same email/password or Google to manage your personal account.

Website login has no SSO. SAML sign-in is available on the admin portal and in the VS Code extension only — not on coop-ai.dev/login. Enterprise developers use Sign in with SSO in the extension; org admins use Continue with SSO on the admin portal login page.

Forgot your password? Use Forgot password on the website or admin portal, or the Forgot password? link in the extension.

Enterprise checkout

1. Browser — Choose a plan on Pricing and complete Stripe checkout.
2. Browser — On the Welcome page, wait for provisioning (usually under a minute).
3. Email — Check your inbox for your account welcome email.
4. Browser — Admin portal — Open admin.coop-ai.dev/login. Sign in with email/password, Continue with Google, or (Enterprise) enter Organization name → Continue with SSO. The marketing site login at coop-ai.dev/login does not offer SSO — use the admin portal for SAML.
5. Admin portal — Connect GitHub (GitHub App on company org — use Send link to GitHub admin if IT owns GitHub), Slack, and other tools once for your whole org.
6. Admin portal — Invite teammates from the Users page (or rely on IdP JIT after SSO is configured).
7. Extension UI — Developers install CoopAI in VS Code and sign in with Continue with Google, email/password, or Organization name + Sign in with SSO (Enterprise).

Enterprise onboarding timeline

Typical sequence for a new Enterprise org (org admin + IT). Adjust for your IdP and GitHub ownership.

Detail: Single Sign On (SSO), SAML SSO troubleshooting, admin portal, and operator guide docs/enterprise-integration-onboarding.md.

SSO-only org playbook

Use this when Require SSO is enabled in Settings → Single sign-on → Sign-in policy (password and Google blocked for new interactive sign-ins and token refresh).

1. Browser — IdP — Provision users in Okta / Entra / your SAML IdP with an email attribute (or email-format NameID). Map the same email your org uses in Coop.
2. Browser — Admin portal — Settings → Single sign-on → complete steps 1–2 (SP values into IdP, paste IdP Entity ID / SSO URL / cert) → Save SSO → Test connection with your admin identity.
3. Browser — Admin portal — Step 3: enable Require SSO only after a successful test. Coop shows a confirmation — a misconfigured IdP can lock everyone out. Enabling Require SSO also ends existing password/Google sessions for the org (SAML sessions stay). Allow email and password and Allow Google are hidden while Require SSO is on.
4. Browser — Admin portal — Users → promote at least one SSO user to admin if JIT created them as member (first SAML login defaults to member).
5. Browser — Admin portal login — All admins and members sign in at admin.coop-ai.dev/login with Organization name + Continue with SSO. Do not send users to coop-ai.dev/login — it has no SSO and returns sso_required for password attempts.
6. Extension UI — Developers use Settings → Account → Organization name + Sign in with SSO (browser handoff; VS Code completes automatically). No password invite required for SSO-only orgs.
7. Offboarding — Deactivate in Users, or automate POST /v1/auth/saml/offboard from your IdP provisioning job.

Known limits: Enabling Require SSO revokes password/Google sessions and refresh tokens for that org (SAML sessions remain). Org API keys (coop_…) still authenticate automation under Require SSO — revoke keys when users leave. SAML sessions default to 12 hours with no silent refresh. Full error codes and limits: SAML SSO troubleshooting.

Repository access (Pro / Enterprise)

Org admins control which Deep-Indexed repos developers see in VS Code.

Browser — Admin portal → Settings → Repository access

Per-user mode is useful when company repos and personal forks share an org. Developers see a read-only message in Settings → Tools when access is admin-controlled.

Operator smoke test: repo docs/repo-access-smoke-test.md (npm run smoke:repo-access).

Install the VS Code extension

1. Browser — Open the VS Code Marketplace listing for CoopAI (or use the install button on coop-ai.dev).
2. Extension UI — Click Install, then reload VS Code if prompted.
3. Extension UI — Open the Coop sidebar from the activity bar (Coop icon).

Sign in

Extension UI → Settings → Account

Three sign-in paths appear on one screen:

Email is two steps (same pattern as ChatGPT / Claude):

1. Enter your email address and click Continue with email.
2. Enter your password and click Sign in.
3. Use Forgot password? to reset, or ← Use a different email to go back.

Enterprise SSO requires your organization name before you click Sign in with SSO. Coop opens your system browser for IdP sign-in; when you finish, VS Code completes the session automatically. Organization name matching is case-insensitive. SSO is not available on coop-ai.dev/login — use the admin portal login for browser-based SAML.

After sign-in: Account shows your org and plan summary, plus Sign out.

Use coop-ai.dev/forgot-password if you need to reset your password outside the extension.

Automation API keys (coop_…) are for CI and scripts only — create them in the admin portal API Keys page, not in the extension.

Set repository context

1. Extension UI — Open Settings → Workspace.
2. Pick an indexed repo from your org catalog and set Primary branch (e.g. main).
3. Extension UI — Select the repository with Use repo (not a file). The three steps below match the screenshots under Understand Repo.

Understand Repo and /understand require that Use repo step — Settings owner/repo alone is not enough, and a file chip blocks the action. Find Owner / Knowledge Gaps can run with either a file chip or Use repo.

In production mode (coopAI.devMode: false), org admins connect code hosts in the admin portal — developers do not paste PATs.

Optional: connect integrations

Integrations (Slack, Jira, Confluence, Notion, Google Docs, Teams) power Trace Decision and Knowledge Gaps with cross-tool context.

If integrations are not connected, Coop still works for code-only questions. Ask your org admin to connect tools for full cross-tool context.

Enterprise SSO

Enterprise orgs sign in with SAML 2.0 through your company identity provider (Okta, Azure AD / Entra ID, or generic SAML). SSO is available on the Enterprise plan only.

Where SSO works

Organization name matching is case-insensitive on both surfaces. IdP setup detail (Okta, Entra, generic): Single Sign On (SSO). Error codes and known limits: SAML SSO troubleshooting.

Admin portal login (SSO)

1. Browser — Open admin.coop-ai.dev/login.
2. Scroll past email/password and Continue with Google to the or SSO section.
3. Enter your Organization name (exact name from billing or Settings → Account & organization).
4. Click Continue with SSO — your browser opens your IdP sign-in.
5. After authentication, you land in the admin portal dashboard.

Password and Google remain on the same page for orgs that have not enabled Require SSO.

Admin: configure SSO (3-step panel)

Org admins configure SAML at Settings → Single sign-on (/settings/single-sign-on). The panel follows three steps — match your IdP work to each:

If step 1 shows Service provider URLs unavailable, your Coop operator (not end users) must set COOP_PUBLIC_BASE_URL on the API server to the public backend URL (e.g. https://api.coop-ai.dev), then restart the API. This env var controls SAML callback URLs — it is operator infrastructure config, not something developers set in VS Code.

Full IdP walkthroughs: Single Sign On (SSO).

Admin portal settings hub

Settings is a hub with nested pages (not one long form). Open Settings in the sidebar, then choose a card:

Extension: sign in with SSO

1. Extension UI — Settings → Account.
2. Enter your Organization name below the email fields (case-insensitive).
3. Click Sign in with SSO — Coop opens your system browser for IdP login.
4. Complete sign-in in the browser; return to VS Code. Account shows your org and plan when the session is ready.

Admin portal login uses the same org name with Continue with SSO on /login instead of Sign in with SSO.

Known limits (Enterprise SSO)

See SAML SSO troubleshooting — Known limits for the full list.

Using the Extension

Open the Coop sidebar

The Coop sidebar lives in the VS Code activity bar. When chat is empty, you'll see the CoopAI wordmark with a short hint to ask about the repo or type / for commands. Structured workflows (Understand Repo, Trace Decision, and the rest) live in the Workflows menu in the chat header — not as a list under the logo.

Start a new chat

Use the chat header at the top of the sidebar:

Previous threads stay in the dropdown until you delete them. Starting a new chat or switching threads does not cancel an in-flight reply — that turn keeps generating in the background (shown as “Generating…” in the thread list). Open the thread again to watch it finish, or press Stop on that thread to cancel only that turn. Quick actions and slash commands always run in the active thread.

If a past thread was working on a specific file, switching back to that thread restores the file chip and opens that file in the editor. Reloading VS Code alone does not reopen last session’s file.

Chat composer

Type free-form questions in the composer. Coop streams answers grounded in your code graph and connected integrations. Free-form chat uses OpenAI GPT-5 mini — assigned by Coop, not user-selected.

• Press Enter to send (Shift+Enter for a new line).
• Responses stream in real time with markdown formatting.
• Chat history persists in the session.

Active file context chip

The chip above the composer (right side) shows which file Coop is using as chat context. It is not an @ mention and is separate from the AGENTS.md pill.

• Open a file in the editor → the chip follows the active (last-focused) text tab.
• Choose a file in Coop’s explorer → the chip updates and the file opens in the editor.
• Click the chip → focuses that file in the editor.
• Close that tab → the file chip clears.
• Reload VS Code → Coop does not reopen last session’s file or leave a ghost file chip (unless that file is already open).
• Switch back to a past chat thread that used a file → that file chips and opens again.

A repo-only chip (/RepoName) appears only when you choose Use repo in the explorer with no file selected.

Outside-workspace files (for example Downloads) stay L and work for plain chat. Quick actions that need the code graph may stay blocked until you open a repo file — the chip is not removed.

@-mentions and attachments

• Type @ to search files and attach extra paths for one message (up to 3 @-mentions). These are separate from the active-file chip above.
• Use the paperclip to attach files — images, PDFs, or text (up to 4 per message).
• Selected lines in the editor are included automatically as context.

Slash commands

Type / in the composer to see available commands. Quick actions:

Integration commands: /slack, /jira, /teams, /confluence, /notion, /docs.

Settings overview

Open CoopAI Settings from the gear icon in the sidebar title bar (opens a dedicated settings tab). You can also run CoopAI: Open Settings from the Command Palette.

Right-click any selection in the editor for Trace Decision, Find Owner, Blast Radius, or Knowledge Gaps. Understand Repo is repo-wide only — use Workflows → Understand Repo or /understand after Use repo in the Remote workspace picker.

Model assignments

Coop assigns a model per feature — you do not pick provider or model on Pro. Open Settings → Preferences → Model & chat to see four read-only assignment rows with On / Off badges.

Create pull request Notes use OpenAI GPT-4o mini and are labeled (AI Generated) — you can edit them before submit.

Enterprise custom model selection is coming soon. With coopAI.devMode: true, provider and model dev overrides apply to local testing only — not production routing.

One toggle remains editable:

Chat, quick actions, and edit patches are always on. Click Save model settings after changing the autocomplete toggle.

Inline complete and edit selection

Inline complete — Ghost-text autocomplete as you type. On by default for new installs. Coop routes completions to Mistral Codestral (FIM).

Toggle Autocomplete in the chat header — On / Off — for a quick switch while you code. For a persistent preference, use Settings → Preferences → Model & chat → Enable inline autocomplete. The header toggle and this checkbox stay in sync. Preferences persist at global scope — workspace .vscode/settings.json cannot silently override your choice.

Settings path: Open CoopAI Settings → Preferences → Model & chat → check or uncheck Enable inline autocomplete → Save model settings. The header toggle and this checkbox stay in sync.

How it works:

• VS Code InlineCompletionItemProvider shows streaming ghost text
• FIM (fill-in-the-middle) sends prefix + suffix segments when coopAI.autocomplete.useFim is true (default) — routed to assigned Mistral Codestral
• Hot Streak keeps completions snappy after Tab-accept; Smart Throttle adapts debounce to typing speed and latency
• Multi-line completions activate after {, =>, (, or inside blocks (up to 200 tokens)
• Indexed repos: when the workspace repo is Deep-Indexed and index status is ready, graph context (dependents and ownership) is attached automatically — no extra setting required. A one-time toast may confirm autocomplete is available with graph context. Set coopAI.autocomplete.useGraphContext to true to force graph on; leave at false (default) for auto when indexed (all plans)

Copilot: when Coop autocomplete is on, Coop automatically disables Copilot inline ghost text (github.copilot.enable) and restores your prior setting when you turn Coop autocomplete off. Copilot chat and other features stay available.

Full guide: Inline autocomplete.

Edit selection — Shipped. Highlight code, describe the change in chat with /edit, /patch, or /fix, then Apply the generated patch from the VS Code notification. Coop routes edit patches through OpenAI GPT-5.1, attaches the full active file (selection is a focus hint, not a context window cut), and includes your editor selection text when present (coopAI.includeSelection, default true).

Full guide: Edit mode.

Completion-only routing — Inline requests use a separate zero-retention path (x-use-case: code-completion-only), distinct from chat.

Create a pull request

You can open a pull request for your team without leaving VS Code.

Three ways — all open the same confirm step. Cancel, Escape, or clicking away creates nothing.

• Click Create pull request on a patch card — that Apply only.
• Type Create a PR in chat after Apply — every /edit you Applied in this thread.
• Type Create a PR in chat after editing a Use-repo file — dirty buffers, no Apply required. Unsaved is fine.

There is no /pr slash command.

Open a pull request

1. Select the repository with Use repo.
2. Either Apply an /edit, or type in a Use-repo file.
3. Click Create pull request on a card, or type Create a PR in chat.
4. Review Branch (default coop/patch), Title, and Notes (AI Generated). Edit anything you want.
5. Click Create pull request. Coop shows a link — open it to see the PR. Or Cancel.

Undo restores the editor. It does not close the PR.

Full guide: Create pull request.

Quick Actions

Run quick actions from the Workflows menu in the chat header, slash commands in chat (/understand, /trace, /owner, …), or the editor context menu. Right-click a selection for Trace Decision, Find Owner, Blast Radius, or Knowledge Gaps — Understand Repo is not file-scoped; use Workflows → Understand Repo or /understand after Use repo. Structured quick actions and integration slash commands (/slack, /jira, …) use Anthropic Claude Sonnet 4.6 — assigned by Coop for reliable, evidence-backed outputs.

When to use each action

Understand Repo

Slash: /understand (aliases: /understandrepo, /repo, /architecture, /explain)

Requires: An explicit Use repo selection in the Remote workspace picker (repository row, not a file). Settings → Workspace owner/repo alone does not unlock it.

Ignores individual files: If a file chip is active (open editor file or remote file pick), Workflows → Understand Repo and /understand stay blocked until you click Use repo on the repository. This action never deep-dives a single file — use plain chat, Trace Decision, or Blast Radius for that.

Select a repository (then run Understand Repo)

1. Extension UI — Open the remote file / repos picker (repos control in the Coop sidebar).
2. Select the repository (not a file) and click Use repo.
3. Success: a repo-only chip (/RepoName), In use on the picker, and Understand Repo available from Workflows or /understand.

Default prompt: "Understand this repository's architecture, subsystems, and risks."

What you get: A repo-wide overview (Summary → Architecture → Key subsystems → Entry points → Risks & unknowns → optional Related documentation → Suggested next steps → Sources), plus a Sources / evidence card when index and integrations return in time.

Example:

I'm onboarding to coop-backend — where does webhook ingestion start, and how do events flow into the job queue vs GraphCache? What are the 5 files I should read first to trace a GitHub push end-to-end?

/understand focus on the webhook ingestion path

Trace Decision

Slash: /trace (aliases: /why, /decision, /history)

Requires: An open file in the editor.

Default prompt: "Trace the engineering decision behind this code."

Example:

Pull the Slack thread and Jira ticket tied to auth_middleware.go — why did we add zero-retention headers here? Cross-reference commits on internal/llm/router.go from the last 90 days.

/trace why was zero-retention added here

Find Owner

Slash: /owner (aliases: /who, /find-owner)

Works without open file: Yes — with Use repo in the Remote workspace picker, or with a file chip. Settings → Workspace owner/repo alone is not enough.

Default prompt (file): "Find who owns this area and how to reach them."

Default prompt (repo-wide): "Map repository ownership and who to contact."

Example:

Who owns services/billing/invoice_handler.go? CODEOWNERS says @platform-payments but git blame shows @marcus. Does pkg/ledger/posting.go share the same on-call rotation?

Blast Radius

Slash: /blast (aliases: /impact, /blast-radius)

Requires: An open file in the editor.

Default prompt: "Estimate the impact of changing this code."

Example:

If I refactor TokenValidator.validate() in internal/auth/token_validator.ts, what breaks downstream? List dependents in api-gateway, workers/webhook-processor, and any shared libs.

/blast what breaks if I change the token validator

Knowledge Gaps

Slash: /gaps (aliases: /unknowns, /knowledge-gaps)

Works without open file: Yes — with Use repo, or with a file chip. Settings → Workspace alone is not enough.

Default prompt (file): "Audit documentation and ownership gaps for this area."

Default prompt (repo-wide): "Audit documentation and ownership gaps across this repository."

Example:

Before I ship changes to GraphConsistencyManager.applyEvent(), what am I missing? Any Slack threads or Jira tickets on webhook dedupe?

File-level vs repo-wide

Integration slash commands

Integration commands query connected tools with the same Anthropic Claude Sonnet 4.6 routing as quick actions.

Example: /slack what did #platform-auth decide about session TTL?

Prompt Library

Saved prompts in the sidebar

Click Prompts in the chat composer footer to open a dropdown of your pinned prompts. Select a prompt to insert it into the composer with current file and workspace context filled in. Press Send when you are ready.

If you already have text in the composer, the saved prompt is appended below it.

Pin your top 5

1. Extension UI — Open Settings → Preferences → Prompt library, or click See all prompts… in the Prompts dropdown.
2. Pin up to 5 prompts — they appear in the Prompts dropdown.
3. Drag pinned rows to reorder them. Click Use on any row to insert it into the composer.

Save a prompt from chat

1. Extension UI — Type a prompt in the chat composer.
2. Click Save to library (shown when you have a workspace open and text in the composer).
3. Name the prompt and click Save. Coop writes it to .coop/prompts.json and links a quick action automatically when the text starts with a slash command like /understand.

Workspace prompts file

Teams share prompts via .coop/prompts.json in the repository root. Commit it to git so everyone gets the same library.

Template variables

At run time, Coop substitutes:

Link prompts to quick actions

Set actionId on a prompt to route through a quick-action pipeline:

When actionId is set, your template becomes the user intent appended to the action — not a replacement for Coop's model prompt.

Example team prompts

{
  "version": 1,
  "prompts": [
    {
      "id": "onboard-webhooks",
      "title": "Onboard: webhook flow",
      "template": "Trace webhook ingestion from HTTP handler to job queue. List the 5 files to read first.",
      "actionId": "understand-repo"
    },
    {
      "id": "pre-ship-gaps",
      "title": "Pre-ship gap check",
      "template": "Audit {{file}} for missing docs, unclear ownership, and open questions before I merge.",
      "actionId": "knowledge-gaps"
    },
    {
      "id": "refactor-impact",
      "title": "Refactor impact",
      "template": "What breaks if I change {{file}}? Prioritize cross-service dependents.",
      "actionId": "blast-radius"
    },
    {
      "id": "pr-reviewers",
      "title": "Suggest PR reviewers",
      "template": "Who should review changes to {{file}} on branch {{branch}}? Prefer blame-aware experts.",
      "actionId": "find-owner"
    },
    {
      "id": "incident-trace",
      "title": "Incident decision trace",
      "template": "/trace link commits and tickets for the last auth incident in {{repo}}",
      "actionId": "trace-decision"
    }
  ]
}

Pin onboard-webhooks, pre-ship-gaps, refactor-impact, pr-reviewers, and incident-trace as your top 5.

AGENTS.md

What AGENTS.md is for

AGENTS.md is your repository's operator manual for AI tools — canonical URLs, docs links, UI conventions, and setup surfaces. It lives in git alongside your code, not on the marketing site.

This Owner's Manual (what you're reading) is product documentation. Your repo's AGENTS.md is project-specific guidance for Coop, Cursor, and other agents working in that codebase.

What to put in it

• Canonical URLs (API, admin portal, docs)
• Build and test commands
• Architecture overview and internal API conventions
• Rules for how agents should give setup instructions to users
• Pointers to deeper docs in your repo

How Coop uses it

When project instructions are enabled, Coop loads AGENTS.md (and subtree-specific files in large monorepos) on every chat turn — not only for Understand Repo. If no AGENTS.md is found, the composer shows an Attach AGENTS.md prompt. Keep the top-level file general; add subtree-specific AGENTS.md files for large monorepos.

Keep it tool-agnostic

Write AGENTS.md so any AI assistant can follow it — plain Markdown, explicit surfaces (File / Terminal / Browser / Extension UI), and links to deeper docs in your repo. Avoid editor-specific config syntax so the same file helps every teammate regardless of the tools they use.

For large monorepos, add a nested AGENTS.md inside individual service or package folders. Coop loads the nearest file for the code you're working in, so root-level conventions stay general while service-specific notes live next to the code.

Example AGENTS.md skeleton

# Agent guide — my-project

## Canonical URLs

| Purpose | URL |
| --- | --- |
| API | https://api.example.com |
| Staging | https://staging.example.com |

## Build & test

- `npm run build` — production build
- `npm test` — unit tests
- `npm run lint` — ESLint

## Architecture

Brief overview of services, entry points, and where to find docs.

## Agent instructions

When giving setup steps, name the surface (File / Terminal / Browser / Extension UI).

Ask Coop: "Update AGENTS.md based on what I told you in this thread" to generate or refresh it.

Developer vs Pro

See Pricing for current limits and upgrade paths.

When to ask your admin

In production mode, org admins connect code hosts and collaboration tools once in the admin portal. Individual developers sign in to Coop — they do not paste OAuth tokens in VS Code.

Ask your admin if:

• Quick actions return "integration not connected"
• You need a teammate invited or more than 3 Deep-Indexed repos (upgrade to Pro)
• Teammates need invites or seat assignments

Full admin setup is covered in the Documentation hub.

Troubleshooting

Support

• Email: support@coop-ai.dev
• Demo / enterprise: Book a demo
• Documentation: Docs hub for admin portal, integrations, API reference, and enterprise deployment
• Enterprise SSO: Single Sign On (SSO) setup · SAML SSO troubleshooting error codes
• Security questions: Security page