# Repository: ComposioHQ/composio
# Stars: 27813

## CLAUDE.md

# CLAUDE.md

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

## Overview

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

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

## Effect.ts Reference Source

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](https://github.com/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

The CLI uses [`@clack/prompts`](https://github.com/bombshell-dev/clack) 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](https://github.com/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

### Build and Development
```bash
# 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
```bash
# Install dependencies
pnpm install

# Check peer dependencies
pnpm check:peer-deps

# Update peer dependencies  
pnpm update:peer-deps
```

### Creating New Components
```bash
# Create a new provider
pnpm create:provider <provider-name> [--agentic]

# Create a new example
pnpm create:example <example-name>
```

### Release Management
```bash
# Create changeset for releases
pnpm changeset

# Version packages
pnpm changeset:version

# Publish packages
pnpm changeset:release
```

## Project Architecture

### Repository Structure
```
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

**@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

**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

### For Tool Development
1. Tools are auto-generated from OpenAPI specifications
2. Custom tools can be created using the Custom Tools API
3. Tool execution happens through the main Composio class

### For Provider Development
1. Use `pnpm create:provider <name>` to scaffold new providers
2. Implement required methods: `wrapTool`, `wrapTools`
3. For agentic providers, also implement execution handlers
4. Add comprehensive tests and documentation

### Testing
- Unit tests use Vitest
- Run tests with `pnpm test`
- Tests are located in `test/` directories within each package
- Mock implementations are available in `test/utils/mocks/`

### Code Quality
- ESLint configuration in `eslint.config.mjs`
- Prettier for code formatting
- TypeScript strict mode enabled
- Comprehensive TSDoc documentation required
- Husky pre-commit hooks for quality checks

## Environment Variables

```bash
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

- **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

### When Updating GitHub Actions

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

```bash
# 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

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

```bash
# 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

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

### Provider Integration
```typescript
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
```typescript
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

### Setup
The Python SDK is located in the `/python/` directory and uses `uv` for dependency management and `nox` for automation.

### Environment Setup
```bash
# Create and setup Python development environment
cd python
make env
source .venv/bin/activate
```

### Python Development Commands
```bash
# 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
```
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
- **Formatter**: Ruff (Black-compatible, 88 char line length)
- **Linter**: Ruff with custom configuration
- **Type Checker**: mypy with strict optional typing
- **Test Framework**: pytest with custom markers (core, openai, langchain, agno)
- **Python Version**: >=3.10, <4
- **Dependency Managers**: uv

### Python Testing
```bash
# 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
- Core: `pysher`, `pydantic>=2.6.4`, `composio-client==1.4.0`, `typing-extensions>=4.0.0`, `openai`
- Dev: `nox`, `pytest`, `ruff`, `langchain_openai`, `fastapi`, `twine`, `click`, `semver`

### Python Environment Variables
Same as TypeScript SDK, with additional:
```bash
OPENAI_API_KEY    # Required for OpenAI provider examples
```

## README.md


<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](https://composio.dev) • [📚 Documentation](https://docs.composio.dev)

[![GitHub Stars](https://img.shields.io/github/stars/ComposioHQ/composio?style=social)](https://github.com/ComposioHQ/composio/stargazers)
[![PyPI Downloads](https://img.shields.io/pypi/dm/composio?label=PyPI%20Downloads)](https://pypi.org/project/composio/)
[![NPM Downloads](https://img.shields.io/npm/dt/@composio/core?label=NPM%20Downloads)](https://www.npmjs.com/package/@composio/core)
[![Discord](https://img.shields.io/badge/Discord-join-5865F2?logo=discord&logoColor=white)](https://discord.gg/composio)
</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

### TypeScript SDK Installation

```bash
# Using npm
npm install @composio/core

# Using yarn
yarn add @composio/core

# Using pnpm
pnpm add @composio/core
```

#### Quick start:

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

#### Simple Agent with OpenAI Agents

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

```typescript
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 = 'user@acme.org';

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

```bash
# Using pip
pip install composio

# Using poetry
poetry add composio
```

#### Quick start:

```python
from composio import Composio

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

#### Simple Agent with OpenAI Agents

```bash
pip install composio_openai_agents openai-agents
```

```python
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 = "user@acme.org"
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

To update the OpenAPI specifications used for generating SDK documentation:

```bash
# 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

### TypeScript SDK (/ts)

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](/ts/README.md).

### Python SDK (/python)

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](/python/README.md).

## Provider Support

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](https://docs.composio.dev/sdk/typescript/custom-providers) to integrate with any AI framework.

## Packages

### Core Packages

| Package | Version |
|---------|---------|
| **TypeScript** | |
| [@composio/core](https://www.npmjs.com/package/@composio/core) | ![npm version](https://img.shields.io/npm/v/@composio/core) |
| **Python** | |
| [composio](https://pypi.org/project/composio/) | ![PyPI version](https://img.shields.io/pypi/v/composio) |

### Provider Packages

| Package | Version |
|---------|---------|
| **TypeScript** | |
| [@composio/openai](https://www.npmjs.com/package/@composio/openai) | ![npm version](https://img.shields.io/npm/v/@composio/openai) |
| [@composio/openai-agents](https://www.npmjs.com/package/@composio/openai-agents) | ![npm version](https://img.shields.io/npm/v/@composio/openai-agents) |
| [@composio/anthropic](https://www.npmjs.com/package/@composio/anthropic) | ![npm version](https://img.shields.io/npm/v/@composio/anthropic) |
| [@composio/langchain](https://www.npmjs.com/package/@composio/langchain) | ![npm version](https://img.shields.io/npm/v/@composio/langchain) |
| [@composio/llamaindex](https://www.npmjs.com/package/@composio/llamaindex) | ![npm version](https://img.shields.io/npm/v/@composio/llamaindex) |
| [@composio/vercel](https://www.npmjs.com/package/@composio/vercel) | ![npm version](https://img.shields.io/npm/v/@composio/vercel) |
| [@composio/google](https://www.npmjs.com/package/@composio/google) | ![npm version](https://img.shields.io/npm/v/@composio/google) |
| [@composio/mastra](https://www.npmjs.com/package/@composio/mastra) | ![npm version](https://img.shields.io/npm/v/@composio/mastra) |
| [@composio/cloudflare](https://www.npmjs.com/package/@composio/cloudflare) | ![npm version](https://img.shields.io/npm/v/@composio/cloudflare) |
| **Python** | |
| [composio-openai](https://pypi.org/project/composio-openai/) | ![PyPI version](https://img.shields.io/pypi/v/composio-openai) |
| [composio-openai-agents](https://pypi.org/project/composio-openai-agents/) | ![PyPI version](https://img.shields.io/pypi/v/composio-openai-agents) |
| [composio-anthropic](https://pypi.org/project/composio-anthropic/) | ![PyPI version](https://img.shields.io/pypi/v/composio-anthropic) |
| [composio-langchain](https://pypi.org/project/composio-langchain/) | ![PyPI version](https://img.shields.io/pypi/v/composio-langchain) |
| [composio-langgraph](https://pypi.org/project/composio-langgraph/) | ![PyPI version](https://img.shields.io/pypi/v/composio-langgraph) |
| [composio-llamaindex](https://pypi.org/project/composio-llamaindex/) | ![PyPI version](https://img.shields.io/pypi/v/composio-llamaindex) |
| [composio-crewai](https://pypi.org/project/composio-crewai/) | ![PyPI version](https://img.shields.io/pypi/v/composio-crewai) |
| [composio-autogen](https://pypi.org/project/composio-autogen/) | ![PyPI version](https://img.shields.io/pypi/v/composio-autogen) |
| [composio-gemini](https://pypi.org/project/composio-gemini/) | ![PyPI version](https://img.shields.io/pypi/v/composio-gemini) |
| [composio-google](https://pypi.org/project/composio-google/) | ![PyPI version](https://img.shields.io/pypi/v/composio-google) |
| [composio-google-adk](https://pypi.org/project/composio-google-adk/) | ![PyPI version](https://img.shields.io/pypi/v/composio-google-adk) |

### Utility Packages

| Package | Version |
|---------|---------|
| [@composio/json-schema-to-zod](https://www.npmjs.com/package/@composio/json-schema-to-zod) | ![npm version](https://img.shields.io/npm/v/@composio/json-schema-to-zod) |
| [@composio/ts-builders](https://www.npmjs.com/package/@composio/ts-builders) | ![npm version](https://img.shields.io/npm/v/@composio/ts-builders) |

_if you are looking for the older sdk, you can find them [here](https://github.com/ComposioHQ/composio/tree/master)_

## Rube

[Rube](https://rube.app) 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

We welcome contributions to both SDKs! Please read our [contribution guidelines](https://github.com/ComposioHQ/composio/blob/next/CONTRIBUTING.md) before submitting pull requests.

## License

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

## Support

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

- Open an issue in this repository
- Contact our [support team](mailto:support@composio.dev)
- Check our [documentation](https://docs.composio.dev/)