Repository: ComposioHQ/composio

Stars: 27813

CLAUDE.md Copy Chapter

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Overview Copy Chapter

This is the Composio SDK v3 repository containing both TypeScript and Python SDKs. The main development focus is on the TypeScript SDK located in /ts/ directory. The project uses a monorepo structure with multiple packages and examples.

Memories and Notes Copy Chapter

- For documentation tasks, refer to docs/CLAUDE.md

Effect.ts Reference Source Copy Chapter

The CLI package (@composio/cli) is built on the Effect.ts ecosystem. A local copy of the Effect source code is available as a git submodule:

- Location: ts/vendor/effect/
- Repo: Effect-TS/effect
- Branch: main

When working on CLI code, reference the Effect source for accurate patterns:
- ts/vendor/effect/packages/effect/src/ — core Effect runtime
- ts/vendor/effect/packages/cli/src/ — @effect/cli (Command, Options, Args)
- ts/vendor/effect/packages/platform/src/ — @effect/platform (FileSystem, Terminal)

Important: The submodule is for read-only reference only. Do not modify files in ts/vendor/. The CLI's actual dependencies come from npm via pnpm install.

Clack Reference Source Copy Chapter

The CLI uses @clack/prompts for interactive terminal UI. A local copy of the Clack source code is available as a git submodule:

- Location: ts/vendor/clack/
- Repo: bombshell-dev/clack

When working on CLI prompts and terminal UI, reference the Clack source for accurate APIs:
- ts/vendor/clack/packages/prompts/src/ — @clack/prompts (high-level API: text, select, confirm, spinner, etc.)
- ts/vendor/clack/packages/core/src/ — @clack/core (low-level primitives)

See ts/packages/cli/AGENTS.md for detailed Clack usage guidelines.

Important: The submodule is for read-only reference only. Do not modify files in ts/vendor/. The CLI's actual @clack/prompts dependency comes from npm via pnpm install.

Common Development Commands Copy Chapter

Build and Development Copy Section

Build all packages

pnpm build
Build only TypeScript packages  

pnpm build:packages
Clean build artifacts

pnpm clean
pnpm clean:workspace
Lint code

pnpm lint
pnpm lint:fix
Format code

pnpm format
Run tests

pnpm test

Package Management Copy Section

Install dependencies

pnpm install
Check peer dependencies

pnpm check:peer-deps
Update peer dependencies  

pnpm update:peer-deps

Creating New Components Copy Section

Create a new provider

pnpm create:provider <provider-name> [--agentic]
Create a new example

pnpm create:example <example-name>

Release Management Copy Section

Create changeset for releases

pnpm changeset
Version packages

pnpm changeset:version
Publish packages

pnpm changeset:release

Project Architecture Copy Chapter

Repository Structure Copy Section

composio/
├── ts/                      # TypeScript SDK (main development)
│   ├── packages/
│   │   ├── core/           # Core SDK functionality
│   │   ├── providers/      # AI provider integrations (OpenAI, Anthropic, etc.)
│   │   ├── cli/           # Command-line interface
│   │   ├── json-schema-to-zod/ # Schema conversion utility
│   │   └── ts-builders/   # TypeScript code generation utilities
│   └── examples/          # Usage examples for different providers
├── python/                # Python SDK
├── docs/                  # Documentation (Fumadocs)
└── examples/              # Cross-platform examples

Core Packages Copy Section

@composio/core - Main SDK functionality:
- src/composio.ts - Main Composio class
- src/models/ - Core models (Tools, Toolkits, ConnectedAccounts, etc.)
- src/provider/ - Base provider implementations
- src/services/ - Internal services (telemetry, pusher)
- src/types/ - TypeScript type definitions
- src/utils/ - Utility functions and helpers

Provider Packages - AI integrations:
- @composio/openai - OpenAI integration
- @composio/anthropic - Anthropic integration
- @composio/google - Google GenAI integration
- @composio/langchain - LangChain integration
- @composio/vercel - Vercel AI integration
- @composio/mastra - Mastra integration

Key Concepts Copy Section

Tools - Individual functions that can be executed (e.g., GITHUB_CREATE_REPO, GMAIL_SEND_EMAIL)

Toolkits - Collections of related tools grouped by service (e.g., github, gmail, slack)

Connected Accounts - User authentication/authorization for external services

Auth Configs - Configuration for different authentication methods

Custom Tools - User-defined tools with custom logic

Providers - Integrations with AI frameworks (OpenAI, Anthropic, etc.)

Modifiers - Middleware to transform tool inputs/outputs

Development Workflow Copy Chapter

For Tool Development Copy Section

For Provider Development Copy Section

Testing Copy Section

Code Quality Copy Section

Environment Variables Copy Chapter

COMPOSIO_API_KEY          # Required: Your Composio API key
COMPOSIO_BASE_URL         # Optional: Custom API base URL
COMPOSIO_LOG_LEVEL        # Optional: Logging level (silent, error, warn, info, debug)
COMPOSIO_DISABLE_TELEMETRY # Optional: Set to "true" to disable telemetry
DEVELOPMENT               # Development mode flag
CI                       # CI environment flag

Key Files and Locations Copy Chapter

- Main SDK Entry: ts/packages/core/src/index.ts
- Core Composio Class: ts/packages/core/src/composio.ts
- Type Definitions: ts/packages/core/src/types/
- Error Classes: ts/packages/core/src/errors/
- Examples: ts/examples/ and examples/
- Documentation: docs/
- Build Configs: turbo.jsonc, tsconfig.base.json, tsdown.config.base.ts
- E2E Tests: ts/e2e-tests/

Maintenance Tasks Copy Chapter

When Updating GitHub Actions Copy Section

When modifying files in .github/workflows/, update the "Prerequisites" section in ts/docs/internal/release.md with the current tool versions:

- Node.js: cat .nvmrc
- Bun: cat .bun-version
- pnpm: cat package.json | jq -r .packageManager | cut -d'@' -f2

Testing Commands Copy Chapter

Run all tests

pnpm test
Run tests for core package only

cd ts/packages/core && pnpm test
Run tests with UI

pnpm test:ui

TypeScript E2E Tests Copy Section

E2E tests for @composio/core are located in ts/e2e-tests/ and test runtime compatibility across different JavaScript environments.

Run all e2e tests (Node.js + Deno + Cloudflare)

pnpm test:e2e
Run only Node.js e2e tests (CJS/ESM compatibility, runs in Docker)

pnpm test:e2e:node
Run only Deno e2e tests (npm: specifier compatibility, runs in Docker)

pnpm test:e2e:deno
Run only Cloudflare Workers e2e tests

pnpm test:e2e:cloudflare
Run Node.js tests with a specific Node version

COMPOSIO_E2E_NODE_VERSION=22.12.0 pnpm test:e2e:node
Run Deno tests with a specific Deno version

COMPOSIO_E2E_DENO_VERSION=2.6.7 pnpm test:e2e:deno

E2E Test Structure:

ts/e2e-tests/
├── _utils/                    # Shared Docker infrastructure
├── runtimes/
│   ├── node/                  # Node.js runtime tests
│   │   ├── cjs-basic/         # CommonJS compatibility
│   │   └── esm-basic/         # ESM compatibility
│   ├── deno/                  # Deno runtime tests
│   │   └── esm-basic/         # npm: specifier compatibility
│   └── cloudflare/            # Cloudflare runtime tests
│       └── cf-workers-basic/  # Cloudflare Workers tests
└── README.md                  # E2E test documentation

Note: When adding new e2e tests, update ts/e2e-tests/README.md with the new test information.

Common Patterns Copy Chapter

Tool Execution Copy Section

const composio = new Composio({ apiKey: 'your-key' });
const result = await composio.tools.execute('TOOL_NAME', {
  userId: 'user-id',
  arguments: { / tool args / }
});

Provider Integration Copy Section

import { OpenAIProvider } from '@composio/openai';
const provider = new OpenAIProvider({ apiKey: 'openai-key' });
const tools = await composio.tools.get('user-id', { toolkits: ['github'] });
const wrappedTools = provider.wrapTools(tools);

Custom Tool Creation Copy Section

import { z } from 'zod';
const customTool = await composio.tools.createCustomTool({
  name: 'My Tool',
  description: 'Tool description',
  slug: 'MY_TOOL',
  inputParams: z.object({
    param: z.string().describe('Parameter description')
  }),
  execute: async (input) => {
    // Implementation
    return {
      data: { result: input.param },
      error: null,
      successful: true
    };
  }
});

This monorepo uses pnpm workspaces and Turbo for efficient builds and development.

Python SDK Development Copy Chapter

Setup Copy Section

Environment Setup Copy Section

Create and setup Python development environment

cd python
make env
source .venv/bin/activate

Python Development Commands Copy Section

Setup environment (creates virtual env with all dependencies)

make env
Sync dependencies (when in an existing environment)

make sync
Install provider packages

make provider
Format code using ruff

make fmt
Or directly: nox -s fmt
Check linting and type issues

make chk
Or directly: nox -s chk
Fix linting issues

nox -s fix
Run tests (requires implementing tst session)

make tst
Or directly: nox -s tst
Run sanity tests (requires implementing snt session)  

make snt
Or directly: nox -s snt
Clean build artifacts

make clean-build
Bump version

make bump
Build packages

make build

Python Project Structure Copy Section

python/
├── composio/           # Main SDK package
├── providers/          # Provider implementations
├── tests/             # Test suite
├── examples/          # Usage examples
├── scripts/           # Development scripts
├── config/            # Configuration files
│   ├── pytest.ini     # Pytest configuration
│   ├── mypy.ini       # MyPy type checking config
│   ├── ruff.toml     # Ruff linter/formatter config
│   └── codecov.yml   # Code coverage config
├── Makefile          # Development shortcuts
├── noxfile.py        # Nox automation sessions
└── pyproject.toml    # Project configuration

Python Code Quality Copy Section

Python Testing Copy Section

Run tests with pytest markers

pytest -m core        # Run core tests only
pytest -m openai      # Run OpenAI provider tests
pytest -m langchain   # Run LangChain provider tests
pytest -m agno       # Run Agno provider tests

Python Package Dependencies Copy Section

Python Environment Variables Copy Section

OPENAI_API_KEY    # Required for OpenAI provider examples

README.md Copy Chapter

<div align="center">

<img src="https://raw.githubusercontent.com/ComposioHQ/composio/next/public/cover.png" alt="Composio Logo" width="auto" height="auto" style="margin-bottom: 20px;"/>

Composio SDK

Skills that evolve for your Agents

🌐 Website • 📚 Documentation

</div>

This repository contains the official Software Development Kits (SDKs) for Composio, providing seamless integration capabilities for Python and Typescript Agentic Frameworks and Libraries.

Getting Started Copy Chapter

TypeScript SDK Installation Copy Section

Using npm

npm install @composio/core
Using yarn

yarn add @composio/core
Using pnpm

pnpm add @composio/core

#### Quick start:

import { Composio } from '@composio/core';
// Initialize the SDK
const composio = new Composio({
  // apiKey: 'your-api-key',
});

#### Simple Agent with OpenAI Agents

npm install @composio/openai-agents @openai/agents

import { Composio } from '@composio/core';
import { OpenAIAgentsProvider } from '@composio/openai-agents';
import { Agent, run } from '@openai/agents';
const composio = new Composio({
  provider: new OpenAIAgentsProvider(),
});
const userId = '[email protected]';
const tools = await composio.tools.get(userId, {
  toolkits: ['HACKERNEWS'],
});
const agent = new Agent({
  name: 'Hackernews assistant',
  tools: tools,
});
const result = await run(agent, 'What is the latest hackernews post about?');
console.log(JSON.stringify(result.finalOutput, null, 2));
// will return the response from the agent with data from HACKERNEWS API.

Python SDK Installation Copy Section

Using pip

pip install composio
Using poetry

poetry add composio

#### Quick start:

from composio import Composio
composio = Composio(
  # api_key="your-api-key",
)

#### Simple Agent with OpenAI Agents

pip install composio_openai_agents openai-agents

import asyncio
from agents import Agent, Runner
from composio import Composio
from composio_openai_agents import OpenAIAgentsProvider
Initialize Composio client with OpenAI Agents Provider

composio = Composio(provider=OpenAIAgentsProvider())
user_id = "[email protected]"
tools = composio.tools.get(user_id=user_id, toolkits=["HACKERNEWS"])
Create an agent with the tools

agent = Agent(
    name="Hackernews Agent",
    instructions="You are a helpful assistant.",
    tools=tools,
)
Run the agent

async def main():
    result = await Runner.run(
        starting_agent=agent,
        input="What's the latest Hackernews post about?",
    )
    print(result.final_output)
asyncio.run(main())
will return the response from the agent with data from HACKERNEWS API.

For more detailed usage instructions and examples, please refer to each SDK's specific documentation.

Open API Specification Copy Section

To update the OpenAPI specifications used for generating SDK documentation:

Pull the latest API specifications from the backend

pnpm api:pull

This command pulls the OpenAPI specification from https://backend.composio.dev/api/v3/openapi.json and updates the local API documentation files.

This is pulled automatically with build step.

Available SDKs Copy Chapter

TypeScript SDK (/ts) Copy Section

The TypeScript SDK provides a modern, type-safe way to interact with Composio's services. It's designed for both Node.js and browser environments, offering full TypeScript support with comprehensive type definitions.

For detailed information about the TypeScript SDK, please refer to the TypeScript SDK Documentation.

Python SDK (/python) Copy Section

The Python SDK offers a Pythonic interface to Composio's services, making it easy to integrate Composio into your Python applications. It supports Python 3.10+ and follows modern Python development practices.

For detailed information about the Python SDK, please refer to the Python SDK Documentation.

Provider Support Copy Chapter

The following table shows which AI frameworks and platforms are supported in each SDK:

| Provider | TypeScript | Python |
|----------|:----------:|:------:|
| OpenAI | ✅ | ✅ |
| OpenAI Agents | ✅ | ✅ |
| Anthropic | ✅ | ✅ |
| LangChain | ✅ | ✅ |
| LangGraph | ✅* | ✅ |
| LlamaIndex | ✅ | ✅ |
| Vercel AI SDK | ✅ | ❌ |
| Google Gemini | ✅ | ✅ |
| Google ADK | ❌ | ✅ |
| Mastra | ✅ | ❌ |
| Cloudflare Workers AI | ✅ | ❌ |
| CrewAI | ❌ | ✅ |
| AutoGen | ❌ | ✅ |

\ LangGraph in TypeScript is supported via the @composio/langchain package.*

Don't see your provider? Learn how to build a custom provider to integrate with any AI framework.

Packages Copy Chapter

Core Packages Copy Section

| Package | Version |
|---------|---------|
| TypeScript | |
| @composio/core | !npm version |
| Python | |
| composio | !PyPI version |

Provider Packages Copy Section

| Package | Version |
|---------|---------|
| TypeScript | |
| @composio/openai | !npm version |
| @composio/openai-agents | !npm version |
| @composio/anthropic | !npm version |
| @composio/langchain | !npm version |
| @composio/llamaindex | !npm version |
| @composio/vercel | !npm version |
| @composio/google | !npm version |
| @composio/mastra | !npm version |
| @composio/cloudflare | !npm version |
| Python | |
| composio-openai | !PyPI version |
| composio-openai-agents | !PyPI version |
| composio-anthropic | !PyPI version |
| composio-langchain | !PyPI version |
| composio-langgraph | !PyPI version |
| composio-llamaindex | !PyPI version |
| composio-crewai | !PyPI version |
| composio-autogen | !PyPI version |
| composio-gemini | !PyPI version |
| composio-google | !PyPI version |
| composio-google-adk | !PyPI version |

Utility Packages Copy Section

| Package | Version |
|---------|---------|
| @composio/json-schema-to-zod | !npm version |
| @composio/ts-builders | !npm version |

_if you are looking for the older sdk, you can find them here_

Rube Copy Chapter

Rube is a Model Context Protocol (MCP) server built with Composio. It connects your AI tools to 500+ apps like Gmail, Slack, GitHub, and Notion. Simply install it in your AI client, authenticate once with your apps, and start asking your AI to perform real actions like "Send an email" or "Create a task."

It integrates with major AI clients like Cursor, Claude Desktop, VS Code, Claude Code and any custom MCP‑compatible client. You can switch between these clients and your integrations follow you.

Contributing Copy Chapter

We welcome contributions to both SDKs! Please read our contribution guidelines before submitting pull requests.

License Copy Chapter

This project is licensed under the MIT License - see the LICENSE file for details.

Support Copy Chapter

If you encounter any issues or have questions about the SDKs:

- Open an issue in this repository
- Contact our support team
- Check our documentation