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 Jhunjhunwala committed
Aug 7, 2026 at 17:21 UTC
943591ac9af929d3d5674f4d4d91eccf97b64ed5
33 files changed
+722
-768
docs/app/(home)/page.tsx
+2
-25
@@ -1,28 +1,5 @@
1
-import Link from 'next/link';
1
+import { permanentRedirect } from 'next/navigation';
2
3
export default function HomePage() {
4
- return (
5
- <div className="flex flex-col justify-center text-center flex-1 px-6 py-16">
6
- <h1 className="text-3xl md:text-4xl mb-4 font-medium tracking-tight" style={{ color: 'var(--composio-orange)' }}>
7
- Composio Documentation
8
- </h1>
9
- <p className="text-lg text-[var(--color-fd-muted-foreground)] max-w-xl mx-auto mb-8">
10
- Connect AI agents to 1000+ tools with managed authentication.
11
- </p>
12
- <div className="flex gap-4 justify-center">
13
- <Link
14
- href="/docs"
15
- 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"
16
- >
17
- Get Started
18
- </Link>
19
- <Link
20
- href="/docs/quickstart"
21
- className="px-5 py-2.5 rounded-lg border border-[var(--color-fd-border)] font-medium hover:bg-[var(--color-fd-muted)] transition-colors"
22
- >
23
- Quickstart
24
- </Link>
25
- </div>
26
- </div>
27
- );
4
+ permanentRedirect('/docs');
5
}
docs/app/global.css
+15
@@ -1140,6 +1140,21 @@ html:not(.dark) .terminal-theme-claude {
1140
}
1141
}
1142
1143
+@media (forced-colors: active) {
1144
+ .audience-badge-platform {
1145
+ background: none !important;
1146
+ color: CanvasText !important;
1147
+ -webkit-text-fill-color: CanvasText !important;
1148
+ }
1149
+
1150
+ .audience-badge-platform-border {
1151
+ background: none !important;
1152
+ border: 1px solid CanvasText;
1153
+ mask: none !important;
1154
+ -webkit-mask: none !important;
1155
+ }
1156
+}
1157
+
1158
/* @pierre/diffs: the +/- stat counts in the file header are hidden via the
1159
`unsafeCSS` option in components/diff-view.tsx, NOT here — the header renders
1160
inside an open shadow root that global CSS can't pierce. */
docs/app/llms.txt/route.ts
+16
-1
@@ -100,6 +100,17 @@ function formatPage(page: { url: string }) {
100
return `- https://docs.composio.dev${page.url}.md`;
101
}
102
103
+const AUTHENTICATION_GUIDE_URLS = [
104
+ '/docs/manually-authenticating',
105
+ '/docs/managing-multiple-connected-accounts',
106
+ '/docs/shared-connections',
107
+ '/docs/importing-existing-connections',
108
+ '/docs/custom-app-vs-managed-app',
109
+ '/docs/programmatic-auth-configs',
110
+ '/docs/controlling-scopes',
111
+ '/docs/white-labeling-authentication',
112
+];
113
+
114
/**
115
* Splits reference pages by REST version.
116
*
@@ -150,10 +161,14 @@ ${legacyReferencePages.map(formatPage).join('\n')}
161
162
> Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
163
153
-> **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.
164
+> **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.
165
166
${docsTree}
167
168
+## Authentication guides
169
+
170
+${AUTHENTICATION_GUIDE_URLS.map(url => formatPage({ url })).join('\n')}
171
+
172
## Examples
173
174
${examplesPages.map(formatPage).join('\n')}
docs/components/docs-hero-v2.tsx
+7
-50
@@ -1,58 +1,15 @@
1
-import Link from 'next/link';
2
-import { Play, Code2, Blocks } from 'lucide-react';
3
-import { DocsHeroV2Chat } from './docs-hero-v2-chat';
4
-
5
-const CHIPS = [
6
- { label: 'Quickstart', href: '/docs/quickstart', icon: Play },
7
- { label: 'API reference', href: '/reference', icon: Code2 },
8
- { label: 'Toolkits', href: '/toolkits', icon: Blocks },
9
-];
10
-
11
-/**
12
- * Welcome-page hero — v2.
13
- *
14
- * Two-column layout: copy + entry points on the left, mock chat / agent
15
- * loop on the right. Left column mirrors the dev-platform pattern
16
- * popularized by Claude / OpenAI docs: small eyebrow, large headline,
17
- * sub paragraph, search input, then a row of quick-link chips.
18
- */
1
export function DocsHeroV2() {
2
return (
21
- <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">
22
- {/* Left — copy + entry points */}
23
- <div className="flex flex-col gap-5">
24
- <h1 className="text-3xl font-medium leading-[1.05] tracking-[-0.025em] text-fd-foreground md:text-4xl lg:text-[40px]">
25
- Start building with Composio.
3
+ <section className="py-10 sm:py-12">
4
+ <div className="flex max-w-[720px] flex-col gap-5">
5
+ <h1 className="text-4xl font-medium leading-[1.05] tracking-[-0.03em] text-fd-foreground sm:text-5xl">
6
+ Give agents the tools they need.
7
</h1>
8
28
- <p className="max-w-[480px] text-[15px] leading-[1.55] text-fd-foreground/70 md:text-base">
29
- Give your AI agent 1000+ pre-authenticated toolkits, per-user
30
- sessions, triggers, and a workbench.
9
+ <p className="max-w-[620px] text-base leading-[1.6] text-fd-foreground/70 sm:text-lg">
10
+ Use Composio to discover tools, authenticate each user, and run
11
+ actions across 1,000+ apps.
12
</p>
32
-
33
- {/* Quick-link chips — single column */}
34
- <div className="flex max-w-[360px] flex-col gap-2">
35
- {CHIPS.map(({ label, href, icon: Icon }) => (
36
- <Link
37
- key={href}
38
- 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"
39
- href={href}
40
- >
41
- <Icon
42
- aria-hidden="true"
43
- className="size-4 text-[var(--composio-brand)]"
44
- />
45
- {label}
46
- </Link>
47
- ))}
48
- </div>
49
- </div>
50
-
51
- {/* Right — mock chat with floating "active tool" card.
52
- Hidden below lg: the layered animation is fiddly on small
53
- screens and the left column carries the welcome on its own. */}
54
- <div className="relative hidden lg:block lg:h-full">
55
- <DocsHeroV2Chat />
13
</div>
14
</section>
15
);
docs/components/docs-hero.tsx
+1
-1
@@ -11,7 +11,7 @@ import { DocsHeroV2 } from './docs-hero-v2';
11
*/
12
export function DocsHero() {
13
return (
14
- <div className="not-prose mb-10">
14
+ <div className="not-prose mb-2">
15
<DocsHeroV2 />
16
{/* <HeroSection /> */}
17
</div>
docs/components/home-features.tsx
+6
-1
@@ -298,9 +298,11 @@ function StaticCpuLights() {
298
299
export function SectionHeading({
300
eyebrow,
301
+ id,
302
title,
303
}: {
304
eyebrow: string;
305
+ id?: string;
306
title: string;
307
}) {
308
return (
@@ -308,7 +310,10 @@ export function SectionHeading({
310
<span className="font-mono text-[10.5px] uppercase tracking-[0.08em] text-fd-foreground/55">
311
{eyebrow}
312
</span>
311
- <h2 className="text-xl font-medium leading-[1.15] tracking-[-0.01em] text-fd-foreground sm:text-2xl">
313
+ <h2
314
+ className="text-xl font-medium leading-[1.15] tracking-[-0.01em] text-fd-foreground sm:text-2xl"
315
+ id={id}
316
+ >
317
{title}
318
</h2>
319
</div>
docs/components/home-surfaces.tsx
+98
-234
@@ -1,260 +1,124 @@
1
-'use client';
2
-
1
import Link from 'next/link';
4
-import Image from 'next/image';
5
-import {
6
- ArrowUpRight,
7
- Code2,
8
- Heart,
9
- Terminal,
10
- Copy,
11
- Check,
12
-} from 'lucide-react';
13
-import { useState, type ReactNode, type MouseEvent } from 'react';
2
+import { ArrowUpRight, Code2, Plug } from 'lucide-react';
3
+import type { LucideIcon } from 'lucide-react';
4
+import { HOME_INTENTS, homeIntentAnchor, type HomeIntent } from '@/lib/home-navigation';
5
import { SectionHeading } from './home-features';
6
16
-// Some provider logos ship a dedicated `-dark` variant (white-on-dark
17
-// or stroke-inverted). Use those in dark mode instead of inverting the
18
-// light SVG via CSS — `dark:invert` mangles full-colour logos
19
-// (Google's primary palette, LlamaIndex's gradient, CrewAI's brand).
20
-const PROVIDERS: { name: string; logo: string; logoDark?: string }[] = [
21
- {
22
- name: 'Anthropic',
23
- logo: '/images/providers/anthropic-logo.svg',
24
- logoDark: '/images/providers/anthropic-logo-dark.svg',
25
- },
26
- {
27
- name: 'OpenAI',
28
- logo: '/images/providers/openai-logo.svg',
29
- logoDark: '/images/providers/openai-logo-dark.svg',
30
- },
31
- {
32
- name: 'Vercel AI',
33
- logo: '/images/providers/vercel-logo.svg',
34
- logoDark: '/images/providers/vercel-logo-dark.svg',
35
- },
36
- { name: 'Google', logo: '/images/providers/google-logo.svg' },
37
- {
38
- name: 'LangChain',
39
- logo: '/images/providers/langchain-logo.svg',
40
- logoDark: '/images/providers/langchain-logo-dark.svg',
41
- },
42
- { name: 'CrewAI', logo: '/images/providers/crewai-logo.svg' },
43
- { name: 'LlamaIndex', logo: '/images/providers/llamaIndex-logo.svg' },
44
- {
45
- name: 'Mastra',
46
- logo: '/images/providers/mastra-logo.svg',
47
- logoDark: '/images/providers/mastra-logo-dark.svg',
48
- },
49
-];
50
-
51
-const CLIENTS: { name: string; logo: string; h: number }[] = [
52
- { name: 'Claude', logo: '/images/clients/claude.svg', h: 20 },
53
- { name: 'Codex', logo: '/images/clients/codex.png', h: 20 },
54
- { name: 'Cursor', logo: '/images/clients/cursor.svg', h: 20 },
55
- { name: 'Windsurf', logo: '/images/clients/windsurf.svg', h: 20 },
56
- { name: 'OpenClaw', logo: '/images/clients/openclaw.svg', h: 20 },
57
-];
7
+const INTENT_ICONS: Record<HomeIntent['id'], LucideIcon> = {
8
+ build: Code2,
9
+ use: Plug,
10
+};
11
59
-/**
60
- * Welcome-page audience selector — surfaces the three ways into Composio.
61
- * "Build with the SDK" gets the full width of the top row and a strip of
62
- * provider logos showing which frameworks ship first-class support; the
63
- * two non-developer surfaces (For You + CLI) sit below in a 2-col row.
64
- */
12
export function HomeSurfaces() {
13
return (
14
<section className="not-prose mb-14">
15
<SectionHeading
69
- eyebrow="For everyone"
70
- title="Three ways to use Composio."
16
+ eyebrow="Get started"
17
+ id="two-ways-to-start"
18
+ title="Two ways to start"
19
/>
20
<div className="grid grid-cols-1 gap-5 md:grid-cols-2">
73
- {/* Full-width Developers card */}
74
- <SurfaceCard
75
- eyebrow="Developers"
76
- eyebrowIcon={<Code2 aria-hidden="true" className="size-4" />}
77
- title="Build with the SDK"
78
- description="You're here. TypeScript or Python, with first-class providers for the frameworks you already use."
79
- href="/docs/quickstart"
80
- external={false}
81
- spanFull
82
- extra={<ProviderStrip />}
83
- />
84
- {/* Bottom row: For You + CLI */}
85
- <SurfaceCard
86
- eyebrow="For You"
87
- eyebrowIcon={<Heart aria-hidden="true" className="size-4" />}
88
- title="Use Composio yourself"
89
- description="Plug 1000+ pre-authenticated apps into Claude Code, Cursor, or any MCP client. No build required. Connect once and go."
90
- href="https://composio.dev/for-you"
91
- external
92
- extra={<ClientStrip />}
93
- />
94
- <SurfaceCard
95
- eyebrow="CLI"
96
- eyebrowIcon={<Terminal aria-hidden="true" className="size-4" />}
97
- title="Run Composio from your shell"
98
- description="Connect accounts, search tools, and execute them right from your terminal."
99
- href="/docs/cli"
100
- external={false}
101
- extra={<CliInstall />}
102
- />
21
+ {HOME_INTENTS.map(intent => (
22
+ <IntentCard key={intent.id} intent={intent} />
23
+ ))}
24
</div>
25
</section>
26
);
27
}
28
108
-function SurfaceCard({
109
- eyebrowIcon,
110
- eyebrow,
111
- title,
112
- description,
113
- href,
114
- external,
115
- spanFull,
116
- extra,
117
-}: {
118
- eyebrowIcon: ReactNode;
119
- eyebrow: string;
120
- title: string;
121
- description: string;
122
- href: string;
123
- external: boolean;
124
- spanFull?: boolean;
125
- extra?: ReactNode;
126
-}) {
127
- const externalProps = external
128
- ? { target: '_blank' as const, rel: 'noopener noreferrer' }
129
- : {};
29
+function IntentCard({ intent }: { intent: HomeIntent }) {
30
+ const Icon = INTENT_ICONS[intent.id];
31
+
32
return (
131
- <Link
132
- href={href}
133
- {...externalProps}
134
- className={
135
- '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' +
136
- (spanFull ? ' md:col-span-2' : '')
137
- }
138
- >
139
- <div className="flex items-center justify-between">
140
- <span className="inline-flex items-center gap-1.5 font-mono text-[11px] uppercase tracking-[0.08em] text-[var(--composio-brand)]">
141
- {eyebrowIcon}
142
- {eyebrow}
143
- </span>
144
- <ArrowUpRight
145
- aria-hidden="true"
146
- className="size-3.5 text-fd-foreground/60 transition-transform group-hover:-translate-y-px group-hover:translate-x-px"
147
- />
33
+ <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">
34
+ <AudienceBadge audience={intent.audience} />
35
+ <div className="mb-4 flex items-center gap-2 text-[var(--composio-brand)]">
36
+ <Icon aria-hidden="true" className="size-4" />
37
+ <h3
38
+ className="text-[18px] font-medium tracking-[-0.01em] text-fd-foreground"
39
+ id={homeIntentAnchor(intent.title)}
40
+ >
41
+ {intent.title}
42
+ </h3>
43
</div>
149
- <h3 className="text-[17px] font-medium leading-snug tracking-[-0.01em] text-fd-foreground sm:text-lg">
150
- {title}
151
- </h3>
152
- <p className="text-[14px] leading-[1.55] text-fd-foreground/70">
153
- {description}
44
+ <p className="mb-5 text-[14px] leading-[1.55] text-fd-foreground/70">
45
+ {intent.description}
46
</p>
155
- {extra}
156
- </Link>
47
+ <ul className="mt-auto flex flex-col gap-2">
48
+ {intent.links.map(link => (
49
+ <li key={link.href}>
50
+ <Link
51
+ 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"
52
+ href={link.href}
53
+ >
54
+ <span className="flex min-w-0 flex-col gap-0.5">
55
+ <span className="text-[14px] font-medium text-fd-foreground">
56
+ {link.title}
57
+ </span>
58
+ <span className="text-[12.5px] leading-[1.45] text-fd-foreground/65">
59
+ {link.description}
60
+ </span>
61
+ </span>
62
+ <ArrowUpRight
63
+ aria-hidden="true"
64
+ 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"
65
+ />
66
+ </Link>
67
+ </li>
68
+ ))}
69
+ </ul>
70
+ </article>
71
);
72
}
73
160
-const CLI_INSTALL_COMMAND = 'curl -fsSL https://composio.dev/install | sh';
161
-
162
-function CliInstall() {
163
- const [copied, setCopied] = useState(false);
164
-
165
- function handleCopy(e: MouseEvent<HTMLButtonElement>) {
166
- // The whole card is wrapped in a <Link> — keep this click from
167
- // navigating to /docs/cli.
168
- e.preventDefault();
169
- e.stopPropagation();
170
- navigator.clipboard.writeText(CLI_INSTALL_COMMAND).then(() => {
171
- setCopied(true);
172
- window.setTimeout(() => setCopied(false), 1500);
173
- });
174
- }
74
+const PLATFORM_BADGE_GRADIENT =
75
+ 'linear-gradient(135deg, #00e68a, #00b4d8, #0077ff)';
76
176
- return (
177
- <div className="mt-2 flex items-center gap-2 border border-fd-border bg-fd-background px-3 py-2 font-mono text-[12px]">
178
- <span className="shrink-0 text-fd-foreground/40">$</span>
179
- <code className="flex-1 truncate text-fd-foreground/85">
180
- {CLI_INSTALL_COMMAND}
181
- </code>
182
- <button
183
- aria-label={copied ? 'Copied' : 'Copy install command'}
184
- className="-mr-1 inline-flex size-6 shrink-0 items-center justify-center text-fd-foreground/55 transition-colors hover:text-fd-foreground"
185
- onClick={handleCopy}
186
- type="button"
187
- >
188
- {copied ? (
189
- <Check
190
- aria-hidden="true"
191
- className="size-3.5 text-[var(--composio-brand)]"
192
- />
193
- ) : (
194
- <Copy aria-hidden="true" className="size-3.5" />
195
- )}
196
- </button>
197
- </div>
198
- );
199
-}
77
+function AudienceBadge({ audience }: { audience: HomeIntent['audience'] }) {
78
+ const isPlatform = audience === 'Platform';
79
201
-function ClientStrip() {
80
return (
203
- <div className="mt-2 flex flex-wrap items-center gap-x-5 gap-y-3">
204
- {CLIENTS.map((c) => (
205
- <Image
206
- key={c.name}
207
- alt={c.name}
208
- className="object-contain"
209
- height={c.h}
210
- src={c.logo}
211
- style={{ height: c.h, width: 'auto' }}
212
- width={Math.ceil(c.h * 3.5)}
213
- />
214
- ))}
215
- </div>
216
- );
217
-}
218
-
219
-function ProviderStrip() {
220
- return (
221
- <div className="mt-2 flex flex-wrap items-center gap-3">
222
- {PROVIDERS.map((p) => (
223
- <div
224
- key={p.name}
225
- className="flex h-10 items-center justify-center gap-2 rounded-md border border-fd-border bg-fd-card px-3"
226
- title={p.name}
227
- >
228
- {p.logoDark ? (
229
- <>
230
- <Image
231
- alt={p.name}
232
- className="h-4 w-auto object-contain dark:hidden"
233
- height={16}
234
- src={p.logo}
235
- width={64}
236
- />
237
- <Image
238
- alt=""
239
- aria-hidden="true"
240
- className="hidden h-4 w-auto object-contain dark:block"
241
- height={16}
242
- src={p.logoDark}
243
- width={64}
244
- />
245
- </>
246
- ) : (
247
- <Image
248
- alt={p.name}
249
- className="h-4 w-auto object-contain"
250
- height={16}
251
- src={p.logo}
252
- width={64}
253
- />
254
- )}
255
- <span className="text-[12px] text-fd-foreground/75">{p.name}</span>
256
- </div>
257
- ))}
258
- </div>
81
+ <span
82
+ className={
83
+ '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 ' +
84
+ (isPlatform
85
+ ? 'audience-badge-platform'
86
+ : 'text-[#0007cd] dark:text-[#4d6fff]')
87
+ }
88
+ style={
89
+ isPlatform
90
+ ? {
91
+ background: PLATFORM_BADGE_GRADIENT,
92
+ backgroundClip: 'text',
93
+ WebkitBackgroundClip: 'text',
94
+ WebkitTextFillColor: 'transparent',
95
+ }
96
+ : undefined
97
+ }
98
+ >
99
+ <span
100
+ aria-hidden="true"
101
+ className={
102
+ 'pointer-events-none absolute inset-0 rounded-[4px] ' +
103
+ (isPlatform
104
+ ? 'audience-badge-platform-border'
105
+ : 'border border-[#0007cd] dark:border-[#4d6fff]')
106
+ }
107
+ style={
108
+ isPlatform
109
+ ? {
110
+ padding: '1px',
111
+ background: PLATFORM_BADGE_GRADIENT,
112
+ WebkitMask:
113
+ 'linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)',
114
+ WebkitMaskComposite: 'xor',
115
+ mask: 'linear-gradient(#fff 0 0) content-box, linear-gradient(#fff 0 0)',
116
+ maskComposite: 'exclude',
117
+ }
118
+ : undefined
119
+ }
120
+ />
121
+ {audience}
122
+ </span>
123
);
124
}
docs/content/docs/agent-plugins.mdx
new
+95
@@ -0,0 +1,95 @@
1
+---
2
+title: Agent plugins
3
+description: Install Composio for Codex or Claude Code
4
+keywords: [agent plugins, codex, claude code, cli, composio setup, skills]
5
+---
6
+
7
+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.
8
+
9
+## Install the plugin
10
+
11
+Install the Composio CLI:
12
+
13
+```bash
14
+curl -fsSL https://composio.dev/install | sh
15
+```
16
+
17
+Open a new terminal, sign in, and configure every supported agent on your machine:
18
+
19
+```bash
20
+composio login
21
+composio setup --target auto
22
+```
23
+
24
+`auto` detects Codex and Claude Code. If both are installed, it configures both.
25
+
26
+<Callout type="info" title="Running setup from an agent or script?">
27
+Setup asks before changing local files. Add `--yes` in a non-interactive shell: `composio setup --target auto --yes`.
28
+</Callout>
29
+
30
+## Try a task
31
+
32
+Ask Codex or Claude Code to work with one of your apps:
33
+
34
+- `List the open GitHub issues assigned to me.`
35
+- `Summarize the unread Gmail messages I received today.`
36
+- `Create a Linear issue from these release notes: ...`
37
+
38
+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.
39
+
40
+## Configure one agent
41
+
42
+Use an explicit target when you only want to configure one agent.
43
+
44
+### Codex
45
+
46
+```bash
47
+composio setup --target codex
48
+```
49
+
50
+The Codex plugin bundles the Composio CLI skill. You can also install the plugin with Codex directly:
51
+
52
+```bash
53
+codex plugin marketplace add https://github.com/ComposioHQ/composio-plugin-openai.git --json
54
+codex plugin add composio@composio --json
55
+```
56
+
57
+The plugin source is available in [`ComposioHQ/composio-plugin-openai`](https://github.com/ComposioHQ/composio-plugin-openai).
58
+
59
+### Claude Code
60
+
61
+```bash
62
+composio setup --target claude
63
+```
64
+
65
+You can also install the plugin from Claude Code:
66
+
67
+```bash
68
+/plugin marketplace add ComposioHQ/composio-plugin-cc
69
+/plugin install composio@composio
70
+```
71
+
72
+See the [Claude Code plugin guide](/docs/claude-code-plugin) for team installation, updates, and troubleshooting.
73
+
74
+## What the plugin uses
75
+
76
+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).
77
+
78
+## Install only the CLI skill
79
+
80
+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.
81
+
82
+If you want the skill without the plugin, install it for your agent directly:
83
+
84
+```bash
85
+composio --install-skill composio-cli claude
86
+composio --install-skill composio-cli codex
87
+```
88
+
89
+## Choose another setup
90
+
91
+<Cards>
92
+ <Card title="Build an agent" href="/docs/quickstart" description="Add Composio tools and authentication to your application." />
93
+ <Card title="Use the CLI" href="/docs/cli" description="Search, connect, and run tools from your terminal." />
94
+ <Card title="Connect over MCP" href="/docs/composio-connect" description="Add Composio to an existing MCP client." />
95
+</Cards>
docs/content/docs/auth-configuration/meta.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
- "title": "Authentication",
2
+ "title": "Direct auth",
3
"defaultOpen": false,
4
"pages": [
5
"custom-auth-configs",
docs/content/docs/authentication.mdx
+12
-3
@@ -133,6 +133,15 @@ console.log(connectionRequest.redirectUrl);
133
</Tab>
134
</Tabs>
135
136
-## Next
137
-
138
-<Card icon={<ShieldCheck />} title="Manual auth management" href="/docs/manually-authenticating" description="Generate Connect Links yourself, check connection status, and disable in-chat prompts" />
136
+## Authentication guides
137
+
138
+<Cards>
139
+ <Card title="Manual auth management" href="/docs/manually-authenticating" description="Generate Connect Links yourself, check connection status, and disable in-chat prompts." />
140
+ <Card title="Multiple connected accounts" href="/docs/managing-multiple-connected-accounts" description="Let one user choose between work, personal, or other accounts." />
141
+ <Card title="Shared connections" href="/docs/shared-connections" description="Share one connected account with a controlled set of users." />
142
+ <Card title="Import existing connections" href="/docs/importing-existing-connections" description="Bring credentials your application already stores into Composio." />
143
+ <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." />
144
+ <Card title="Programmatic auth configs" href="/docs/programmatic-auth-configs" description="Create auth configs in code and attach them to sessions." />
145
+ <Card title="Control OAuth scopes" href="/docs/controlling-scopes" description="Choose the permissions requested when a user connects." />
146
+ <Card title="White-label authentication" href="/docs/white-labeling-authentication" description="Use your own OAuth app and remove Composio branding." />
147
+</Cards>
docs/content/docs/claude-code-plugin.mdx
+1
-1
@@ -7,7 +7,7 @@ keywords: [claude code, plugin, marketplace, composio, oauth, cli, mcp]
7
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.
8
9
<Callout type="info">
10
-Using Cursor, Codex, Claude Desktop, or another MCP client? See [Composio Connect](/docs/composio-connect).
10
+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).
11
</Callout>
12
13
## Install
docs/content/docs/cli.mdx
+25
-12
@@ -1,12 +1,12 @@
1
---
2
title: Composio CLI
3
-description: Use the Composio CLI inside Claude Code for knowledge work, debugging, and developer workflows.
4
-keywords: [cli, claude code, command line, terminal, composio for you, knowledge work, dev commands]
3
+description: Use the Composio CLI from Codex, Claude Code, or your terminal for agent workflows and development.
4
+keywords: [cli, codex, claude code, command line, terminal, agent plugins, knowledge work, dev commands]
5
---
6
7
-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).
7
+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).
8
9
-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.
9
+Reach for it when you want an agent to act in your connected apps directly, without building an SDK application or configuring MCP.
10
11
## Install
12
@@ -24,10 +24,23 @@ Open a new terminal, then log in:
24
composio login
25
```
26
27
-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:
27
+Install the native plugin for Codex or Claude Code:
28
+
29
+```bash
30
+composio setup --target auto
31
+```
32
+
33
+`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.
34
+
35
+Setup asks before changing local files. Add `--yes` when you run it from an agent, script, CI job, or another non-interactive shell.
36
+
37
+`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.
38
+
39
+If you explicitly need the standalone skill without the native plugin, install it manually for the agent host:
40
41
```bash
42
composio --install-skill composio-cli claude
43
+composio --install-skill composio-cli codex
44
```
45
46
### Install with options
@@ -198,13 +211,13 @@ rm -rf "${COMPOSIO_INSTALL_DIR:-$HOME/.composio}"
211
```
212
</Callout>
213
201
-## Knowledge work in Claude Code
214
+## Agent and terminal workflows
215
203
-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.
216
+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.
217
218
### Search, connect, and execute tools
219
207
-Use this flow when Claude needs to act in one of your connected apps:
220
+Use this flow when you or your agent needs to act in one of your connected apps:
221
222
```bash
223
# Find the right tool
@@ -230,7 +243,7 @@ The commands you'll reach for most:
243
| `composio link` | Connect an app account |
244
| `composio proxy` | Call provider APIs with Composio-managed auth |
245
233
-Use `composio proxy` when Claude already knows the provider's API endpoint and just needs Composio to inject auth from your connected account:
246
+Use `composio proxy` when the agent already knows the provider's API endpoint and just needs Composio to inject auth from your connected account:
247
248
```bash
249
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
251
252
### Run scripts and sub-agents
253
241
-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.
254
+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.
255
256
Run a single scripted workflow:
257
@@ -297,7 +310,7 @@ composio run --file ./workflow.ts -- --repo composiohq/composio
310
311
### Listen to trigger events
312
300
-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:
313
+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:
314
315
```bash
316
# Compact table view for matching events
@@ -309,7 +322,7 @@ composio dev listen --trigger-slug GMAIL_NEW_GMAIL_MESSAGE --json --max-events 5
322
# Forward each matching event to a local or hosted webhook
323
composio dev listen --toolkits github --forward https://example.com/webhook
324
312
-# Append matching events to a local file for Claude to inspect
325
+# Append matching events to a local file for an agent to inspect
326
composio dev listen --toolkits slack --out ./events.jsonl
327
```
328
docs/content/docs/composio-connect.mdx
+7
-3
@@ -1,14 +1,18 @@
1
---
2
title: Composio Connect
3
-description: Add Composio tools to your AI agent via MCP
3
+description: Connect Composio to an existing MCP client without using the SDK
4
keywords: [composio connect, mcp, claude code, cursor, vscode, windsurf, cline, chatgpt, notion, n8n, codex]
5
---
6
7
-Give any AI agent the ability to act across 1000+ apps. Bring your agent to where you work.
7
+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`.
8
+
9
+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.
10
+
11
+If you are building an application, start with the [SDK Quickstart](/docs/quickstart) or create a [session MCP endpoint](/docs/sessions-via-mcp) instead.
12
13
## How Composio Connect works
14
11
-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.
15
+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.
16
17
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.
18
docs/content/docs/extending-sessions/meta.json
+2
-2
@@ -1,6 +1,6 @@
1
{
2
- "title": "Extending sessions capabilities",
3
- "defaultOpen": true,
2
+ "title": "Extend sessions",
3
+ "defaultOpen": false,
4
"pages": [
5
"proxy-execute",
6
"custom-tools-and-toolkits",
docs/content/docs/index.mdx
+3
-3
@@ -1,13 +1,13 @@
1
---
2
title: Welcome
3
-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.
3
+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.
4
keywords: [getting started, introduction]
5
---
6
7
<DocsHero />
8
9
-<HomeFeatures />
10
-
9
<HomeSurfaces />
10
11
+<HomeFeatures />
12
+
13
<HomeResources />
docs/content/docs/meta.json
+12
-25
@@ -4,38 +4,25 @@
4
"index",
5
"quickstart",
6
"providers",
7
- "---Customizing sessions---",
7
+ "agent-plugins",
8
+ "cli",
9
+ "composio-connect",
10
+ "---Core concepts---",
11
"how-composio-works",
12
"configuring-sessions",
13
+ "authentication",
14
+ "triggers",
15
+ "---Guides---",
16
"sessions-via-mcp",
17
"sandbox",
18
"extending-sessions",
13
- "---Authenticate users---",
14
- "authentication",
15
- "manually-authenticating",
16
- "managing-multiple-connected-accounts",
17
- "shared-connections",
18
- "importing-existing-connections",
19
- "---Customizing auth---",
20
- "custom-app-vs-managed-app",
21
- "programmatic-auth-configs",
22
- "controlling-scopes",
23
- "white-labeling-authentication",
24
- "---Triggers---",
25
- "triggers",
26
- "setting-up-triggers/creating-triggers",
27
- "setting-up-triggers/subscribing-to-events",
28
- "setting-up-triggers/managing-triggers",
29
- "setting-up-triggers/custom-oauth-webhooks",
30
- "---Security and Data---",
31
- "security/overview",
32
- "security/data-retention",
33
- "---Direct Tool Execution Guides (Legacy)---",
19
+ "setting-up-triggers",
20
+ "---Direct execution (legacy)---",
21
"sessions-vs-direct-execution",
22
"tools-direct",
23
"auth-configuration",
37
- "---Other topics---",
38
- "cli",
39
- "migration-guide"
24
+ "---Migration and security---",
25
+ "migration-guide",
26
+ "security"
27
]
28
}
docs/content/docs/migration-guide/meta.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
- "title": "Migration Guide",
2
+ "title": "Migration guides",
3
"pages": [
4
"direct-to-sessions",
5
"mcp-servers-to-sessions",
docs/content/docs/providers/custom-providers/meta.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
- "title": "Custom Providers",
2
+ "title": "Custom providers",
3
"pages": [
4
"typescript",
5
"python"
docs/content/docs/providers/index.mdx
+5
-1
@@ -1,5 +1,5 @@
1
---
2
-title: Providers
2
+title: SDKs and frameworks
3
description: Composio works with any AI framework. Pick your preferred SDK to get started.
4
---
5
@@ -7,6 +7,10 @@ Composio works with any AI framework. A provider is the adapter that turns Compo
7
8
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).
9
10
+<Callout type="info" title="Using TypeScript?">
11
+The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` instead of CommonJS `require()`.
12
+</Callout>
13
+
14
## AI SDKs
15
16
Use these when you call a model SDK directly.
docs/content/docs/providers/meta.json
+3
-3
@@ -1,7 +1,6 @@
1
{
2
- "title": "Providers",
2
+ "title": "SDKs and frameworks",
3
"pages": [
4
- "...",
4
"anthropic",
5
"openai",
6
"vercel",
@@ -13,6 +12,7 @@
12
"crewai",
13
"llamaindex",
14
"mastra",
16
- "custom-providers"
15
+ "custom-providers",
16
+ "..."
17
]
18
}
docs/content/docs/quickstart.mdx
+101
-390
@@ -1,443 +1,154 @@
1
---
2
title: Quickstart
3
-description: Build an AI agent with access to 1000+ tools
4
-keywords: [tutorial, setup, first agent]
3
+description: Build a Python agent that discovers and runs Composio tools
4
+keywords: [tutorial, setup, first agent, python, openai agents, sessions, tool router]
5
---
6
7
-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).
7
+Build an agent that chooses Composio tools at runtime. Type a task, connect an app if needed, and continue in the same conversation.
8
9
-<Callout type="info">
10
-The TypeScript SDK is ESM-only and requires Node.js 22.22.3 or newer. Use `import` syntax rather than CommonJS `require()`.
11
-</Callout>
9
+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).
10
13
-<QuickstartFlow>
11
+## Prerequisites
12
15
-<FrameworkOption id="openai-agents" name="OpenAI Agents" logo="/images/providers/openai-logo.svg" logoDark="/images/providers/openai-logo-dark.svg">
13
+You need:
14
17
-<Steps>
18
-<Step>
19
-<StepTitle>Install</StepTitle>
20
-
21
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
22
-<Tab value="Python">
23
-The Composio Python SDK requires **Python 3.10 or newer**.
24
-
25
-<PackageInstall ecosystem="python" packages="python-dotenv composio composio-openai-agents openai-agents" />
26
-</Tab>
27
-<Tab value="TypeScript">
28
-<PackageInstall
29
- packages="@composio/core @composio/openai-agents @openai/agents"
30
- comment={[
31
- '@composio/core ships its docs and TypeScript source in the package,',
32
- 'so it is inspectable to coding agents.',
33
- 'Use @composio/slim for a smaller install with the same API.',
34
- ]}
35
-/>
36
-</Tab>
37
-</Tabs>
38
-</Step>
15
+- [`uv`](https://docs.astral.sh/uv/) to create the Python project and install its dependencies.
16
+- 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).
17
+- An `OPENAI_API_KEY` from [OpenAI](https://platform.openai.com/api-keys).
18
+
19
+## Build the agent
20
21
+<Steps>
22
<Step>
41
-<StepTitle>Configure API Keys</StepTitle>
23
+<StepTitle>Create the project</StepTitle>
24
43
-<Callout type="info">
44
-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).
45
-</Callout>
25
+Create a Python 3.10 project and enter its directory:
26
47
-```bash title=".env"
48
-COMPOSIO_API_KEY=your_composio_api_key
49
-OPENAI_API_KEY=your_openai_api_key
27
+```bash
28
+uv init --app --python 3.10 composio-quickstart
29
+cd composio-quickstart
30
```
51
-</Step>
31
32
+</Step>
33
<Step>
54
-<StepTitle>Create session and run agent</StepTitle>
34
+<StepTitle>Install the packages</StepTitle>
35
56
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
57
-<Tab value="Python">
58
-```python
59
-from dotenv import load_dotenv
60
-from composio import Composio
61
-from agents import Agent, Runner, SQLiteSession
62
-from composio_openai_agents import OpenAIAgentsProvider
63
-
64
-load_dotenv()
65
-
66
-# Initialize Composio with OpenAI Agents provider
67
-composio = Composio(provider=OpenAIAgentsProvider())
68
-
69
-# Create a session for your user
70
-user_id = "user_123"
71
-session = composio.sessions.create(user_id=user_id)
72
-tools = session.tools()
73
-
74
-# For multi-turn, store the session ID in your db and reuse instead of creating another session:
75
-# session_id = session.session_id
76
-# session = composio.use(session_id)
77
-
78
-agent = Agent(
79
- name="Personal Assistant",
80
- instructions="You are a helpful personal assistant. Use Composio tools to take action.",
81
- model="gpt-5.2",
82
- tools=tools,
83
-)
84
-
85
-# Memory for multi-turn conversation
86
-memory = SQLiteSession("conversation")
87
-
88
-print("""
89
-What task would you like me to help you with?
90
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
91
-(Type 'exit' to exit)
92
-Example tasks:
93
- - 'Summarize my emails from today'
94
- - 'List all open issues on the composio github repository'
95
-""")
96
-
97
-while True:
98
- user_input = input("You: ").strip()
99
- if user_input.lower() == "exit":
100
- break
101
-
102
- print("Assistant: ", end="", flush=True)
103
- result = Runner.run_sync(starting_agent=agent, input=user_input, session=memory)
104
- print(f"{result.final_output}\n")
105
-```
106
-</Tab>
107
-<Tab value="TypeScript">
108
-```typescript
109
-import "dotenv/config";
110
-import { Composio } from "@composio/core";
111
-import { Agent, run, MemorySession } from "@openai/agents";
112
-import { OpenAIAgentsProvider } from "@composio/openai-agents";
113
-import { createInterface } from "readline/promises";
114
-
115
-// Initialize Composio with OpenAI Agents provider
116
-const composio = new Composio({ provider: new OpenAIAgentsProvider() });
117
-
118
-// Create a session for your user
119
-const userId = "user_123";
120
-const session = await composio.create(userId);
121
-const tools = await session.tools();
122
-
123
-// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
124
-// const sessionId = session.sessionId;
125
-// const session = await composio.use(sessionId);
126
-
127
-const agent = new Agent({
128
- name: "Personal Assistant",
129
- instructions: "You are a helpful personal assistant. Use Composio tools to take action.",
130
- model: "gpt-5.2",
131
- tools,
132
-});
133
-
134
-const memory = new MemorySession();
135
-const readline = createInterface({ input: process.stdin, output: process.stdout });
136
-
137
-console.log(`
138
-What task would you like me to help you with?
139
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
140
-(Type 'exit' to exit)
141
-Example tasks:
142
- - 'Summarize my emails from today'
143
- - 'List all open issues on the composio github repository'
144
-`);
145
-
146
-while (true) {
147
- const input = (await readline.question("You: ")).trim();
148
- if (input.toLowerCase() === "exit") break;
149
-
150
- process.stdout.write("Assistant: ");
151
- const result = await run(agent, input, { session: memory });
152
- process.stdout.write(`${result.finalOutput}\n`);
153
-}
154
-readline.close();
36
+```bash
37
+uv add python-dotenv composio composio-openai-agents openai-agents
38
```
156
-</Tab>
157
-</Tabs>
158
-</Step>
159
-</Steps>
160
-
161
-</FrameworkOption>
162
-
163
-<FrameworkOption id="claude-agents" name="Claude Agent SDK" logo="/images/providers/anthropic-logo.svg" logoDark="/images/providers/anthropic-logo-dark.svg">
39
165
-<Steps>
166
-<Step>
167
-<StepTitle>Install</StepTitle>
168
-
169
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
170
-<Tab value="Python">
171
-<PackageInstall ecosystem="python" packages="python-dotenv composio composio-claude-agent-sdk claude-agent-sdk" />
172
-</Tab>
173
-<Tab value="TypeScript">
174
-<PackageInstall
175
- packages="dotenv @composio/core @composio/claude-agent-sdk @anthropic-ai/claude-agent-sdk"
176
- comment={[
177
- '@composio/core ships its docs and TypeScript source in the package,',
178
- 'so it is inspectable to coding agents.',
179
- 'Use @composio/slim for a smaller install with the same API.',
180
- ]}
181
-/>
182
-</Tab>
183
-</Tabs>
40
</Step>
185
-
41
<Step>
187
-<StepTitle>Configure API Keys</StepTitle>
42
+<StepTitle>Set your API keys</StepTitle>
43
189
-<Callout type="info">
190
-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).
191
-</Callout>
44
+Create a `.env` file in the project root:
45
46
```bash title=".env"
47
COMPOSIO_API_KEY=your_composio_api_key
195
-ANTHROPIC_API_KEY=your_anthropic_api_key
48
+OPENAI_API_KEY=your_openai_api_key
49
+```
50
+
51
+Keep `.env` out of source control:
52
+
53
+```bash
54
+echo ".env" >> .gitignore
55
```
197
-</Step>
56
57
+</Step>
58
<Step>
200
-<StepTitle>Create session and run agent</StepTitle>
59
+<StepTitle>Add the agent</StepTitle>
60
202
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
203
-<Tab value="Python">
204
-```python
205
-import asyncio
206
-from dotenv import load_dotenv
61
+Replace `main.py` with this complete program:
62
+
63
+```python title="main.py"
64
+import sys
65
+
66
+from agents import Agent, Runner, SQLiteSession
67
from composio import Composio
208
-from composio_claude_agent_sdk import ClaudeAgentSDKProvider
209
-from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, create_sdk_mcp_server, AssistantMessage, TextBlock
68
+from composio_openai_agents import OpenAIAgentsProvider
69
+from dotenv import load_dotenv
70
71
load_dotenv()
72
213
-# Initialize Composio with Claude Agent SDK provider
214
-composio = Composio(provider=ClaudeAgentSDKProvider())
215
-
216
-# Create a session for your user
217
-user_id = "user_123"
218
-session = composio.sessions.create(user_id=user_id)
219
-tools = session.tools()
73
+composio = Composio(provider=OpenAIAgentsProvider())
74
+session = composio.sessions.create(user_id="quickstart-user")
75
221
-# For multi-turn, store the session ID in your db and reuse instead of creating another session:
222
-# session_id = session.session_id
223
-# session = composio.use(session_id)
76
+agent = Agent(
77
+ name="Composio assistant",
78
+ instructions=(
79
+ "Use Composio tools to complete the request. "
80
+ "If a connection is required, share its Connect Link and wait. "
81
+ "Ask for confirmation before creating, updating, or deleting data."
82
+ ),
83
+ tools=session.tools(),
84
+)
85
225
-custom_server = create_sdk_mcp_server(name="composio", version="1.0.0", tools=tools)
86
+conversation = SQLiteSession("quickstart-conversation")
87
227
-async def main():
228
- options = ClaudeAgentOptions(
229
- system_prompt="You are a helpful assistant. Use tools to complete tasks.",
230
- permission_mode="bypassPermissions",
231
- mcp_servers={"composio": custom_server},
88
+def run_task(task: str) -> None:
89
+ result = Runner.run_sync(
90
+ starting_agent=agent,
91
+ input=task,
92
+ session=conversation,
93
)
233
-
234
- async with ClaudeSDKClient(options=options) as client:
235
- print("""
236
-What task would you like me to help you with?
237
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
238
-(Type 'exit' to exit)
239
-Example tasks:
240
- - 'Summarize my emails from today'
241
- - 'List all open issues on the composio github repository'
242
-""")
243
-
244
- while True:
245
- user_input = input("You: ").strip()
246
- if user_input.lower() == "exit":
247
- break
248
-
249
- await client.query(user_input)
250
- print("Claude: ", end="", flush=True)
251
- async for message in client.receive_response():
252
- if isinstance(message, AssistantMessage):
253
- for block in message.content:
254
- if isinstance(block, TextBlock):
255
- print(block.text, end="", flush=True)
256
- print()
257
-
258
-asyncio.run(main())
259
-```
260
-</Tab>
261
-<Tab value="TypeScript">
262
-```typescript
263
-import "dotenv/config";
264
-import { Composio } from "@composio/core";
265
-import { ClaudeAgentSDKProvider } from "@composio/claude-agent-sdk";
266
-import { createSdkMcpServer, query } from "@anthropic-ai/claude-agent-sdk";
267
-import { createInterface } from "readline/promises";
268
-
269
-// Initialize Composio with Claude Agent SDK provider
270
-const composio = new Composio({ provider: new ClaudeAgentSDKProvider() });
271
-
272
-// Create a session for your user
273
-const userId = "user_123";
274
-const session = await composio.create(userId);
275
-const tools = await session.tools();
276
-
277
-// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
278
-// const sessionId = session.sessionId;
279
-// const session = await composio.use(sessionId);
280
-
281
-const customServer = createSdkMcpServer({
282
- name: "composio",
283
- version: "1.0.0",
284
- tools: tools,
285
-});
286
-
287
-const readline = createInterface({ input: process.stdin, output: process.stdout });
288
-
289
-console.log(`
290
-What task would you like me to help you with?
291
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
292
-(Type 'exit' to exit)
293
-Example tasks:
294
- - 'Summarize my emails from today'
295
- - 'List all open issues on the composio github repository and create a Google Sheet with the issues'
296
-`);
297
-
298
-let isFirstQuery = true;
299
-const options = {
300
- mcpServers: { composio: customServer },
301
- permissionMode: "bypassPermissions" as const,
302
-};
303
-
304
-while (true) {
305
- const input = (await readline.question("You: ")).trim();
306
- if (input.toLowerCase() === "exit") break;
307
-
308
- const queryOptions = isFirstQuery ? options : { ...options, continue: true };
309
- isFirstQuery = false;
310
-
311
- process.stdout.write("Claude: ");
312
- for await (const stream of query({ prompt: input, options: queryOptions })) {
313
- if (stream.type === "assistant") {
314
- for (const block of stream.message.content) {
315
- if (block.type === "text") {
316
- process.stdout.write(block.text);
317
- }
318
- }
319
- }
320
- }
321
- console.log();
322
-}
323
-
324
-readline.close();
94
+ print(f"Assistant: {result.final_output}\n")
95
+
96
+if len(sys.argv) > 1:
97
+ run_task(" ".join(sys.argv[1:]))
98
+else:
99
+ print("Ask me to work with your apps. Type 'exit' to quit.")
100
+ while True:
101
+ task = input("You: ").strip()
102
+ if task.lower() == "exit":
103
+ break
104
+ if task:
105
+ run_task(task)
106
```
326
-</Tab>
327
-</Tabs>
107
+
108
</Step>
329
-</Steps>
109
+<Step>
110
+<StepTitle>Run it</StepTitle>
111
331
-</FrameworkOption>
112
+```bash
113
+uv run main.py
114
+```
115
333
-<FrameworkOption id="vercel-ai" name="Vercel AI SDK" logo="/images/providers/vercel-logo.svg" logoDark="/images/providers/vercel-logo-dark.svg">
116
+To run one task without an interactive prompt, pass it as an argument:
117
335
-<Steps>
336
-<Step>
337
-<StepTitle>Install</StepTitle>
338
-
339
-<PackageInstall
340
- packages="@composio/core @composio/vercel ai @ai-sdk/anthropic"
341
- comment={[
342
- '@composio/core ships its docs and TypeScript source in the package,',
343
- 'so it is inspectable to coding agents.',
344
- 'Use @composio/slim for a smaller install with the same API.',
345
- ]}
346
-/>
347
-</Step>
118
+```bash
119
+uv run main.py "Find the three most recent open issues in composiohq/composio"
120
+```
121
349
-<Step>
350
-<StepTitle>Configure API Keys</StepTitle>
122
+Enter any task that needs an app tool. For example:
123
352
-<Callout type="info">
353
-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).
354
-</Callout>
124
+- `Find the three most recent open issues in a public GitHub repository.`
125
+- `Summarize my unread emails from today.`
126
+- `Turn these release notes into a Linear issue: ...`
127
356
-```bash title=".env"
357
-COMPOSIO_API_KEY=your_composio_api_key
358
-ANTHROPIC_API_KEY=your_anthropic_api_key
359
-```
360
-</Step>
128
+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.
129
362
-<Step>
363
-<StepTitle>Create session and run agent</StepTitle>
364
-
365
-```typescript
366
-import "dotenv/config";
367
-import { anthropic } from "@ai-sdk/anthropic";
368
-import { Composio } from "@composio/core";
369
-import { VercelProvider } from "@composio/vercel";
370
-import { streamText, stepCountIs, type ModelMessage } from "ai";
371
-import { createInterface } from "readline/promises";
372
-
373
-// Initialize Composio with Vercel provider
374
-const composio = new Composio({ provider: new VercelProvider() });
375
-
376
-// Create a session for your user
377
-const userId = "user_123";
378
-const session = await composio.create(userId);
379
-const tools = await session.tools();
380
-
381
-// For multi-turn, store the session ID in your db and reuse instead of calling create() again:
382
-// const sessionId = session.sessionId;
383
-// const session = await composio.use(sessionId);
384
-
385
-const readline = createInterface({ input: process.stdin, output: process.stdout });
386
-
387
-console.log(`
388
-What task would you like me to help you with?
389
-I can use tools like Gmail, GitHub, Linear, Notion, and more.
390
-(Type 'exit' to exit)
391
-Example tasks:
392
- - 'Summarize my emails from today'
393
- - 'List all open issues on the composio github repository'
394
-`);
395
-
396
-const messages: ModelMessage[] = [];
397
-
398
-while (true) {
399
- const input = (await readline.question("You: ")).trim();
400
- if (input.toLowerCase() === "exit") break;
401
-
402
- messages.push({ role: "user", content: input });
403
- process.stdout.write("Assistant: ");
404
-
405
- const result = await streamText({
406
- system: "You are a helpful personal assistant. Use Composio tools to take action.",
407
- model: anthropic("claude-sonnet-4-6"),
408
- messages,
409
- stopWhen: stepCountIs(10),
410
- onStepFinish: (step) => {
411
- for (const toolCall of step.toolCalls) {
412
- process.stdout.write(`\n[Using tool: ${toolCall.toolName}]`);
413
- }
414
- },
415
- tools,
416
- });
417
-
418
- for await (const textPart of result.textStream) {
419
- process.stdout.write(textPart);
420
- }
421
- console.log();
422
-
423
- messages.push(...(await result.response).messages);
424
-}
425
-
426
-readline.close();
427
-```
130
</Step>
131
</Steps>
132
431
-</FrameworkOption>
133
+## What just happened?
134
433
-</QuickstartFlow>
135
+- `OpenAIAgentsProvider` formats Composio tools for OpenAI Agents.
136
+- `composio.sessions.create()` creates a Composio session for `quickstart-user`. The session scopes connections and tool calls to that ID.
137
+- 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).
138
+- `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.
139
+- `SQLiteSession` stores the OpenAI conversation history on disk. It is separate from the Composio session.
140
435
-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.
141
+<Callout type="warn" title="Use your application's user ID in production">
142
+`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.
143
+</Callout>
144
437
-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).
145
+You can inspect the selected tools, inputs, responses, and timing with the [Logs API](/reference/api-reference/logs).
146
439
-## Next
147
+## Adapt the example
148
441
-<Card icon={<Wrench />} title="Configuring Sessions" href="/docs/configuring-sessions">
442
- Restrict toolkits, set custom auth configs, and select connected accounts
443
-</Card>
149
+<Cards>
150
+ <Card title="Use another framework" href="/docs/providers" description="Choose OpenAI, Anthropic, Vercel AI SDK, LangChain, CrewAI, or another supported provider." />
151
+ <Card title="Configure the session" href="/docs/configuring-sessions" description="Restrict toolkits, preload tools, or select connected accounts." />
152
+ <Card title="Design authentication" href="/docs/authentication" description="Add Connect Links and per-user connections to your application." />
153
+ <Card title="Expose an MCP endpoint" href="/docs/sessions-via-mcp" description="Use the same Composio session from an MCP-compatible application." />
154
+</Cards>
docs/content/docs/sandbox/meta.json
+2
-2
@@ -1,6 +1,6 @@
1
{
2
- "title": "Sandbox (prev Workbench)",
3
- "defaultOpen": true,
2
+ "title": "Sandboxes",
3
+ "defaultOpen": false,
4
"pages": [
5
"remote",
6
"local"
docs/content/docs/security/meta.json
new
+8
@@ -0,0 +1,8 @@
1
+{
2
+ "title": "Security and data",
3
+ "defaultOpen": false,
4
+ "pages": [
5
+ "overview",
6
+ "data-retention"
7
+ ]
8
+}
docs/content/docs/sessions-via-mcp.mdx
+7
-3
@@ -1,12 +1,16 @@
1
---
2
title: Using sessions via MCP
3
-description: Connect any MCP-compatible client to a Composio session
3
+description: Build an application that exposes a Composio session to an MCP-compatible client
4
keywords: [mcp, model context protocol, sessions, remote server, hosted mcp]
5
---
6
7
-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.
7
+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.
8
9
-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.
9
+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.
10
+
11
+<Callout type="info" title="Connecting an existing agent instead?">
12
+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).
13
+</Callout>
14
15
<Callout type="info">
16
Want to bring tools from your own remote MCP server into Composio instead? See [Custom MCP](/docs/extending-sessions/custom-mcp).
docs/content/docs/setting-up-triggers/meta.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
- "title": "Setting up triggers",
2
+ "title": "Set up triggers",
3
"pages": [
4
"creating-triggers",
5
"subscribing-to-events",
docs/content/docs/tools-direct/executing-tools.mdx
+2
-2
@@ -1,6 +1,6 @@
1
---
2
-title: Executing Tools
3
-description: Learn how to execute Composio tools with different providers and frameworks
2
+title: Executing tools directly
3
+description: Maintain legacy code that calls composio.tools.execute() and other direct tool APIs
4
keywords: [execute, run, tool calling, function calling, direct execution]
5
llmGuardrails: "direct-execution"
6
legacy: true
docs/content/docs/tools-direct/meta.json
+1
-1
@@ -1,5 +1,5 @@
1
{
2
- "title": "Tools",
2
+ "title": "Direct execution",
3
"defaultOpen": false,
4
"pages": [
5
"fetching-tools",
docs/lib/home-navigation.ts
new
+82
@@ -0,0 +1,82 @@
1
+export interface HomeIntentLink {
2
+ title: string;
3
+ description: string;
4
+ href: string;
5
+}
6
+
7
+export interface HomeIntent {
8
+ id: 'build' | 'use';
9
+ audience: 'For you' | 'Platform';
10
+ title: string;
11
+ description: string;
12
+ links: HomeIntentLink[];
13
+}
14
+
15
+export const HOME_INTENTS: HomeIntent[] = [
16
+ {
17
+ id: 'build',
18
+ audience: 'Platform',
19
+ title: 'Build with Composio',
20
+ description: 'Add Composio tools and authentication to your own agent or application.',
21
+ links: [
22
+ {
23
+ title: 'Quickstart',
24
+ description: 'Build an agent that discovers tools and works across your apps.',
25
+ href: '/docs/quickstart',
26
+ },
27
+ {
28
+ title: 'Framework guides',
29
+ description: 'Use OpenAI, Anthropic, Vercel AI SDK, or another framework.',
30
+ href: '/docs/providers',
31
+ },
32
+ {
33
+ title: 'Sessions via MCP',
34
+ description: 'Expose a Composio session through a hosted MCP endpoint.',
35
+ href: '/docs/sessions-via-mcp',
36
+ },
37
+ ],
38
+ },
39
+ {
40
+ id: 'use',
41
+ audience: 'For you',
42
+ title: 'Use Composio',
43
+ description: 'Connect an existing coding agent or terminal to Composio.',
44
+ links: [
45
+ {
46
+ title: 'Agent plugins',
47
+ description: 'Install the native Composio plugin for Codex or Claude Code.',
48
+ href: '/docs/agent-plugins',
49
+ },
50
+ {
51
+ title: 'Composio CLI',
52
+ description: 'Search, connect, and run tools from your terminal.',
53
+ href: '/docs/cli',
54
+ },
55
+ {
56
+ title: 'Connect over MCP',
57
+ description: 'Use Composio with Cursor or another existing MCP client.',
58
+ href: '/docs/composio-connect',
59
+ },
60
+ ],
61
+ },
62
+];
63
+
64
+export function homeIntentAnchor(title: string): string {
65
+ return title.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/(^-|-$)/g, '');
66
+}
67
+
68
+export function homeIntentsToMarkdown(): string {
69
+ const sections = HOME_INTENTS.map(intent => {
70
+ const links = intent.links
71
+ .map(link => `- [${link.title}](${link.href}): ${link.description}`)
72
+ .join('\n');
73
+
74
+ return `### ${intent.title}\n\n**${intent.audience}**\n\n${intent.description}\n\n${links}`;
75
+ }).join('\n\n');
76
+
77
+ return `## Two ways to start\n\n${sections}`;
78
+}
79
+
80
+export function replaceHomeNavigationMarkdown(content: string): string {
81
+ return content.replace(/<HomeSurfaces\s*\/>/g, homeIntentsToMarkdown());
82
+}
docs/lib/source.ts
+4
-1
@@ -11,6 +11,7 @@ import { transformDeprecatedApiSidebarNode } from './deprecated-api-sidebar';
11
import { API_BASE_URLS, detectApiVersion, type ApiVersion } from './api-version';
12
import { apiVersionPointer } from './api-version-guidance';
13
import { apiEndpointsSchema } from './api-endpoints-table-schema';
14
+import { replaceHomeNavigationMarkdown } from './home-navigation';
15
16
/**
17
* True if a reference URL belongs to an intentionally-hidden API tag
@@ -261,6 +262,8 @@ export function mdxToCleanMarkdown(content: string, url?: string): string {
262
)
263
);
264
265
+ result = replaceHomeNavigationMarkdown(result);
266
+
267
// Convert YouTube to link
268
result = result.replace(
269
/<YouTube\s+id="([^"]+)"\s+title="([^"]+)"\s*\/>/g,
@@ -321,7 +324,7 @@ export function mdxToCleanMarkdown(content: string, url?: string): string {
324
result = result.replace(/<Step>\s*###\s*(.+)/g, '#### $1');
325
result = result.replace(/<\/?Steps>/g, '');
326
result = result.replace(/<\/?Step>/g, '');
324
- result = result.replace(/^(\s*#{1,6})\s*#\s+(.+)$/gm, '$1 $2');
327
+ result = result.replace(/^(\s*#{1,6})\s+#\s+(.+)$/gm, '$1 $2');
328
result = result.replace(/^\s*#\s*$/gm, '');
329
330
result = result.replace(/<FrameworkOption[\s\S]*?name="([^"]*)"[\s\S]*?>/g, '\n## $1\n');
docs/tests/static/home-navigation.test.ts
new
+65
@@ -0,0 +1,65 @@
1
+import { describe, expect, test } from 'bun:test';
2
+
3
+import {
4
+ HOME_INTENTS,
5
+ homeIntentAnchor,
6
+ homeIntentsToMarkdown,
7
+ replaceHomeNavigationMarkdown,
8
+} from '../../lib/home-navigation';
9
+import { mdxToCleanMarkdown } from '../../lib/source';
10
+
11
+describe('Welcome navigation', () => {
12
+ test('separates build paths from use paths', () => {
13
+ expect(HOME_INTENTS.map(intent => intent.title)).toEqual([
14
+ 'Build with Composio',
15
+ 'Use Composio',
16
+ ]);
17
+ expect(HOME_INTENTS[0].links.map(link => link.href)).toEqual([
18
+ '/docs/quickstart',
19
+ '/docs/providers',
20
+ '/docs/sessions-via-mcp',
21
+ ]);
22
+ expect(HOME_INTENTS[1].links.map(link => link.href)).toEqual([
23
+ '/docs/agent-plugins',
24
+ '/docs/cli',
25
+ '/docs/composio-connect',
26
+ ]);
27
+ });
28
+
29
+ test('serializes the same paths for agent-readable Markdown', () => {
30
+ const markdown = homeIntentsToMarkdown();
31
+
32
+ for (const intent of HOME_INTENTS) {
33
+ expect(markdown).toContain(`### ${intent.title}`);
34
+ expect(markdown).toContain(`**${intent.audience}**`);
35
+ for (const link of intent.links) {
36
+ expect(markdown).toContain(`[${link.title}](${link.href})`);
37
+ }
38
+ }
39
+
40
+ expect(replaceHomeNavigationMarkdown('<HomeSurfaces />')).toBe(markdown);
41
+ expect(mdxToCleanMarkdown('<HomeSurfaces />')).toContain('## Two ways to start');
42
+ expect(mdxToCleanMarkdown('<HomeSurfaces />')).toContain('### Build with Composio');
43
+ expect(markdown).not.toContain('<HomeSurfaces');
44
+ expect(markdown.toLowerCase()).not.toContain('skills');
45
+ expect(markdown).toContain('native Composio plugin for Codex or Claude Code');
46
+ });
47
+
48
+ test('keeps rendered headings linkable and badges visible', async () => {
49
+ const source = await Bun.file(
50
+ new URL('../../components/home-surfaces.tsx', import.meta.url)
51
+ ).text();
52
+
53
+ expect(source).toContain('id="two-ways-to-start"');
54
+ for (const intent of HOME_INTENTS) {
55
+ expect(homeIntentAnchor(intent.title)).toMatch(/^[a-z0-9-]+$/);
56
+ }
57
+ expect(source).toContain('id={homeIntentAnchor(intent.title)}');
58
+ expect(source).toContain('background: PLATFORM_BADGE_GRADIENT');
59
+ expect(source).toContain("backgroundClip: 'text'");
60
+ expect(source).toContain("WebkitTextFillColor: 'transparent'");
61
+ expect(source).toContain("mask: 'linear-gradient(#fff 0 0) content-box");
62
+ expect(source).toContain('text-[#0007cd] dark:text-[#4d6fff]');
63
+ expect(source).toContain('audience-badge-platform-border');
64
+ });
65
+});
docs/tests/static/navigation.test.ts
+35
@@ -42,6 +42,41 @@ async function exists(path: string): Promise<boolean> {
42
}
43
44
describe("Navigation - meta.json validity", () => {
45
+ test("root navigation separates current and legacy paths", async () => {
46
+ const metaPath = join(CONTENT_DIR, "meta.json");
47
+ const meta = JSON.parse(await readFile(metaPath, "utf-8"));
48
+ const pages = meta.pages as string[];
49
+ const separators = pages.filter(isSeparator);
50
+
51
+ expect(separators).toEqual([
52
+ "---Get Started---",
53
+ "---Core concepts---",
54
+ "---Guides---",
55
+ "---Direct execution (legacy)---",
56
+ "---Migration and security---",
57
+ ]);
58
+
59
+ expect(pages.slice(1, pages.indexOf("---Core concepts---"))).toEqual([
60
+ "index",
61
+ "quickstart",
62
+ "providers",
63
+ "agent-plugins",
64
+ "cli",
65
+ "composio-connect",
66
+ ]);
67
+
68
+ expect(
69
+ pages.slice(
70
+ pages.indexOf("---Direct execution (legacy)---") + 1,
71
+ pages.indexOf("---Migration and security---")
72
+ )
73
+ ).toEqual([
74
+ "sessions-vs-direct-execution",
75
+ "tools-direct",
76
+ "auth-configuration",
77
+ ]);
78
+ });
79
+
80
test("root meta.json entries all resolve to files or directories", async () => {
81
const metaPath = join(CONTENT_DIR, "meta.json");
82
const meta = JSON.parse(await readFile(metaPath, "utf-8"));
docs/tests/static/quickstart.test.ts
new
+45
@@ -0,0 +1,45 @@
1
+import { describe, expect, test } from 'bun:test';
2
+import { readFile } from 'fs/promises';
3
+import { join } from 'path';
4
+
5
+const QUICKSTART_PATH = join(import.meta.dir, '../../content/docs/quickstart.mdx');
6
+
7
+describe('Quickstart default path', () => {
8
+ test('presents one linear OpenAI Agents and Python flow before adaptations', async () => {
9
+ const content = await readFile(QUICKSTART_PATH, 'utf-8');
10
+ const milestones = [
11
+ '<StepTitle>Create the project</StepTitle>',
12
+ '<StepTitle>Install the packages</StepTitle>',
13
+ '<StepTitle>Set your API keys</StepTitle>',
14
+ '<StepTitle>Add the agent</StepTitle>',
15
+ '<StepTitle>Run it</StepTitle>',
16
+ '## What just happened?',
17
+ '## Adapt the example',
18
+ ];
19
+ const positions = milestones.map(milestone => content.indexOf(milestone));
20
+
21
+ expect(positions.every(position => position >= 0)).toBe(true);
22
+ expect([...positions].sort((a, b) => a - b)).toEqual(positions);
23
+ expect(content).not.toContain('<QuickstartFlow>');
24
+ expect(content).not.toContain('<FrameworkOption');
25
+ expect(content).not.toContain('Finish this path');
26
+ expect(content).not.toContain('respond exactly');
27
+ });
28
+
29
+ test('supports interactive and one-shot tasks', async () => {
30
+ const content = await readFile(QUICKSTART_PATH, 'utf-8');
31
+
32
+ expect(content).toContain('uv init --app --python 3.10 composio-quickstart');
33
+ expect(content).toContain(
34
+ 'uv add python-dotenv composio composio-openai-agents openai-agents'
35
+ );
36
+ expect(content).toContain('session = composio.sessions.create(user_id="quickstart-user")');
37
+ expect(content).toContain('if len(sys.argv) > 1:');
38
+ expect(content).toContain('run_task(" ".join(sys.argv[1:]))');
39
+ expect(content).toContain('task = input("You: ").strip()');
40
+ expect(content).toContain('uv run main.py "Find the three most recent open issues');
41
+ expect(content).toContain('the agent gives you a Connect Link');
42
+ expect(content).toContain('a small set of meta tools for finding, connecting, and running app tools');
43
+ expect(content).toContain('composio.use(session_id)');
44
+ });
45
+});
docs/tests/static/start-routing.test.ts
new
+56
@@ -0,0 +1,56 @@
1
+import { describe, expect, test } from 'bun:test';
2
+
3
+import { HOME_INTENTS } from '../../lib/home-navigation';
4
+
5
+const read = (path: string) => Bun.file(new URL(`../../${path}`, import.meta.url)).text();
6
+
7
+describe('getting-started routing policy', () => {
8
+ test('publishes native plugins for both supported agent hosts', async () => {
9
+ const plugins = await read('content/docs/agent-plugins.mdx');
10
+
11
+ expect(plugins).toContain('Agent plugins let Codex and Claude Code use Composio');
12
+ expect(plugins).toContain('composio setup --target codex');
13
+ expect(plugins).toContain('composio setup --target claude');
14
+ expect(plugins).toContain('codex plugin marketplace add');
15
+ expect(plugins).toContain('/plugin marketplace add');
16
+ expect(plugins).toContain('composio search');
17
+ expect(plugins).toContain('composio link');
18
+ expect(plugins).toContain('composio execute');
19
+ expect(plugins).toContain('composio --install-skill composio-cli claude');
20
+ expect(plugins).toContain('composio --install-skill composio-cli codex');
21
+ expect(plugins).toContain('composio setup --target auto --yes');
22
+ expect(plugins).toContain('### Codex');
23
+ expect(plugins).toContain('### Claude Code');
24
+ expect(plugins).not.toContain('<Tabs');
25
+ });
26
+
27
+ test('keeps native plugins ahead of CLI and explicit MCP on Welcome', () => {
28
+ expect(HOME_INTENTS[1].links.map(link => link.href)).toEqual([
29
+ '/docs/agent-plugins',
30
+ '/docs/cli',
31
+ '/docs/composio-connect',
32
+ ]);
33
+ });
34
+
35
+ test('keeps progressive authentication guides in the human and agent indexes', async () => {
36
+ const [authentication, llmsRoute] = await Promise.all([
37
+ read('content/docs/authentication.mdx'),
38
+ read('app/llms.txt/route.ts'),
39
+ ]);
40
+ const guides = [
41
+ 'manually-authenticating',
42
+ 'managing-multiple-connected-accounts',
43
+ 'shared-connections',
44
+ 'importing-existing-connections',
45
+ 'custom-app-vs-managed-app',
46
+ 'programmatic-auth-configs',
47
+ 'controlling-scopes',
48
+ 'white-labeling-authentication',
49
+ ];
50
+
51
+ for (const guide of guides) {
52
+ expect(authentication).toContain(`href="/docs/${guide}"`);
53
+ expect(llmsRoute).toContain(`'/docs/${guide}'`);
54
+ }
55
+ });
56
+});