composiohq__composio/CONTRIBUTING.md

Contributing to Composio SDK

Thank you for your interest in contributing to Composio. This guide covers the root SDK repository. The monorepo contains the TypeScript SDK, Python SDK, docs site, examples, and release tooling.

Table of Contents

• Development Setup
• Project Structure
• Development Commands
• Working with AI Coding Agents
• Coding Standards
• Documentation Requirements
• Pull Request Process
• Creating New Providers
• Testing Guidelines
• Release Process
• Questions and Support

Development Setup

Prerequisites

Tool versions are pinned in mise.toml, which is the source of truth for local development and CI:

• Node.js 24.17.0
• pnpm 11.8.0
• Bun 1.3.10
• Deno 2.6.7
• Python 3.12
• uv 0.8.19

Use mise to install the toolchain:

mise install

mise installs pnpm through its npm backend. Do not rely on Corepack for this repository.

Getting Started

1. Fork and clone the repository:

   git clone https://github.com/YOUR_USERNAME/composio.git
   cd composio
   

2. Install the pinned toolchain:

   mise install
   

3. Install dependencies:

   pnpm install
   

4. Build the project:

   pnpm build
   

5. Run tests:

   pnpm test
   

Project Structure

composio/
├── ts/                        # TypeScript SDK workspace
│   ├── packages/
│   │   ├── core/              # Core SDK package (@composio/core)
│   │   ├── cli/               # CLI binary and command implementations
│   │   ├── cli-keyring/       # Keyring helper for the CLI
│   │   ├── cli-local-tools/   # Local tools support for the CLI
│   │   ├── providers/         # AI framework provider adapters
│   │   ├── json-schema-to-zod/ # Schema conversion utility
│   │   └── ts-builders/       # TypeScript build helpers
│   ├── e2e-tests/             # Runtime and CLI end-to-end tests
│   ├── examples/              # TypeScript examples
│   └── scripts/               # TypeScript build and maintenance scripts
├── python/                    # Python SDK
│   ├── composio/              # Main Python package
│   ├── providers/             # Python provider adapters
│   ├── tests/                 # pytest test suite
│   ├── scripts/               # Python development and release scripts
│   └── docs/                  # Python release notes and process docs
├── docs/                      # Documentation site
├── test/                      # Root-level release/install script tests
└── .github/                   # GitHub Actions and shared CI actions

Development Commands

# Build all packages
pnpm build

# Build TypeScript packages only
pnpm build:packages

# Lint TypeScript packages
pnpm lint

# Fix lint issues where possible
pnpm lint:fix

# Format supported files
pnpm format

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

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

# Check peer dependencies
pnpm check:peer-deps

# Update peer dependencies
pnpm update:peer-deps

Dead code detection

The Dead Code CI workflow reports likely-orphaned code on every PR (findings land in the run's Step Summary; it never fails the build). Run the same checks locally:

# TypeScript — unused files, exports, types and dependencies
pnpm dlx knip@5            # config in knip.json

# Python — unused functions, classes and variables
cd python && make dead-code   # vulture; allowlist in python/config/vulture_allowlist.py

# GitHub Actions — orphaned reusable workflows and composite actions
bash .github/scripts/check-orphan-ci.sh

These tools carry false positives (public API surface, dynamic imports, import-map targets), so treat their output as advisory: verify a finding is truly unreferenced before deleting, and suppress confirmed false positives via knip.json / vulture_allowlist.py.

Working with AI Coding Agents

This repository ships its own agent guidance, and CI keeps it honest. You get it for free — an agent that reads this repo inherits the layout, commands, and guardrails without setup.

AGENTS.md files live at the root and inside each subtree (ts/, python/, docs/, and the packages). Coding agents read the nearest one automatically, so you usually do not need to do anything beyond keeping them accurate when you move code. The canonical skill tree is .agents/skills/ (with .claude/skills as a compatibility symlink): focused, task-scoped skills that route an agent to the right workflow, from bug-fixing to cli-release.

Two deterministic checks guard this guidance:

pnpm validate:agent-skills    # frontmatter, reference links, stale guidance refs, command names
pnpm validate:skill-routing   # routing smoke test over skill descriptions

validate:agent-skills parses package.json, python/Makefile, and python/noxfile.py, then verifies every command mentioned in guidance actually exists — so guidance cannot recommend a command that was renamed away. Both checks run in CI via .github/workflows/agent-substrate.yml whenever agent guidance changes.

If you add or rename a skill, or rewrite a skill description, run both checks and add a routing probe in ts/scripts/test-skill-routing.mjs so routing stays covered. To author or edit a skill, read .agents/skills/skill-maintenance/SKILL.md first.

Coding Standards

TypeScript

1. Follow the style of the package you are editing.
2. Use TypeScript for new TypeScript SDK code.
3. Use named exports for public APIs unless the local package pattern says otherwise.
4. Keep public API changes typed and documented with TSDoc.
5. Add focused tests for new behavior and bug fixes.
6. Use Oxlint and Prettier through the repo scripts.
7. Keep generated or vendored code out of manual edits unless the package explicitly owns that output.

Python

1. Follow the existing Python SDK layout under python/.
2. Use Ruff formatting and linting through the Python make targets.
3. Keep provider-specific changes inside the relevant python/providers/* package.
4. Add pytest coverage for behavior changes.

Error Handling

1. Use the existing error classes and result shapes in the package you are editing.
2. Include enough context in error messages to identify the failing operation.
3. Avoid swallowing errors unless the caller has an explicit fallback path.

Documentation Requirements

Update docs when a change affects public behavior, install flows, examples, environment variables, release steps, or provider usage.

For documentation-site work, read docs/CLAUDE.md first. It documents the docs app, MDX conventions, link checking, generated data, and docs branch workflow.

Package documentation should generally include:

1. A short package description.
2. Installation instructions.
3. Usage examples.
4. Public API notes.
5. Environment variables or authentication requirements when relevant.
6. Provider limitations or streaming details when relevant.

Pull Request Process

1. Create a branch from the target base branch. Most active SDK and docs work targets next.

   git checkout next
   git pull origin next
   git checkout -b feature/your-feature-name
   

2. Make focused changes that match the issue or feature scope.

3. Add or update tests for behavior changes.

4. Update documentation when user-facing behavior changes.

5. Add a changeset for changes that affect published TypeScript packages:

   pnpm changeset
   

   Root-level documentation-only changes, such as edits to this file, do not need a changeset.

6. Run the smallest meaningful verification command locally before opening the PR.

7. Push your branch and open a PR against the correct base branch.

Creating New Providers

TypeScript Providers

Use the TypeScript provider creation script:

pnpm create:provider my-provider [--agentic]

Then:

1. Implement the required provider methods.
2. Add tests under the provider package.
3. Add examples or docs when the provider has user-facing setup details.
4. Run the package tests and relevant build checks.

Python Providers

Use the Python provider creation target from the python/ directory:

cd python
make create-provider name=my-provider

For agentic providers:

cd python
make create-provider name=my-provider agentic=true

Then add provider tests and run the relevant Python checks.

Testing Guidelines

TypeScript SDK

Run the root TypeScript test suite:

pnpm test

Run all TypeScript end-to-end tests:

pnpm test:e2e

Run runtime-specific end-to-end tests:

pnpm test:e2e:node
pnpm test:e2e:deno
pnpm test:e2e:cli
pnpm test:e2e:cloudflare

Open the Vitest UI:

pnpm test:ui

Python SDK

Set up the Python development environment:

cd python
make env
source .venv/bin/activate

Run Python checks:

make fmt
make chk
make tst
make snt

You can also run a focused pytest command through uv:

uv run pytest tests/test_sdk.py -v

Docs Site

For docs changes:

cd docs
bun install
bun run build
bun run lint:links

See docs/CLAUDE.md for the full docs workflow.

Release Process

Only maintainers publish releases.

For TypeScript package and CLI release details, use ts/docs/internal/release.md. The root scripts are:

pnpm changeset
pnpm changeset:version
pnpm changeset:release

For Python package release details, use python/docs/release.md. Python package versioning and release preparation are handled from the python/ workspace.

Questions and Support

• Join our Discord Community
• Check our Documentation
• File issues on GitHub

License

By contributing to Composio SDK, you agree that your contributions will be licensed under the ISC License.