Skip to content

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

docs: restructure onboarding around user intent

Kshitij Jhunjhunwala943591ac9af9
diff --git a/docs/app/(home)/page.tsx b/docs/app/(home)/page.tsx
index 28b56ee8d..89a88707f 100644
--- a/docs/app/(home)/page.tsx
+++ b/docs/app/(home)/page.tsx
@@ -1,28 +1,5 @@
-import Link from 'next/link';
+import { permanentRedirect } from 'next/navigation';
export default function HomePage() {
- return (
- <div className="flex flex-col justify-center text-center flex-1 px-6 py-16">
- <h1 className="text-3xl md:text-4xl mb-4 font-medium tracking-tight" style={{ color: 'var(--composio-orange)' }}>
- Composio Documentation
- </h1>
- <p className="text-lg text-[var(--color-fd-muted-foreground)] max-w-xl mx-auto mb-8">
- Connect AI agents to 1000+ tools with managed authentication.
- </p>
- <div className="flex gap-4 justify-center">
- <Link
- href="/docs"
- className="px-5 py-2.5 rounded-lg bg-[var(--color-fd-foreground)] text-[var(--color-fd-background)] font-medium hover:opacity-90 transition-opacity"
- >
- Get Started
- </Link>
- <Link
- href="/docs/quickstart"
- className="px-5 py-2.5 rounded-lg border border-[var(--color-fd-border)] font-medium hover:bg-[var(--color-fd-muted)] transition-colors"
- >
- Quickstart
- </Link>
- </div>
- </div>
- );
+ permanentRedirect('/docs');
}
diff --git a/docs/app/global.css b/docs/app/global.css
index ea183a530..2e448ac4a 100644
--- a/docs/app/global.css
+++ b/docs/app/global.css
@@ -1140,6 +1140,21 @@ html:not(.dark) .terminal-theme-claude {
}
}
+@media (forced-colors: active) {
+ .audience-badge-platform {
+ background: none !important;
+ color: CanvasText !important;
+ -webkit-text-fill-color: CanvasText !important;
+ }
+
+ .audience-badge-platform-border {
+ background: none !important;
+ border: 1px solid CanvasText;
+ mask: none !important;
+ -webkit-mask: none !important;
+ }
+}
+
/* @pierre/diffs: the +/- stat counts in the file header are hidden via the
`unsafeCSS` option in components/diff-view.tsx, NOT here — the header renders
inside an open shadow root that global CSS can't pierce. */
diff --git a/docs/app/llms.txt/route.ts b/docs/app/llms.txt/route.ts
index 5b19a0b38..2b48cd6a8 100644
--- a/docs/app/llms.txt/route.ts
+++ b/docs/app/llms.txt/route.ts
@@ -100,6 +100,17 @@ function formatPage(page: { url: string }) {
return `- https://docs.composio.dev${page.url}.md`;
}
+const AUTHENTICATION_GUIDE_URLS = [
+ '/docs/manually-authenticating',
+ '/docs/managing-multiple-connected-accounts',
+ '/docs/shared-connections',
+ '/docs/importing-existing-connections',
+ '/docs/custom-app-vs-managed-app',
+ '/docs/programmatic-auth-configs',
+ '/docs/controlling-scopes',
+ '/docs/white-labeling-authentication',
+];
+
/**
* Splits reference pages by REST version.
*
@@ -150,10 +161,14 @@ ${legacyReferencePages.map(formatPage).join('\n')}
> Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
-> **For AI agents:** Give your agent tools it can call directly with \`composio.create(user_id)\` + \`session.tools()\` and a provider package (e.g. \`composio_openai\`, \`@composio/openai\`). To connect over MCP instead, create the session with \`mcp: true\` and read \`session.mcp.url\` from any MCP-compatible client. See any page's .md endpoint for full usage instructions.
+> **For AI agents:** Route by intent. To build an application, start with [Quickstart](https://docs.composio.dev/docs/quickstart.md) or [Providers](https://docs.composio.dev/docs/providers.md) and use \`composio.create(user_id)\` + \`session.tools()\`. To use Composio from Codex or Claude Code without explicit MCP intent, install the [native agent plugin](https://docs.composio.dev/docs/agent-plugins.md). To connect an existing client over MCP, use [Composio Connect](https://docs.composio.dev/docs/composio-connect.md). When an application creates a session and needs MCP transport, use [Sessions via MCP](https://docs.composio.dev/docs/sessions-via-mcp.md). See any page's .md endpoint for full usage instructions.
${docsTree}
+## Authentication guides
+
+${AUTHENTICATION_GUIDE_URLS.map(url => formatPage({ url })).join('\n')}
+
## Examples
${examplesPages.map(formatPage).join('\n')}
diff --git a/docs/components/docs-hero-v2.tsx b/docs/components/docs-hero-v2.tsx
index 5b5e90994..cf346304b 100644
--- a/docs/components/docs-hero-v2.tsx
+++ b/docs/components/docs-hero-v2.tsx
@@ -1,58 +1,15 @@
-import Link from 'next/link';
-import { Play, Code2, Blocks } from 'lucide-react';
-import { DocsHeroV2Chat } from './docs-hero-v2-chat';
-
-const CHIPS = [
- { label: 'Quickstart', href: '/docs/quickstart', icon: Play },
- { label: 'API reference', href: '/reference', icon: Code2 },
- { label: 'Toolkits', href: '/toolkits', icon: Blocks },
-];
-
-/**
- * Welcome-page hero — v2.
- *
- * Two-column layout: copy + entry points on the left, mock chat / agent
- * loop on the right. Left column mirrors the dev-platform pattern
- * popularized by Claude / OpenAI docs: small eyebrow, large headline,
- * sub paragraph, search input, then a row of quick-link chips.
- */
export function DocsHeroV2() {
return (
- <section className="relative grid grid-cols-1 items-start gap-8 py-4 md:py-6 lg:h-[500px] lg:grid-cols-2 lg:gap-12">
- {/* Left — copy + entry points */}
- <div className="flex flex-col gap-5">
- <h1 className="text-3xl font-medium leading-[1.05] tracking-[-0.025em] text-fd-foreground md:text-4xl lg:text-[40px]">
- Start building with Composio.
+ <section className="py-10 sm:py-12">
+ <div className="flex max-w-[720px] flex-col gap-5">
+ <h1 className="text-4xl font-medium leading-[1.05] tracking-[-0.03em] text-fd-foreground sm:text-5xl">
+ Give agents the tools they need.
</h1>
- <p className="max-w-[480px] text-[15px] leading-[1.55] text-fd-foreground/70 md:text-base">
- Give your AI agent 1000+ pre-authenticated toolkits, per-user
- sessions, triggers, and a workbench.
+ <p className="max-w-[620px] text-base leading-[1.6] text-fd-foreground/70 sm:text-lg">
+ Use Composio to discover tools, authenticate each user, and run
+ actions across 1,000+ apps.
</p>
-
- {/* Quick-link chips — single column */}
- <div className="flex max-w-[360px] flex-col gap-2">
- {CHIPS.map(({ label, href, icon: Icon }) => (
- <Link
- key={href}
- className="flex items-center gap-2.5 rounded-md border border-fd-border bg-fd-card px-4 py-3 text-[15px] text-fd-foreground no-underline transition-colors hover:border-fd-foreground/15 hover:bg-fd-accent/40"
- href={href}
- >
- <Icon
- aria-hidden="true"
- className="size-4 text-[var(--composio-brand)]"
- />
- {label}
- </Link>
- ))}
- </div>
- </div>
-
- {/* Right — mock chat with floating "active tool" card.
- Hidden below lg: the layered animation is fiddly on small
- screens and the left column carries the welcome on its own. */}
- <div className="relative hidden lg:block lg:h-full">
- <DocsHeroV2Chat />
</div>
</section>
);
diff --git a/docs/components/docs-hero.tsx b/docs/components/docs-hero.tsx
index 7b2156f7b..1e1cb83af 100644
--- a/docs/components/docs-hero.tsx
+++ b/docs/components/docs-hero.tsx
@@ -11,7 +11,7 @@ import { DocsHeroV2 } from './docs-hero-v2';
*/
export function DocsHero() {
return (
- <div className="not-prose mb-10">
+ <div className="not-prose mb-2">
<DocsHeroV2 />
{/* <HeroSection /> */}
</div>
diff --git a/docs/components/home-features.tsx b/docs/components/home-features.tsx
index 1916fb38a..b669b0f76 100644
--- a/docs/components/home-features.tsx
+++ b/docs/components/home-features.tsx
@@ -298,9 +298,11 @@ function StaticCpuLights() {
export function SectionHeading({
eyebrow,
+ id,
title,
}: {
eyebrow: string;
+ id?: string;
title: string;
}) {
return (
@@ -308,7 +310,10 @@ export function SectionHeading({
<span className="font-mono text-[10.5px] uppercase tracking-[0.08em] text-fd-foreground/55">
{eyebrow}
</span>
- <h2 className="text-xl font-medium leading-[1.15] tracking-[-0.01em] text-fd-foreground sm:text-2xl">
+ <h2
+ className="text-xl font-medium leading-[1.15] tracking-[-0.01em] text-fd-foreground sm:text-2xl"
+ id={id}
+ >
{title}
</h2>
</div>
diff --git a/docs/components/home-surfaces.tsx b/docs/components/home-surfaces.tsx
index 1aab360fe..1d547dc1d 100644
--- a/docs/components/home-surfaces.tsx
+++ b/docs/components/home-surfaces.tsx
@@ -1,260 +1,124 @@
-'use client';
-
import Link from 'next/link';
-import Image from 'next/image';
-import {
- ArrowUpRight,
- Code2,
- Heart,
- Terminal,
- Copy,
- Check,
-} from 'lucide-react';
-import { useState, type ReactNode, type MouseEvent } from 'react';
+import { ArrowUpRight, Code2, Plug } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+import { HOME_INTENTS, homeIntentAnchor, type HomeIntent } from '@/lib/home-navigation';
import { SectionHeading } from './home-features';
-// Some provider logos ship a dedicated `-dark` variant (white-on-dark
-// or stroke-inverted). Use those in dark mode instead of inverting the
-// light SVG via CSS — `dark:invert` mangles full-colour logos
-// (Google's primary palette, LlamaIndex's gradient, CrewAI's brand).
-const PROVIDERS: { name: string; logo: string; logoDark?: string }[] = [
- {
- name: 'Anthropic',
- logo: '/images/providers/anthropic-logo.svg',
- logoDark: '/images/providers/anthropic-logo-dark.svg',
- },
- {
- name: 'OpenAI',
- logo: '/images/providers/openai-logo.svg',
- logoDark: '/images/providers/openai-logo-dark.svg',
- },
- {
- name: 'Vercel AI',
- logo: '/images/providers/vercel-logo.svg',
- logoDark: '/images/providers/vercel-logo-dark.svg',
- },
- { name: 'Google', logo: '/images/providers/google-logo.svg' },
- {
- name: 'LangChain',
- logo: '/images/providers/langchain-logo.svg',
- logoDark: '/images/providers/langchain-logo-dark.svg',
- },
- { name: 'CrewAI', logo: '/images/providers/crewai-logo.svg' },
- { name: 'LlamaIndex', logo: '/images/providers/llamaIndex-logo.svg' },
- {
- name: 'Mastra',
- logo: '/images/providers/mastra-logo.svg',
- logoDark: '/images/providers/mastra-logo-dark.svg',
- },
-];
-
-const CLIENTS: { name: string; logo: string; h: number }[] = [
- { name: 'Claude', logo: '/images/clients/claude.svg', h: 20 },
- { name: 'Codex', logo: '/images/clients/codex.png', h: 20 },
- { name: 'Cursor', logo: '/images/clients/cursor.svg', h: 20 },
- { name: 'Windsurf', logo: '/images/clients/windsurf.svg', h: 20 },
- { name: 'OpenClaw', logo: '/images/clients/openclaw.svg', h: 20 },
-];
+const INTENT_ICONS: Record<HomeIntent['id'], LucideIcon> = {
+ build: Code2,
+ use: Plug,
+};
-/**
- * Welcome-page audience selector — surfaces the three ways into Composio.
- * "Build with the SDK" gets the full width of the top row and a strip of
- * provider logos showing which frameworks ship first-class support; the
- * two non-developer surfaces (For You + CLI) sit below in a 2-col row.
- */
export function HomeSurfaces() {
return (
<section className="not-prose mb-14">
<SectionHeading
- eyebrow="For everyone"
- title="Three ways to use Composio."
+ eyebrow="Get started"
+ id="two-ways-to-start"
+ title="Two ways to start"
/>
<div className="grid grid-cols-1 gap-5 md:grid-cols-2">
- {/* Full-width Developers card */}
- <SurfaceCard
- eyebrow="Developers"
- eyebrowIcon={<Code2 aria-hidden="true" className="size-4" />}
- title="Build with the SDK"
- description="You're here. TypeScript or Python, with first-class providers for the frameworks you already use."
- href="/docs/quickstart"
- external={false}
- spanFull
- extra={<ProviderStrip />}
- />
- {/* Bottom row: For You + CLI */}
- <SurfaceCard
- eyebrow="For You"
- eyebrowIcon={<Heart aria-hidden="true" className="size-4" />}
- title="Use Composio yourself"
- description="Plug 1000+ pre-authenticated apps into Claude Code, Cursor, or any MCP client. No build required. Connect once and go."
- href="https://composio.dev/for-you"
- external
- extra={<ClientStrip />}
- />
- <SurfaceCard
- eyebrow="CLI"
- eyebrowIcon={<Terminal aria-hidden="true" className="size-4" />}
- title="Run Composio from your shell"
- description="Connect accounts, search tools, and execute them right from your terminal."
- href="/docs/cli"
- external={false}
- extra={<CliInstall />}
- />
+ {HOME_INTENTS.map(intent => (
+ <IntentCard key={intent.id} intent={intent} />
+ ))}
</div>
</section>
);
}
-function SurfaceCard({
- eyebrowIcon,
- eyebrow,
- title,
- description,
- href,
- external,
- spanFull,
- extra,
-}: {
- eyebrowIcon: ReactNode;
- eyebrow: string;
- title: string;
- description: string;
- href: string;
- external: boolean;
- spanFull?: boolean;
- extra?: ReactNode;
-}) {
- const externalProps = external
- ? { target: '_blank' as const, rel: 'noopener noreferrer' }
- : {};
+function IntentCard({ intent }: { intent: HomeIntent }) {
+ const Icon = INTENT_ICONS[intent.id];
+
return (
- <Link
- href={href}
- {...externalProps}
- className={
- 'group relative flex flex-col gap-3 overflow-hidden border border-fd-border bg-fd-card p-6 no-underline shadow-[0_1px_0_rgba(15,15,15,0.04)] transition-[box-shadow,transform,border-color] duration-200 hover:-translate-y-px hover:border-fd-foreground/15 hover:shadow-[0_10px_24px_-12px_rgba(15,15,15,0.18)] sm:p-7' +
- (spanFull ? ' md:col-span-2' : '')
- }
- >
- <div className="flex items-center justify-between">
- <span className="inline-flex items-center gap-1.5 font-mono text-[11px] uppercase tracking-[0.08em] text-[var(--composio-brand)]">
- {eyebrowIcon}
- {eyebrow}
- </span>
- <ArrowUpRight
- aria-hidden="true"
- className="size-3.5 text-fd-foreground/60 transition-transform group-hover:-translate-y-px group-hover:translate-x-px"
- />
+ <article className="flex flex-col border border-fd-border bg-fd-card p-5 shadow-[0_1px_0_rgba(15,15,15,0.04)] sm:p-6">
+ <AudienceBadge audience={intent.audience} />
+ <div className="mb-4 flex items-center gap-2 text-[var(--composio-brand)]">
+ <Icon aria-hidden="true" className="size-4" />
+ <h3
+ className="text-[18px] font-medium tracking-[-0.01em] text-fd-foreground"
+ id={homeIntentAnchor(intent.title)}
+ >
+ {intent.title}
+ </h3>
</div>
- <h3 className="text-[17px] font-medium leading-snug tracking-[-0.01em] text-fd-foreground sm:text-lg">
- {title}
- </h3>
- <p className="text-[14px] leading-[1.55] text-fd-foreground/70">
- {description}
+ <p className="mb-5 text-[14px] leading-[1.55] text-fd-foreground/70">
+ {intent.description}
</p>
- {extra}
- </Link>
+ <ul className="mt-auto flex flex-col gap-2">
+ {intent.links.map(link => (
+ <li key={link.href}>
+ <Link
+ className="group flex items-start justify-between gap-4 border border-fd-border bg-fd-background p-3.5 no-underline transition-[border-color,background-color] hover:border-fd-foreground/15 hover:bg-fd-accent/40"
+ href={link.href}
+ >
+ <span className="flex min-w-0 flex-col gap-0.5">
+ <span className="text-[14px] font-medium text-fd-foreground">
+ {link.title}
+ </span>
+ <span className="text-[12.5px] leading-[1.45] text-fd-foreground/65">
+ {link.description}
+ </span>
+ </span>
+ <ArrowUpRight
+ aria-hidden="true"
+ className="mt-0.5 size-3.5 shrink-0 text-fd-foreground/50 transition-transform group-hover:-translate-y-px group-hover:translate-x-px"
+ />
+ </Link>
+ </li>
+ ))}
+ </ul>
+ </article>
);
}
-const CLI_INSTALL_COMMAND = 'curl -fsSL https://composio.dev/install | sh';
-
-function CliInstall() {
- const [copied, setCopied] = useState(false);
-
- function handleCopy(e: MouseEvent<HTMLButtonElement>) {
- // The whole card is wrapped in a <Link> — keep this click from
- // navigating to /docs/cli.
- e.preventDefault();
- e.stopPropagation();
- navigator.clipboard.writeText(CLI_INSTALL_COMMAND).then(() => {
- setCopied(true);
- window.setTimeout(() => setCopied(false), 1500);
- });
- }
+const PLATFORM_BADGE_GRADIENT =
+ 'linear-gradient(135deg, #00e68a, #00b4d8, #0077ff)';
- return (
- <div className="mt-2 flex items-center gap-2 border border-fd-border bg-fd-background px-3 py-2 font-mono text-[12px]">
- <span className="shrink-0 text-fd-foreground/40">$</span>
- <code className="flex-1 truncate text-fd-foreground/85">
- {CLI_INSTALL_COMMAND}
- </code>
- <button
- aria-label={copied ? 'Copied' : 'Copy install command'}
- className="-mr-1 inline-flex size-6 shrink-0 items-center justify-center text-fd-foreground/55 transition-colors hover:text-fd-foreground"
- onClick={handleCopy}
- type="button"
- >
- {copied ? (
- <Check
- aria-hidden="true"
- className="size-3.5 text-[var(--composio-brand)]"
- />
- ) : (
- <Copy aria-hidden="true" className="size-3.5" />
- )}
- </button>
- </div>
- );
-}
+function AudienceBadge({ audience }: { audience: HomeIntent['audience'] }) {
+ const isPlatform = audience === 'Platform';
-function ClientStrip() {
return (
- <div className="mt-2 flex flex-wrap items-center gap-x-5 gap-y-3">
- {CLIENTS.map((c) => (
- <Image
- key={c.name}
- alt={c.name}
- className="object-contain"
- height={c.h}
- src={c.logo}
- style={{ height: c.h, width: 'auto' }}
- width={Math.ceil(c.h * 3.5)}
- />
- ))}
- </div>
- );
-}
-
-function ProviderStrip() {
- return (
- <div className="mt-2 flex flex-wrap items-center gap-3">
- {PROVIDERS.map((p) => (
- <div
- key={p.name}
- className="flex h-10 items-center justify-center gap-2 rounded-md border border-fd-border bg-fd-card px-3"
- title={p.name}
- >
- {p.logoDark ? (
- <>
- <Image
- alt={p.name}
- className="h-4 w-auto object-contain dark:hidden"
- height={16}
- src={p.logo}
- width={64}
- />
- <Image
- alt=""
- aria-hidden="true"
- className="hidden h-4 w-auto object-contain dark:block"
- height={16}
- src={p.logoDark}
- width={64}
- />
- </>
- ) : (
- <Image
- alt={p.name}
- className="h-4 w-auto object-contain"
- height={16}
- src={p.logo}
- width={64}
- />
- )}
- <span className="text-[12px] text-fd-foreground/75">{p.name}</span>
- </div>
- ))}
- </div>
+ <span
+ className={
+ 'relative mb-4 flex w-fit items-center rounded-[4px] px-[calc(0.25em+2px)] py-[calc(0.167em+2px)] font-mono text-[0.667em] font-semibold uppercase leading-none tracking-wide ' +
+ (isPlatform
+ ? 'audience-badge-platform'
+ : 'text-[#0007cd] dark:text-[#4d6fff]')
+ }
+ style={
+ isPlatform
+ ? {
+ background: PLATFORM_BADGE_GRADIENT,
+ backgroundClip: 'text',
+ WebkitBackgroundClip: 'text',
+ WebkitTextFillColor: 'transparent',
+ }
+ : undefined
+ }
+ >
+ <span
+ aria-hidden="true"
+ className={
+ 'pointer-events-none absolute inset-0 rounded-[4px] ' +
+ (isPlatform
+ ? 'audience-badge-platform-border'
+ : 'border border-[#0007cd] dark:border-[#4d6fff]')
+ }
+ style={
+ isPlatform
+ ? {
+ padding: '1px',
+ background: PLATFORM_BADGE_GRADIENT,
+ WebkitMask:
+ 'linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)',
+ WebkitMaskComposite: 'xor',
+ mask: 'linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)',
+ maskComposite: 'exclude',
+ }
+ : undefined
+ }
+ />
+ {audience}
+ </span>
);
}
diff --git a/docs/content/docs/agent-plugins.mdx b/docs/content/docs/agent-plugins.mdx
new file mode 100644
index 000000000..ccf005d4a
--- /dev/null
+++ b/docs/content/docs/agent-plugins.mdx
@@ -0,0 +1,95 @@
+---
+title: Agent plugins
+description: Install Composio for Codex or Claude Code
+keywords: [agent plugins, codex, claude code, cli, composio setup, skills]
+---
+
+Agent plugins let Codex and Claude Code use Composio from your current conversation. The plugin teaches your agent how to find tools, connect accounts, and run actions through the Composio CLI.
+
+## Install the plugin
+
+Install the Composio CLI:
+
+```bash
+curl -fsSL https://composio.dev/install | sh
+```
+
+Open a new terminal, sign in, and configure every supported agent on your machine:
+
+```bash
+composio login
+composio setup --target auto
+```
+
+`auto` detects Codex and Claude Code. If both are installed, it configures both.
+
+<Callout type="info" title="Running setup from an agent or script?">
+Setup asks before changing local files. Add `--yes` in a non-interactive shell: `composio setup --target auto --yes`.
+</Callout>
+
+## Try a task
+
+Ask Codex or Claude Code to work with one of your apps:
+
+- `List the open GitHub issues assigned to me.`
+- `Summarize the unread Gmail messages I received today.`
+- `Create a Linear issue from these release notes: ...`
+
+You do not need to know a tool slug or connection ID. The agent searches by task and selects a matching tool. If the toolkit is not connected, the agent starts `composio link` and gives you a Connect Link. Approve the connection, then ask the agent to continue.
+
+## Configure one agent
+
+Use an explicit target when you only want to configure one agent.
+
+### Codex
+
+```bash
+composio setup --target codex
+```
+
+The Codex plugin bundles the Composio CLI skill. You can also install the plugin with Codex directly:
+
+```bash
+codex plugin marketplace add https://github.com/ComposioHQ/composio-plugin-openai.git --json
+codex plugin add composio@composio --json
+```
+
+The plugin source is available in [`ComposioHQ/composio-plugin-openai`](https://github.com/ComposioHQ/composio-plugin-openai).
+
+### Claude Code
+
+```bash
+composio setup --target claude
+```
+
+You can also install the plugin from Claude Code:
+
+```bash
+/plugin marketplace add ComposioHQ/composio-plugin-cc
+/plugin install composio@composio
+```
+
+See the [Claude Code plugin guide](/docs/claude-code-plugin) for team installation, updates, and troubleshooting.
+
+## What the plugin uses
+
+Both plugins run the Composio CLI underneath. The agent uses `composio search` to find an unknown tool, `composio link` to connect an account, and `composio execute` to run a known tool. The same connections are available when you use the [CLI directly](/docs/cli).
+
+## Install only the CLI skill
+
+The plugin includes a Composio CLI skill that teaches your agent how to search for and run tools. Codex receives it with the plugin, while `composio login` installs it for Claude Code by default.
+
+If you want the skill without the plugin, install it for your agent directly:
+
+```bash
+composio --install-skill composio-cli claude
+composio --install-skill composio-cli codex
+```
+
+## Choose another setup
+
+<Cards>
+ <Card title="Build an agent" href="/docs/quickstart" description="Add Composio tools and authentication to your application." />
+ <Card title="Use the CLI" href="/docs/cli" description="Search, connect, and run tools from your terminal." />
+ <Card title="Connect over MCP" href="/docs/composio-connect" description="Add Composio to an existing MCP client." />
+</Cards>
diff --git a/docs/content/docs/auth-configuration/meta.json b/docs/content/docs/auth-configuration/meta.json
index 8c8d99ab8..90832e4b2 100644
--- a/docs/content/docs/auth-configuration/meta.json
+++ b/docs/content/docs/auth-configuration/meta.json
@@ -1,5 +1,5 @@
{
- "title": "Authentication",
+ "title": "Direct auth",
"defaultOpen": false,
"pages": [
"custom-auth-configs",
diff --git a/docs/content/docs/authentication.mdx b/docs/content/docs/authentication.mdx
index be760c5cf..4ddfc7d39 100644
--- a/docs/content/docs/authentication.mdx
+++ b/docs/content/docs/authentication.mdx
@@ -133,6 +133,15 @@ console.log(connectionRequest.redirectUrl);
</Tab>
</Tabs>
-## Next
-
-<Card icon={<ShieldCheck />} title="Manual auth management" href="/docs/manually-authenticating" description="Generate Connect Links yourself, check connection status, and disable in-chat prompts" />
+## Authentication guides
+
+<Cards>
+ <Card title="Manual auth management" href="/docs/manually-authenticating" description="Generate Connect Links yourself, check connection status, and disable in-chat prompts." />
+ <Card title="Multiple connected accounts" href="/docs/managing-multiple-connected-accounts" description="Let one user choose between work, personal, or other accounts." />
+ <Card title="Shared connections" href="/docs/shared-connections" description="Share one connected account with a controlled set of users." />
+ <Card title="Import existing connections" href="/docs/importing-existing-connections" description="Bring credentials your application already stores into Composio." />
+ <Card title="Managed vs custom auth" href="/docs/custom-app-vs-managed-app" description="Decide whether to use Composio credentials or your own OAuth app." />
+ <Card title="Programmatic auth configs" href="/docs/programmatic-auth-configs" description="Create auth configs in code and attach them to sessions." />
+ <Card title="Control OAuth scopes" href="/docs/controlling-scopes" description="Choose the permissions requested when a user connects." />
+ <Card title="White-label authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth app and remove Composio branding." />
+</Cards>
diff --git a/docs/content/docs/claude-code-plugin.mdx b/docs/content/docs/claude-code-plugin.mdx
index 296a15ad5..afb03c0b3 100644
--- a/docs/content/docs/claude-code-plugin.mdx
+++ b/docs/content/docs/claude-code-plugin.mdx
@@ -7,7 +7,7 @@ keywords: [claude code, plugin, marketplace, composio, oauth, cli, mcp]
The **Composio plugin for Claude Code** lets Claude act on 1,000+ apps — send the Slack message, open the Linear issue, check your calendar, draft the email. Your agent decides what to do; Composio handles the rest: OAuth, permissions, and finding the right tool for each task. No API keys, no config files.
<Callout type="info">
-Using Cursor, Codex, Claude Desktop, or another MCP client? See [Composio Connect](/docs/composio-connect).
+Using Codex? Follow the [Codex setup](/docs/agent-plugins#configure-one-agent). If you explicitly want MCP in Cursor, Claude Desktop, or another MCP client, use [Composio Connect](/docs/composio-connect).
</Callout>
## Install
diff --git a/docs/content/docs/cli.mdx b/docs/content/docs/cli.mdx
index e73314e21..c940c7a2b 100644
--- a/docs/content/docs/cli.mdx
+++ b/docs/content/docs/cli.mdx
@@ -1,12 +1,12 @@
---
title: Composio CLI
-description: Use the Composio CLI inside Claude Code for knowledge work, debugging, and developer workflows.
-keywords: [cli, claude code, command line, terminal, composio for you, knowledge work, dev commands]
+description: Use the Composio CLI from Codex, Claude Code, or your terminal for agent workflows and development.
+keywords: [cli, codex, claude code, command line, terminal, agent plugins, knowledge work, dev commands]
---
-The Composio CLI gives Claude Code a local tool surface. From your terminal, Claude can connect apps, execute tools, inspect schemas, call authenticated APIs, and debug Composio projects while it works with you. It's the command-line side of [Composio for You](https://composio.dev/for-you).
+The Composio CLI gives coding agents and terminals a local tool surface. Codex, Claude Code, or a person at the terminal can connect apps, execute tools, inspect schemas, call authenticated APIs, and debug Composio projects. It is also the runtime underneath the native [Composio agent plugins](/docs/agent-plugins).
-Reach for it when you want Claude to act in your connected apps directly, instead of pasting API keys, schemas, and one-off scripts into the chat.
+Reach for it when you want an agent to act in your connected apps directly, without building an SDK application or configuring MCP.
## Install
@@ -24,10 +24,23 @@ Open a new terminal, then log in:
composio login
```
-Open Claude Code in the project you want to work in. `composio login` installs the `composio-cli` skill for Claude Code by default. To install it manually:
+Install the native plugin for Codex or Claude Code:
+
+```bash
+composio setup --target auto
+```
+
+`auto` detects supported agents on your machine. Use `--target codex` or `--target claude` to configure only one. See [Agent plugins](/docs/agent-plugins) for manual plugin commands and host-specific details.
+
+Setup asks before changing local files. Add `--yes` when you run it from an agent, script, CI job, or another non-interactive shell.
+
+`composio login` installs the standalone `composio-cli` skill for Claude Code by default. For Codex, prefer `composio setup --target codex`; it installs the native plugin, which bundles the CLI skill.
+
+If you explicitly need the standalone skill without the native plugin, install it manually for the agent host:
```bash
composio --install-skill composio-cli claude
+composio --install-skill composio-cli codex
```
### Install with options
@@ -198,13 +211,13 @@ rm -rf "${COMPOSIO_INSTALL_DIR:-$HOME/.composio}"
```
</Callout>
-## Knowledge work in Claude Code
+## Agent and terminal workflows
-This is the recommended way to use Composio from inside Claude Code. The CLI executes tools, connects accounts, scripts workflows, calls authenticated APIs, and inspects trigger events, all without you wiring up a custom integration first.
+The CLI executes tools, connects accounts, scripts workflows, calls authenticated APIs, and inspects trigger events without you wiring up a custom integration first. Native Codex and Claude Code plugins expose these capabilities to the agent; the same commands work directly in your terminal.
### Search, connect, and execute tools
-Use this flow when Claude needs to act in one of your connected apps:
+Use this flow when you or your agent needs to act in one of your connected apps:
```bash
# Find the right tool
@@ -230,7 +243,7 @@ The commands you'll reach for most:
| `composio link` | Connect an app account |
| `composio proxy` | Call provider APIs with Composio-managed auth |
-Use `composio proxy` when Claude already knows the provider's API endpoint and just needs Composio to inject auth from your connected account:
+Use `composio proxy` when the agent already knows the provider's API endpoint and just needs Composio to inject auth from your connected account:
```bash
composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit gmail
@@ -238,7 +251,7 @@ composio proxy https://gmail.googleapis.com/gmail/v1/users/me/profile --toolkit
### Run scripts and sub-agents
-Reach for `composio run` when Claude needs a multi-step workflow: loops, parallel fan-out, data transformation, or LLM-assisted summarization. It runs inline TS/JS or a file, with `execute()`, `search()`, `proxy()`, `experimental_subAgent()`, `result.prompt()`, and `z` injected.
+Reach for `composio run` when the agent needs a multi-step workflow: loops, parallel fan-out, data transformation, or LLM-assisted summarization. It runs inline TS/JS or a file, with `execute()`, `search()`, `proxy()`, `experimental_subAgent()`, `result.prompt()`, and `z` injected.
Run a single scripted workflow:
@@ -297,7 +310,7 @@ composio run --file ./workflow.ts -- --repo composiohq/composio
### Listen to trigger events
-Use trigger listening when Claude needs to wait for new events, inspect incoming payloads, or forward events while debugging. Event streaming lives in the developer namespace:
+Use trigger listening when the agent needs to wait for new events, inspect incoming payloads, or forward events while debugging. Event streaming lives in the developer namespace:
```bash
# Compact table view for matching events
@@ -309,7 +322,7 @@ composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5
# Forward each matching event to a local or hosted webhook
composio dev listen --toolkits github --forward https://example.com/webhook
-# Append matching events to a local file for Claude to inspect
+# Append matching events to a local file for an agent to inspect
composio dev listen --toolkits slack --out ./events.jsonl
```
diff --git a/docs/content/docs/composio-connect.mdx b/docs/content/docs/composio-connect.mdx
index d9f0070a6..dc366b6f9 100644
--- a/docs/content/docs/composio-connect.mdx
+++ b/docs/content/docs/composio-connect.mdx
@@ -1,14 +1,18 @@
---
title: Composio Connect
-description: Add Composio tools to your AI agent via MCP
+description: Connect Composio to an existing MCP client without using the SDK
keywords: [composio connect, mcp, claude code, cursor, vscode, windsurf, cline, chatgpt, notion, n8n, codex]
---
-Give any AI agent the ability to act across 1000+ apps. Bring your agent to where you work.
+Use Composio Connect when you already have an MCP-compatible client and want the shared Composio MCP URL, without creating an SDK session. Connect it to `https://connect.composio.dev/mcp`.
+
+If you use Codex or Claude Code and did not explicitly choose MCP, install the native [Composio agent plugin](/docs/agent-plugins) instead. The plugin uses the Composio CLI and is the shortest path for those agents.
+
+If you are building an application, start with the [SDK Quickstart](/docs/quickstart) or create a [session MCP endpoint](/docs/sessions-via-mcp) instead.
## How Composio Connect works
-Composio Connect is an MCP server at `https://connect.composio.dev/mcp` that gives your AI agent access to 1000+ apps — Gmail, Notion, Slack, GitHub, Linear, HubSpot, Strava, and more — through a single connection.
+Composio Connect is an MCP server at `https://connect.composio.dev/mcp` that gives your AI agent access to 1000+ apps, including Gmail, Notion, Slack, GitHub, Linear, HubSpot, and Strava, through a single connection.
Rather than exposing every app tool directly, Composio exposes **7 meta-tools** that let the agent discover what's available, authorize apps on demand, and execute tools across apps in parallel. The first time your agent needs an app, Composio generates an OAuth link you approve in your browser; after that the connection persists across sessions. See [Available MCP tools](#available-mcp-tools) for the full list.
diff --git a/docs/content/docs/extending-sessions/meta.json b/docs/content/docs/extending-sessions/meta.json
index 228feedd0..68cd6f562 100644
--- a/docs/content/docs/extending-sessions/meta.json
+++ b/docs/content/docs/extending-sessions/meta.json
@@ -1,6 +1,6 @@
{
- "title": "Extending sessions capabilities",
- "defaultOpen": true,
+ "title": "Extend sessions",
+ "defaultOpen": false,
"pages": [
"proxy-execute",
"custom-tools-and-toolkits",
diff --git a/docs/content/docs/index.mdx b/docs/content/docs/index.mdx
index c632e5178..f84022d2c 100644
--- a/docs/content/docs/index.mdx
+++ b/docs/content/docs/index.mdx
@@ -1,13 +1,13 @@
---
title: Welcome
-description: Give your AI agent 1000+ pre-authenticated toolkits, per-user sessions, authentication, triggers, and a sandbox, so you can ship agents that turn intent into action.
+description: Choose whether to build Composio into an application or use it from an existing agent, then start with the SDK, a native plugin, the CLI, or MCP.
keywords: [getting started, introduction]
---
<DocsHero />
-<HomeFeatures />
-
<HomeSurfaces />
+<HomeFeatures />
+
<HomeResources />
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index 05214a485..878f6297b 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -4,38 +4,25 @@
"index",
"quickstart",
"providers",
- "---Customizing sessions---",
+ "agent-plugins",
+ "cli",
+ "composio-connect",
+ "---Core concepts---",
"how-composio-works",
"configuring-sessions",
+ "authentication",
+ "triggers",
+ "---Guides---",
"sessions-via-mcp",
"sandbox",
"extending-sessions",
- "---Authenticate users---",
- "authentication",
- "manually-authenticating",
- "managing-multiple-connected-accounts",
- "shared-connections",
- "importing-existing-connections",
- "---Customizing auth---",
- "custom-app-vs-managed-app",
- "programmatic-auth-configs",
- "controlling-scopes",
- "white-labeling-authentication",
- "---Triggers---",
- "triggers",
- "setting-up-triggers/creating-triggers",
- "setting-up-triggers/subscribing-to-events",
- "setting-up-triggers/managing-triggers",
- "setting-up-triggers/custom-oauth-webhooks",
- "---Security and Data---",
- "security/overview",
- "security/data-retention",
- "---Direct Tool Execution Guides (Legacy)---",
+ "setting-up-triggers",
+ "---Direct execution (legacy)---",
"sessions-vs-direct-execution",
"tools-direct",
"auth-configuration",
- "---Other topics---",
- "cli",
- "migration-guide"
+ "---Migration and security---",
+ "migration-guide",
+ "security"
]
}
diff --git a/docs/content/docs/migration-guide/meta.json b/docs/content/docs/migration-guide/meta.json
index abaf3c3c2..1407bc8db 100644
--- a/docs/content/docs/migration-guide/meta.json
+++ b/docs/content/docs/migration-guide/meta.json
@@ -1,5 +1,5 @@
{
- "title": "Migration Guide",
+ "title": "Migration guides",
"pages": [
"direct-to-sessions",
"mcp-servers-to-sessions",
diff --git a/docs/content/docs/providers/custom-providers/meta.json b/docs/content/docs/providers/custom-providers/meta.json
index 74d463bb3..a6fab90e8 100644
--- a/docs/content/docs/providers/custom-providers/meta.json
+++ b/docs/content/docs/providers/custom-providers/meta.json
@@ -1,5 +1,5 @@
{
- "title": "Custom Providers",
+ "title": "Custom providers",
"pages": [
"typescript",
"python"
diff --git a/docs/content/docs/providers/index.mdx b/docs/content/docs/providers/index.mdx
index 28e359ce5..9c16665a1 100644
--- a/docs/content/docs/providers/index.mdx
+++ b/docs/content/docs/providers/index.mdx
@@ -1,5 +1,5 @@
---
-title: Providers
+title: SDKs and frameworks
description: Composio works with any AI framework. Pick your preferred SDK to get started.
---
@@ -7,6 +7,10 @@ Composio works with any AI framework. A provider is the adapter that turns Compo
Pick the provider that matches the SDK or agent framework you already use. Each one fetches tools, handles execution, and hands your agent objects it understands. If your framework isn't listed, you can [build your own provider](/docs/providers/custom-providers).
+<Callout type="info" title="Using TypeScript?">
+The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` instead of CommonJS `require()`.
+</Callout>
+
## AI SDKs
Use these when you call a model SDK directly.
diff --git a/docs/content/docs/providers/meta.json b/docs/content/docs/providers/meta.json
index 0fa6323fa..8f157b9de 100644
--- a/docs/content/docs/providers/meta.json
+++ b/docs/content/docs/providers/meta.json
@@ -1,7 +1,6 @@
{
- "title": "Providers",
+ "title": "SDKs and frameworks",
"pages": [
- "...",
"anthropic",
"openai",
"vercel",
@@ -13,6 +12,7 @@
"crewai",
"llamaindex",
"mastra",
- "custom-providers"
+ "custom-providers",
+ "..."
]
}
diff --git a/docs/content/docs/quickstart.mdx b/docs/content/docs/quickstart.mdx
index 17c4d2b9d..8cb42840f 100644
--- a/docs/content/docs/quickstart.mdx
+++ b/docs/content/docs/quickstart.mdx
@@ -1,443 +1,154 @@
---
title: Quickstart
-description: Build an AI agent with access to 1000+ tools
-keywords: [tutorial, setup, first agent]
+description: Build a Python agent that discovers and runs Composio tools
+keywords: [tutorial, setup, first agent, python, openai agents, sessions, tool router]
---
-Build your first AI agent with Composio Tools. You'll create a [session](/docs/how-composio-works) for a user, give your agent access to [tools](/docs/how-composio-works), and let it take action across [1000+ apps](/toolkits).
+Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.
-<Callout type="info">
-The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.
-</Callout>
+This example uses Python and OpenAI Agents. A Composio session gives the agent tool discovery, account connections, and execution. It exposes only a small set of meta tools, so app schemas are loaded when needed. You can use the same pattern with any [supported provider or framework](/docs/providers).
-<QuickstartFlow>
+## Prerequisites
-<FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">
+You need:
-<Steps>
-<Step>
-<StepTitle>Install</StepTitle>
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-The Composio Python SDK requires **Python 3.10 or newer**.
-
-<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
-</Tab>
-<Tab value="TypeScript">
-<PackageInstall
- packages="@composio/core @composio/openai-agents @openai/agents"
- comment={[
- '@composio/core ships its docs and TypeScript source in the package,',
- 'so it is inspectable to coding agents.',
- 'Use @composio/slim for a smaller install with the same API.',
- ]}
-/>
-</Tab>
-</Tabs>
-</Step>
+- [`uv`](https://docs.astral.sh/uv/) to create the Python project and install its dependencies.
+- A `COMPOSIO_API_KEY` from [Composio Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart).
+- An `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
+
+## Build the agent
+<Steps>
<Step>
-<StepTitle>Configure API Keys</StepTitle>
+<StepTitle>Create the project</StepTitle>
-<Callout type="info">
-Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
-</Callout>
+Create a Python 3.10 project and enter its directory:
-```bash title=".env"
-COMPOSIO_API_KEY=your_composio_api_key
-OPENAI_API_KEY=your_openai_api_key
+```bash
+uv init --app --python 3.10 composio-quickstart
+cd composio-quickstart
```
-</Step>
+</Step>
<Step>
-<StepTitle>Create session and run agent</StepTitle>
+<StepTitle>Install the packages</StepTitle>
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-from dotenv import load_dotenv
-from composio import Composio
-from agents import Agent, Runner, SQLiteSession
-from composio_openai_agents import OpenAIAgentsProvider
-
-load_dotenv()
-
-# Initialize Composio with OpenAI Agents provider
-composio = Composio(provider=OpenAIAgentsProvider())
-
-# Create a session for your user
-user_id = "user_123"
-session = composio.sessions.create(user_id=user_id)
-tools = session.tools()
-
-# For multi-turn, store the session ID in your db and reuse instead of creating another session:
-# session_id = session.session_id
-# session = composio.use(session_id)
-
-agent = Agent(
- name="Personal Assistant",
- instructions="You are a helpful personal assistant. Use Composio tools to take action.",
- model="gpt-5.2",
- tools=tools,
-)
-
-# Memory for multi-turn conversation
-memory = SQLiteSession("conversation")
-
-print("""
-What task would you like me to help you with?
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
-(Type 'exit' to exit)
-Example tasks:
- - 'Summarize my emails from today'
- - 'List all open issues on the composio github repository'
-""")
-
-while True:
- user_input = input("You: ").strip()
- if user_input.lower() == "exit":
- break
-
- print("Assistant: ", end="", flush=True)
- result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
- print(f"{result.final_output}\n")
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import "dotenv/config";
-import { Composio } from "@composio/core";
-import { Agent, run, MemorySession } from "@openai/agents";
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
-import { createInterface } from "readline/promises";
-
-// Initialize Composio with OpenAI Agents provider
-const composio = new Composio({ provider: new OpenAIAgentsProvider() });
-
-// Create a session for your user
-const userId = "user_123";
-const session = await composio.create(userId);
-const tools = await session.tools();
-
-// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
-// const sessionId = session.sessionId;
-// const session = await composio.use(sessionId);
-
-const agent = new Agent({
- name: "Personal Assistant",
- instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
- model: "gpt-5.2",
- tools,
-});
-
-const memory = new MemorySession();
-const readline = createInterface({ input: process.stdin, output: process.stdout });
-
-console.log(`
-What task would you like me to help you with?
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
-(Type 'exit' to exit)
-Example tasks:
- - 'Summarize my emails from today'
- - 'List all open issues on the composio github repository'
-`);
-
-while (true) {
- const input = (await readline.question("You: ")).trim();
- if (input.toLowerCase() === "exit") break;
-
- process.stdout.write("Assistant: ");
- const result = await run(agent, input, { session: memory });
- process.stdout.write(`${result.finalOutput}\n`);
-}
-readline.close();
+```bash
+uv add python-dotenv composio composio-openai-agents openai-agents
```
-</Tab>
-</Tabs>
-</Step>
-</Steps>
-
-</FrameworkOption>
-
-<FrameworkOption id="claude-agents" name="Claude Agent SDK" logo="/images/providers/anthropic-logo.svg" logoDark="/images/providers/anthropic-logo-dark.svg">
-<Steps>
-<Step>
-<StepTitle>Install</StepTitle>
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-<PackageInstall ecosystem="python" packages="python-dotenv composio composio-claude-agent-sdk claude-agent-sdk" />
-</Tab>
-<Tab value="TypeScript">
-<PackageInstall
- packages="dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk"
- comment={[
- '@composio/core ships its docs and TypeScript source in the package,',
- 'so it is inspectable to coding agents.',
- 'Use @composio/slim for a smaller install with the same API.',
- ]}
-/>
-</Tab>
-</Tabs>
</Step>
-
<Step>
-<StepTitle>Configure API Keys</StepTitle>
+<StepTitle>Set your API keys</StepTitle>
-<Callout type="info">
-Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
-</Callout>
+Create a `.env` file in the project root:
```bash title=".env"
COMPOSIO_API_KEY=your_composio_api_key
-ANTHROPIC_API_KEY=your_anthropic_api_key
+OPENAI_API_KEY=your_openai_api_key
+```
+
+Keep `.env` out of source control:
+
+```bash
+echo ".env" >> .gitignore
```
-</Step>
+</Step>
<Step>
-<StepTitle>Create session and run agent</StepTitle>
+<StepTitle>Add the agent</StepTitle>
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
-<Tab value="Python">
-```python
-import asyncio
-from dotenv import load_dotenv
+Replace `main.py` with this complete program:
+
+```python title="main.py"
+import sys
+
+from agents import Agent, Runner, SQLiteSession
from composio import Composio
-from composio_claude_agent_sdk import ClaudeAgentSDKProvider
-from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, create_sdk_mcp_server, AssistantMessage, TextBlock
+from composio_openai_agents import OpenAIAgentsProvider
+from dotenv import load_dotenv
load_dotenv()
-# Initialize Composio with Claude Agent SDK provider
-composio = Composio(provider=ClaudeAgentSDKProvider())
-
-# Create a session for your user
-user_id = "user_123"
-session = composio.sessions.create(user_id=user_id)
-tools = session.tools()
+composio = Composio(provider=OpenAIAgentsProvider())
+session = composio.sessions.create(user_id="quickstart-user")
-# For multi-turn, store the session ID in your db and reuse instead of creating another session:
-# session_id = session.session_id
-# session = composio.use(session_id)
+agent = Agent(
+ name="Composio assistant",
+ instructions=(
+ "Use Composio tools to complete the request. "
+ "If a connection is required, share its Connect Link and wait. "
+ "Ask for confirmation before creating, updating, or deleting data."
+ ),
+ tools=session.tools(),
+)
-custom_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
+conversation = SQLiteSession("quickstart-conversation")
-async def main():
- options = ClaudeAgentOptions(
- system_prompt="You are a helpful assistant. Use tools to complete tasks.",
- permission_mode="bypassPermissions",
- mcp_servers={"composio": custom_server},
+def run_task(task: str) -> None:
+ result = Runner.run_sync(
+ starting_agent=agent,
+ input=task,
+ session=conversation,
)
-
- async with ClaudeSDKClient(options=options) as client:
- print("""
-What task would you like me to help you with?
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
-(Type 'exit' to exit)
-Example tasks:
- - 'Summarize my emails from today'
- - 'List all open issues on the composio github repository'
-""")
-
- while True:
- user_input = input("You: ").strip()
- if user_input.lower() == "exit":
- break
-
- await client.query(user_input)
- print("Claude: ", end="", flush=True)
- async for message in client.receive_response():
- if isinstance(message, AssistantMessage):
- for block in message.content:
- if isinstance(block, TextBlock):
- print(block.text, end="", flush=True)
- print()
-
-asyncio.run(main())
-```
-</Tab>
-<Tab value="TypeScript">
-```typescript
-import "dotenv/config";
-import { Composio } from "@composio/core";
-import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
-import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
-import { createInterface } from "readline/promises";
-
-// Initialize Composio with Claude Agent SDK provider
-const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
-
-// Create a session for your user
-const userId = "user_123";
-const session = await composio.create(userId);
-const tools = await session.tools();
-
-// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
-// const sessionId = session.sessionId;
-// const session = await composio.use(sessionId);
-
-const customServer = createSdkMcpServer({
- name: "composio",
- version: "1.0.0",
- tools: tools,
-});
-
-const readline = createInterface({ input: process.stdin, output: process.stdout });
-
-console.log(`
-What task would you like me to help you with?
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
-(Type 'exit' to exit)
-Example tasks:
- - 'Summarize my emails from today'
- - 'List all open issues on the composio github repository and create a Google Sheet with the issues'
-`);
-
-let isFirstQuery = true;
-const options = {
- mcpServers: { composio: customServer },
- permissionMode: "bypassPermissions" as const,
-};
-
-while (true) {
- const input = (await readline.question("You: ")).trim();
- if (input.toLowerCase() === "exit") break;
-
- const queryOptions = isFirstQuery ? options : { ...options, continue: true };
- isFirstQuery = false;
-
- process.stdout.write("Claude: ");
- for await (const stream of query({ prompt: input, options: queryOptions })) {
- if (stream.type === "assistant") {
- for (const block of stream.message.content) {
- if (block.type === "text") {
- process.stdout.write(block.text);
- }
- }
- }
- }
- console.log();
-}
-
-readline.close();
+ print(f"Assistant: {result.final_output}\n")
+
+if len(sys.argv) > 1:
+ run_task(" ".join(sys.argv[1:]))
+else:
+ print("Ask me to work with your apps. Type 'exit' to quit.")
+ while True:
+ task = input("You: ").strip()
+ if task.lower() == "exit":
+ break
+ if task:
+ run_task(task)
```
-</Tab>
-</Tabs>
+
</Step>
-</Steps>
+<Step>
+<StepTitle>Run it</StepTitle>
-</FrameworkOption>
+```bash
+uv run main.py
+```
-<FrameworkOption id="vercel-ai" name="Vercel AI SDK" logo="/images/providers/vercel-logo.svg" logoDark="/images/providers/vercel-logo-dark.svg">
+To run one task without an interactive prompt, pass it as an argument:
-<Steps>
-<Step>
-<StepTitle>Install</StepTitle>
-
-<PackageInstall
- packages="@composio/core @composio/vercel ai @ai-sdk/anthropic"
- comment={[
- '@composio/core ships its docs and TypeScript source in the package,',
- 'so it is inspectable to coding agents.',
- 'Use @composio/slim for a smaller install with the same API.',
- ]}
-/>
-</Step>
+```bash
+uv run main.py "Find the three most recent open issues in composiohq/composio"
+```
-<Step>
-<StepTitle>Configure API Keys</StepTitle>
+Enter any task that needs an app tool. For example:
-<Callout type="info">
-Get your `COMPOSIO_API_KEY` from [Settings](https://dashboard.composio.dev/~/project/settings/api-keys?utm_source=docs&utm_medium=content&utm_campaign=docs-quickstart) and `ANTHROPIC_API_KEY` from [Anthropic](https://console.anthropic.com/settings/keys).
-</Callout>
+- `Find the three most recent open issues in a public GitHub repository.`
+- `Summarize my unread emails from today.`
+- `Turn these release notes into a Linear issue: ...`
-```bash title=".env"
-COMPOSIO_API_KEY=your_composio_api_key
-ANTHROPIC_API_KEY=your_anthropic_api_key
-```
-</Step>
+These are examples, not a sequence. If a task needs access to an account, the agent gives you a Connect Link. Open it, approve the connection, and tell the agent to continue.
-<Step>
-<StepTitle>Create session and run agent</StepTitle>
-
-```typescript
-import "dotenv/config";
-import { anthropic } from "@ai-sdk/anthropic";
-import { Composio } from "@composio/core";
-import { VercelProvider } from "@composio/vercel";
-import { streamText, stepCountIs, type ModelMessage } from "ai";
-import { createInterface } from "readline/promises";
-
-// Initialize Composio with Vercel provider
-const composio = new Composio({ provider: new VercelProvider() });
-
-// Create a session for your user
-const userId = "user_123";
-const session = await composio.create(userId);
-const tools = await session.tools();
-
-// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
-// const sessionId = session.sessionId;
-// const session = await composio.use(sessionId);
-
-const readline = createInterface({ input: process.stdin, output: process.stdout });
-
-console.log(`
-What task would you like me to help you with?
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
-(Type 'exit' to exit)
-Example tasks:
- - 'Summarize my emails from today'
- - 'List all open issues on the composio github repository'
-`);
-
-const messages: ModelMessage[] = [];
-
-while (true) {
- const input = (await readline.question("You: ")).trim();
- if (input.toLowerCase() === "exit") break;
-
- messages.push({ role: "user", content: input });
- process.stdout.write("Assistant: ");
-
- const result = await streamText({
- system: "You are a helpful personal assistant. Use Composio tools to take action.",
- model: anthropic("claude-sonnet-4-6"),
- messages,
- stopWhen: stepCountIs(10),
- onStepFinish: (step) => {
- for (const toolCall of step.toolCalls) {
- process.stdout.write(`\n[Using tool: ${toolCall.toolName}]`);
- }
- },
- tools,
- });
-
- for await (const textPart of result.textStream) {
- process.stdout.write(textPart);
- }
- console.log();
-
- messages.push(...(await result.response).messages);
-}
-
-readline.close();
-```
</Step>
</Steps>
-</FrameworkOption>
+## What just happened?
-</QuickstartFlow>
+- `OpenAIAgentsProvider` formats Composio tools for OpenAI Agents.
+- `composio.sessions.create()` creates a Composio session for `quickstart-user`. The session scopes connections and tool calls to that ID.
+- Composio sessions persist. In an application, store `session.session_id` and restore it with `composio.use(session_id)` instead of creating a new session for every turn. See [Reusing a session](/docs/how-composio-works#how-sessions-behave).
+- `session.tools()` gives the agent a small set of meta tools for finding, connecting, and running app tools. It does not load thousands of tool schemas into the model context.
+- `SQLiteSession` stores the OpenAI conversation history on disk. It is separate from the Composio session.
-By default, each `composio.sessions.create()` call returns a new session with access to all toolkits. Sessions are highly configurable beyond that: [Reusing a session](/docs/how-composio-works#how-sessions-behave) covers storing a session ID and calling `composio.use()` across multi-turn requests, while [Configuring Sessions](/docs/configuring-sessions) covers restricting toolkits, auth configs, and connected accounts.
+<Callout type="warn" title="Use your application's user ID in production">
+`quickstart-user` is only for this local example. Replace it with a stable ID from your database. Each ID gets separate connections and tool calls.
+</Callout>
-Prefer to connect over the Model Context Protocol instead? Every session also exposes an MCP endpoint. See [Using sessions via MCP](/docs/sessions-via-mcp).
+You can inspect the selected tools, inputs, responses, and timing with the [Logs API](/reference/api-reference/logs).
-## Next
+## Adapt the example
-<Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions">
- Restrict toolkits, set custom auth configs, and select connected accounts
-</Card>
+<Cards>
+ <Card title="Use another framework" href="/docs/providers" description="Choose OpenAI, Anthropic, Vercel AI SDK, LangChain, CrewAI, or another supported provider." />
+ <Card title="Configure the session" href="/docs/configuring-sessions" description="Restrict toolkits, preload tools, or select connected accounts." />
+ <Card title="Design authentication" href="/docs/authentication" description="Add Connect Links and per-user connections to your application." />
+ <Card title="Expose an MCP endpoint" href="/docs/sessions-via-mcp" description="Use the same Composio session from an MCP-compatible application." />
+</Cards>
diff --git a/docs/content/docs/sandbox/meta.json b/docs/content/docs/sandbox/meta.json
index 4dbe95a80..574f47c9b 100644
--- a/docs/content/docs/sandbox/meta.json
+++ b/docs/content/docs/sandbox/meta.json
@@ -1,6 +1,6 @@
{
- "title": "Sandbox (prev Workbench)",
- "defaultOpen": true,
+ "title": "Sandboxes",
+ "defaultOpen": false,
"pages": [
"remote",
"local"
diff --git a/docs/content/docs/security/meta.json b/docs/content/docs/security/meta.json
new file mode 100644
index 000000000..8e6c17211
--- /dev/null
+++ b/docs/content/docs/security/meta.json
@@ -0,0 +1,8 @@
+{
+ "title": "Security and data",
+ "defaultOpen": false,
+ "pages": [
+ "overview",
+ "data-retention"
+ ]
+}
diff --git a/docs/content/docs/sessions-via-mcp.mdx b/docs/content/docs/sessions-via-mcp.mdx
index 182dab4dd..b173942e1 100644
--- a/docs/content/docs/sessions-via-mcp.mdx
+++ b/docs/content/docs/sessions-via-mcp.mdx
@@ -1,12 +1,16 @@
---
title: Using sessions via MCP
-description: Connect any MCP-compatible client to a Composio session
+description: Build an application that exposes a Composio session to an MCP-compatible client
keywords: [mcp, model context protocol, sessions, remote server, hosted mcp]
---
-By default Composio gives your agent **tools it can call directly**. Composio formats them as function schemas for your framework through a [provider package](/docs/providers). That's what the [Quickstart](/docs/quickstart) uses, and it's the right choice for most agents.
+Use this guide when you are building an application with Composio and want to expose one user's session over MCP. The application creates and configures the session, then passes its hosted MCP endpoint to a compatible client.
-If you'd rather connect over the [Model Context Protocol](https://modelcontextprotocol.io), every session also exposes a hosted MCP endpoint. This is useful when you want to plug a session into an MCP-native client like Claude Desktop, Cursor, or any framework's MCP transport. No provider package required.
+By default, Composio gives your agent tools it can call directly through a [provider package](/docs/providers). That is what the [Quickstart](/docs/quickstart) uses. Set `mcp: true` when an MCP transport fits your application better. No provider package is required for this route.
+
+<Callout type="info" title="Connecting an existing agent instead?">
+If you use Codex or Claude Code and did not explicitly choose MCP, install the native [Composio agent plugin](/docs/agent-plugins). If you explicitly want MCP in an existing client, use [Composio Connect](/docs/composio-connect).
+</Callout>
<Callout type="info">
Want to bring tools from your own remote MCP server into Composio instead? See [Custom MCP](/docs/extending-sessions/custom-mcp).
diff --git a/docs/content/docs/setting-up-triggers/meta.json b/docs/content/docs/setting-up-triggers/meta.json
index b17c62a47..d246203bb 100644
--- a/docs/content/docs/setting-up-triggers/meta.json
+++ b/docs/content/docs/setting-up-triggers/meta.json
@@ -1,5 +1,5 @@
{
- "title": "Setting up triggers",
+ "title": "Set up triggers",
"pages": [
"creating-triggers",
"subscribing-to-events",
diff --git a/docs/content/docs/tools-direct/executing-tools.mdx b/docs/content/docs/tools-direct/executing-tools.mdx
index f74971c6c..35fd26f74 100644
--- a/docs/content/docs/tools-direct/executing-tools.mdx
+++ b/docs/content/docs/tools-direct/executing-tools.mdx
@@ -1,6 +1,6 @@
---
-title: Executing Tools
-description: Learn how to execute Composio tools with different providers and frameworks
+title: Executing tools directly
+description: Maintain legacy code that calls composio.tools.execute() and other direct tool APIs
keywords: [execute, run, tool calling, function calling, direct execution]
llmGuardrails: "direct-execution"
legacy: true
diff --git a/docs/content/docs/tools-direct/meta.json b/docs/content/docs/tools-direct/meta.json
index 52ef02b22..359b8d15f 100644
--- a/docs/content/docs/tools-direct/meta.json
+++ b/docs/content/docs/tools-direct/meta.json
@@ -1,5 +1,5 @@
{
- "title": "Tools",
+ "title": "Direct execution",
"defaultOpen": false,
"pages": [
"fetching-tools",
diff --git a/docs/lib/home-navigation.ts b/docs/lib/home-navigation.ts
new file mode 100644
index 000000000..9ea06ed8f
--- /dev/null
+++ b/docs/lib/home-navigation.ts
@@ -0,0 +1,82 @@
+export interface HomeIntentLink {
+ title: string;
+ description: string;
+ href: string;
+}
+
+export interface HomeIntent {
+ id: 'build' | 'use';
+ audience: 'For you' | 'Platform';
+ title: string;
+ description: string;
+ links: HomeIntentLink[];
+}
+
+export const HOME_INTENTS: HomeIntent[] = [
+ {
+ id: 'build',
+ audience: 'Platform',
+ title: 'Build with Composio',
+ description: 'Add Composio tools and authentication to your own agent or application.',
+ links: [
+ {
+ title: 'Quickstart',
+ description: 'Build an agent that discovers tools and works across your apps.',
+ href: '/docs/quickstart',
+ },
+ {
+ title: 'Framework guides',
+ description: 'Use OpenAI, Anthropic, Vercel AI SDK, or another framework.',
+ href: '/docs/providers',
+ },
+ {
+ title: 'Sessions via MCP',
+ description: 'Expose a Composio session through a hosted MCP endpoint.',
+ href: '/docs/sessions-via-mcp',
+ },
+ ],
+ },
+ {
+ id: 'use',
+ audience: 'For you',
+ title: 'Use Composio',
+ description: 'Connect an existing coding agent or terminal to Composio.',
+ links: [
+ {
+ title: 'Agent plugins',
+ description: 'Install the native Composio plugin for Codex or Claude Code.',
+ href: '/docs/agent-plugins',
+ },
+ {
+ title: 'Composio CLI',
+ description: 'Search, connect, and run tools from your terminal.',
+ href: '/docs/cli',
+ },
+ {
+ title: 'Connect over MCP',
+ description: 'Use Composio with Cursor or another existing MCP client.',
+ href: '/docs/composio-connect',
+ },
+ ],
+ },
+];
+
+export function homeIntentAnchor(title: string): string {
+ return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
+}
+
+export function homeIntentsToMarkdown(): string {
+ const sections = HOME_INTENTS.map(intent => {
+ const links = intent.links
+ .map(link => `- [${link.title}](${link.href}): ${link.description}`)
+ .join('\n');
+
+ return `### ${intent.title}\n\n**${intent.audience}**\n\n${intent.description}\n\n${links}`;
+ }).join('\n\n');
+
+ return `## Two ways to start\n\n${sections}`;
+}
+
+export function replaceHomeNavigationMarkdown(content: string): string {
+ return content.replace(/<HomeSurfaces\s*\/>/g, homeIntentsToMarkdown());
+}
diff --git a/docs/lib/source.ts b/docs/lib/source.ts
index 21dfeee9a..74aab62e0 100644
--- a/docs/lib/source.ts
+++ b/docs/lib/source.ts
@@ -11,6 +11,7 @@ import { transformDeprecatedApiSidebarNode } from './deprecated-api-sidebar';
import { API_BASE_URLS, detectApiVersion, type ApiVersion } from './api-version';
import { apiVersionPointer } from './api-version-guidance';
import { apiEndpointsSchema } from './api-endpoints-table-schema';
+import { replaceHomeNavigationMarkdown } from './home-navigation';
/**
* True if a reference URL belongs to an intentionally-hidden API tag
@@ -261,6 +262,8 @@ export function mdxToCleanMarkdown(content: string, url?: string): string {
)
);
+ result = replaceHomeNavigationMarkdown(result);
+
// Convert YouTube to link
result = result.replace(
/<YouTube\s+id="([^"]+)"\s+title="([^"]+)"\s*\/>/g,
@@ -321,7 +324,7 @@ export function mdxToCleanMarkdown(content: string, url?: string): string {
result = result.replace(/<Step>\s*###\s*(.+)/g, '#### $1');
result = result.replace(/<\/?Steps>/g, '');
result = result.replace(/<\/?Step>/g, '');
- result = result.replace(/^(\s*#{1,6})\s*#\s+(.+)$/gm, '$1 $2');
+ result = result.replace(/^(\s*#{1,6})\s+#\s+(.+)$/gm, '$1 $2');
result = result.replace(/^\s*#\s*$/gm, '');
result = result.replace(/<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n## $1\n');
diff --git a/docs/tests/static/home-navigation.test.ts b/docs/tests/static/home-navigation.test.ts
new file mode 100644
index 000000000..7f1ee827f
--- /dev/null
+++ b/docs/tests/static/home-navigation.test.ts
@@ -0,0 +1,65 @@
+import { describe, expect, test } from 'bun:test';
+
+import {
+ HOME_INTENTS,
+ homeIntentAnchor,
+ homeIntentsToMarkdown,
+ replaceHomeNavigationMarkdown,
+} from '../../lib/home-navigation';
+import { mdxToCleanMarkdown } from '../../lib/source';
+
+describe('Welcome navigation', () => {
+ test('separates build paths from use paths', () => {
+ expect(HOME_INTENTS.map(intent => intent.title)).toEqual([
+ 'Build with Composio',
+ 'Use Composio',
+ ]);
+ expect(HOME_INTENTS[0].links.map(link => link.href)).toEqual([
+ '/docs/quickstart',
+ '/docs/providers',
+ '/docs/sessions-via-mcp',
+ ]);
+ expect(HOME_INTENTS[1].links.map(link => link.href)).toEqual([
+ '/docs/agent-plugins',
+ '/docs/cli',
+ '/docs/composio-connect',
+ ]);
+ });
+
+ test('serializes the same paths for agent-readable Markdown', () => {
+ const markdown = homeIntentsToMarkdown();
+
+ for (const intent of HOME_INTENTS) {
+ expect(markdown).toContain(`### ${intent.title}`);
+ expect(markdown).toContain(`**${intent.audience}**`);
+ for (const link of intent.links) {
+ expect(markdown).toContain(`[${link.title}](${link.href})`);
+ }
+ }
+
+ expect(replaceHomeNavigationMarkdown('<HomeSurfaces />')).toBe(markdown);
+ expect(mdxToCleanMarkdown('<HomeSurfaces />')).toContain('## Two ways to start');
+ expect(mdxToCleanMarkdown('<HomeSurfaces />')).toContain('### Build with Composio');
+ expect(markdown).not.toContain('<HomeSurfaces');
+ expect(markdown.toLowerCase()).not.toContain('skills');
+ expect(markdown).toContain('native Composio plugin for Codex or Claude Code');
+ });
+
+ test('keeps rendered headings linkable and badges visible', async () => {
+ const source = await Bun.file(
+ new URL('../../components/home-surfaces.tsx', import.meta.url)
+ ).text();
+
+ expect(source).toContain('id="two-ways-to-start"');
+ for (const intent of HOME_INTENTS) {
+ expect(homeIntentAnchor(intent.title)).toMatch(/^[a-z0-9-]+$/);
+ }
+ expect(source).toContain('id={homeIntentAnchor(intent.title)}');
+ expect(source).toContain('background: PLATFORM_BADGE_GRADIENT');
+ expect(source).toContain("backgroundClip: 'text'");
+ expect(source).toContain("WebkitTextFillColor: 'transparent'");
+ expect(source).toContain("mask: 'linear-gradient(#fff 0 0) content-box");
+ expect(source).toContain('text-[#0007cd] dark:text-[#4d6fff]');
+ expect(source).toContain('audience-badge-platform-border');
+ });
+});
diff --git a/docs/tests/static/navigation.test.ts b/docs/tests/static/navigation.test.ts
index 3b7611754..21593305c 100644
--- a/docs/tests/static/navigation.test.ts
+++ b/docs/tests/static/navigation.test.ts
@@ -42,6 +42,41 @@ async function exists(path: string): Promise<boolean> {
}
describe("Navigation - meta.json validity", () => {
+ test("root navigation separates current and legacy paths", async () => {
+ const metaPath = join(CONTENT_DIR, "meta.json");
+ const meta = JSON.parse(await readFile(metaPath, "utf-8"));
+ const pages = meta.pages as string[];
+ const separators = pages.filter(isSeparator);
+
+ expect(separators).toEqual([
+ "---Get Started---",
+ "---Core concepts---",
+ "---Guides---",
+ "---Direct execution (legacy)---",
+ "---Migration and security---",
+ ]);
+
+ expect(pages.slice(1, pages.indexOf("---Core concepts---"))).toEqual([
+ "index",
+ "quickstart",
+ "providers",
+ "agent-plugins",
+ "cli",
+ "composio-connect",
+ ]);
+
+ expect(
+ pages.slice(
+ pages.indexOf("---Direct execution (legacy)---") + 1,
+ pages.indexOf("---Migration and security---")
+ )
+ ).toEqual([
+ "sessions-vs-direct-execution",
+ "tools-direct",
+ "auth-configuration",
+ ]);
+ });
+
test("root meta.json entries all resolve to files or directories", async () => {
const metaPath = join(CONTENT_DIR, "meta.json");
const meta = JSON.parse(await readFile(metaPath, "utf-8"));
diff --git a/docs/tests/static/quickstart.test.ts b/docs/tests/static/quickstart.test.ts
new file mode 100644
index 000000000..02877a15d
--- /dev/null
+++ b/docs/tests/static/quickstart.test.ts
@@ -0,0 +1,45 @@
+import { describe, expect, test } from 'bun:test';
+import { readFile } from 'fs/promises';
+import { join } from 'path';
+
+const QUICKSTART_PATH = join(import.meta.dir, '../../content/docs/quickstart.mdx');
+
+describe('Quickstart default path', () => {
+ test('presents one linear OpenAI Agents and Python flow before adaptations', async () => {
+ const content = await readFile(QUICKSTART_PATH, 'utf-8');
+ const milestones = [
+ '<StepTitle>Create the project</StepTitle>',
+ '<StepTitle>Install the packages</StepTitle>',
+ '<StepTitle>Set your API keys</StepTitle>',
+ '<StepTitle>Add the agent</StepTitle>',
+ '<StepTitle>Run it</StepTitle>',
+ '## What just happened?',
+ '## Adapt the example',
+ ];
+ const positions = milestones.map(milestone => content.indexOf(milestone));
+
+ expect(positions.every(position => position >= 0)).toBe(true);
+ expect([...positions].sort((a, b) => a - b)).toEqual(positions);
+ expect(content).not.toContain('<QuickstartFlow>');
+ expect(content).not.toContain('<FrameworkOption');
+ expect(content).not.toContain('Finish this path');
+ expect(content).not.toContain('respond exactly');
+ });
+
+ test('supports interactive and one-shot tasks', async () => {
+ const content = await readFile(QUICKSTART_PATH, 'utf-8');
+
+ expect(content).toContain('uv init --app --python 3.10 composio-quickstart');
+ expect(content).toContain(
+ 'uv add python-dotenv composio composio-openai-agents openai-agents'
+ );
+ expect(content).toContain('session = composio.sessions.create(user_id="quickstart-user")');
+ expect(content).toContain('if len(sys.argv) > 1:');
+ expect(content).toContain('run_task(" ".join(sys.argv[1:]))');
+ expect(content).toContain('task = input("You: ").strip()');
+ expect(content).toContain('uv run main.py "Find the three most recent open issues');
+ expect(content).toContain('the agent gives you a Connect Link');
+ expect(content).toContain('a small set of meta tools for finding, connecting, and running app tools');
+ expect(content).toContain('composio.use(session_id)');
+ });
+});
diff --git a/docs/tests/static/start-routing.test.ts b/docs/tests/static/start-routing.test.ts
new file mode 100644
index 000000000..e9edf3389
--- /dev/null
+++ b/docs/tests/static/start-routing.test.ts
@@ -0,0 +1,56 @@
+import { describe, expect, test } from 'bun:test';
+
+import { HOME_INTENTS } from '../../lib/home-navigation';
+
+const read = (path: string) => Bun.file(new URL(`../../${path}`, import.meta.url)).text();
+
+describe('getting-started routing policy', () => {
+ test('publishes native plugins for both supported agent hosts', async () => {
+ const plugins = await read('content/docs/agent-plugins.mdx');
+
+ expect(plugins).toContain('Agent plugins let Codex and Claude Code use Composio');
+ expect(plugins).toContain('composio setup --target codex');
+ expect(plugins).toContain('composio setup --target claude');
+ expect(plugins).toContain('codex plugin marketplace add');
+ expect(plugins).toContain('/plugin marketplace add');
+ expect(plugins).toContain('composio search');
+ expect(plugins).toContain('composio link');
+ expect(plugins).toContain('composio execute');
+ expect(plugins).toContain('composio --install-skill composio-cli claude');
+ expect(plugins).toContain('composio --install-skill composio-cli codex');
+ expect(plugins).toContain('composio setup --target auto --yes');
+ expect(plugins).toContain('### Codex');
+ expect(plugins).toContain('### Claude Code');
+ expect(plugins).not.toContain('<Tabs');
+ });
+
+ test('keeps native plugins ahead of CLI and explicit MCP on Welcome', () => {
+ expect(HOME_INTENTS[1].links.map(link => link.href)).toEqual([
+ '/docs/agent-plugins',
+ '/docs/cli',
+ '/docs/composio-connect',
+ ]);
+ });
+
+ test('keeps progressive authentication guides in the human and agent indexes', async () => {
+ const [authentication, llmsRoute] = await Promise.all([
+ read('content/docs/authentication.mdx'),
+ read('app/llms.txt/route.ts'),
+ ]);
+ const guides = [
+ 'manually-authenticating',
+ 'managing-multiple-connected-accounts',
+ 'shared-connections',
+ 'importing-existing-connections',
+ 'custom-app-vs-managed-app',
+ 'programmatic-auth-configs',
+ 'controlling-scopes',
+ 'white-labeling-authentication',
+ ];
+
+ for (const guide of guides) {
+ expect(authentication).toContain(`href="/docs/${guide}"`);
+ expect(llmsRoute).toContain(`'/docs/${guide}'`);
+ }
+ });
+});