Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | # Contributing to Composio |
| 2 | |
| 3 | This repository contains the Composio TypeScript SDK, Python SDK, CLI, docs site, examples, and release tooling. Please read the contribution policy before you open an issue or a pull request. Thank you for your interest in contributing to Composio! |
| 4 | |
| 5 | ## Table of Contents |
| 6 | |
| 7 | - [Contribution Policy](#contribution-policy) |
| 8 | - [Development Setup](#development-setup) |
| 9 | - [Project Structure](#project-structure) |
| 10 | - [Development Commands](#development-commands) |
| 11 | - [Working with AI Coding Agents](#working-with-ai-coding-agents) |
| 12 | - [Coding Standards](#coding-standards) |
| 13 | - [Documentation Changes](#documentation-changes) |
| 14 | - [Pull Request Process](#pull-request-process) |
| 15 | - [Creating New Providers](#creating-new-providers) |
| 16 | - [Testing Guidelines](#testing-guidelines) |
| 17 | - [Release Process](#release-process) |
| 18 | - [Questions and Support](#questions-and-support) |
| 19 | - [License](#license) |
| 20 | |
| 21 | ## Contribution Policy |
| 22 | |
| 23 | ### Open an issue first |
| 24 | |
| 25 | Issues are the preferred way to contribute. A clear bug report or feature request is often more useful to us than a pull request, and it avoids long review cycles for changes we might not accept. |
| 26 | |
| 27 | - **Composio team members and designated maintainers** can open issues and pull requests directly. |
| 28 | - **External contributors** should open an issue first. Open a pull request only for an existing, open issue, and link that issue in the pull request description. For large changes, wait for a maintainer to confirm the approach on the issue before you start implementation. Small fixes do not require prior maintainer approval. |
| 29 | |
| 30 | Use the [issue templates](https://github.com/ComposioHQ/composio/issues/new/choose) for bug reports, feature requests, and tool requests. For support questions, see [Questions and Support](#questions-and-support). For security issues, follow [`SECURITY.md`](.github/SECURITY.md) instead of opening a public issue. |
| 31 | |
| 32 | ### PR reviewer |
| 33 | |
| 34 | [@jkomyno](mailto:alberto@composio.dev) is the designated reviewer for pull requests. Involve the relevant SDK, CLI, or docs owner when the change needs their expertise. |
| 35 | |
| 36 | ### Pull requests we may close |
| 37 | |
| 38 | We reserve the right to close pull requests that don't make a meaningful contribution to Composio's SDKs, CLI, or docs. This includes pull requests that: |
| 39 | |
| 40 | - have no linked issue, when opened by an external contributor |
| 41 | - make cosmetic, speculative, or drive-by changes without a clear user benefit |
| 42 | - are too broad to review, or mix unrelated changes |
| 43 | - add third-party links or promotional content outside the [third-party links policy](#third-party-links-in-docs) |
| 44 | - show that the author hasn't read or verified the submitted code |
| 45 | |
| 46 | ### Read the code you submit |
| 47 | |
| 48 | You are responsible for every line in your pull request, whether you wrote it yourself or with an LLM or coding agent. Before you open a pull request: |
| 49 | |
| 50 | - Read and understand the whole diff. |
| 51 | - Run the relevant checks and describe what you ran. |
| 52 | - Remove unrelated edits, generated noise, and speculative code. |
| 53 | - Be ready to explain any change a reviewer asks about. |
| 54 | |
| 55 | AI assistance is welcome. Unreviewed AI output is not. |
| 56 | |
| 57 | ### Third-party links in docs |
| 58 | |
| 59 | You can link to authoritative technical documentation needed to use or contribute to Composio, including toolkit setup instructions, OAuth documentation, and language or runtime references. |
| 60 | |
| 61 | Other third-party links and promotional content are limited to: |
| 62 | |
| 63 | - frontier model providers, such as OpenAI and Anthropic |
| 64 | - frameworks and platforms that Composio provider packages support, such as LangChain, the Vercel AI SDK, and Google Vertex AI |
| 65 | - partners that have an agreement with Composio |
| 66 | |
| 67 | ### Partnerships |
| 68 | |
| 69 | To propose a partnership, including a docs listing or integration, contact us through [composio.dev/contact](https://composio.dev/contact). Don't open an issue or a pull request for a partnership request. |
| 70 | |
| 71 | ## Development Setup |
| 72 | |
| 73 | ### Prerequisites |
| 74 | |
| 75 | Tool versions are pinned in [`mise.toml`](mise.toml), which is the source of truth for local development and CI. It pins Node.js, pnpm, Bun, Python, and uv. Install the toolchain with [mise](https://mise.jdx.dev): |
| 76 | |
| 77 | ```bash |
| 78 | mise install |
| 79 | ``` |
| 80 | |
| 81 | mise installs pnpm through its npm backend. Don't rely on Corepack for this repository. |
| 82 | |
| 83 | ### Getting started |
| 84 | |
| 85 | 1. Fork and clone the repository: |
| 86 | |
| 87 | ```bash |
| 88 | git clone https://github.com/YOUR_USERNAME/composio.git |
| 89 | cd composio |
| 90 | ``` |
| 91 | |
| 92 | 2. Install the toolchain and dependencies, then build and test: |
| 93 | |
| 94 | ```bash |
| 95 | mise install |
| 96 | pnpm install |
| 97 | pnpm build |
| 98 | pnpm test |
| 99 | ``` |
| 100 | |
| 101 | ## Project Structure |
| 102 | |
| 103 | ```text |
| 104 | composio/ |
| 105 | ├── ts/ # TypeScript SDK workspace |
| 106 | │ ├── packages/ |
| 107 | │ │ ├── core/ # Core SDK package (@composio/core) |
| 108 | │ │ ├── cli/ # CLI binary and command implementations |
| 109 | │ │ ├── cli-keyring/ # Keyring helper for the CLI |
| 110 | │ │ ├── providers/ # AI framework provider adapters |
| 111 | │ │ ├── json-schema-to-zod/ # Schema conversion utility |
| 112 | │ │ └── ts-builders/ # TypeScript build helpers |
| 113 | │ ├── e2e-tests/ # Runtime and CLI end-to-end tests |
| 114 | │ ├── examples/ # TypeScript examples |
| 115 | │ └── scripts/ # TypeScript build and maintenance scripts |
| 116 | ├── python/ # Python SDK |
| 117 | │ ├── composio/ # Main Python package |
| 118 | │ ├── providers/ # Python provider adapters |
| 119 | │ ├── tests/ # pytest test suite |
| 120 | │ ├── scripts/ # Python development and release scripts |
| 121 | │ └── docs/ # Python release notes and process docs |
| 122 | ├── docs/ # Documentation site |
| 123 | ├── test/ # Root-level release/install script tests |
| 124 | └── .github/ # GitHub Actions and shared CI actions |
| 125 | ``` |
| 126 | |
| 127 | Don't hand-edit generated or vendored paths, such as `ts/vendor/**`, `ts/packages/core/generated/**`, and lockfiles. [`AGENTS.md`](AGENTS.md#generated-and-vendored-paths) has the full list. |
| 128 | |
| 129 | ## Development Commands |
| 130 | |
| 131 | ```bash |
| 132 | pnpm build # Build all packages |
| 133 | pnpm build:packages # Build TypeScript packages only |
| 134 | pnpm lint # Lint TypeScript packages |
| 135 | pnpm lint:fix # Fix lint issues where possible |
| 136 | pnpm format # Format supported files |
| 137 | pnpm typecheck # Type-check TypeScript packages |
| 138 | pnpm check:peer-deps # Check peer dependencies |
| 139 | pnpm update:peer-deps # Update peer dependencies |
| 140 | |
| 141 | pnpm create:provider <provider-name> [--agentic] # New TypeScript provider |
| 142 | pnpm create:example <example-name> # New TypeScript example |
| 143 | ``` |
| 144 | |
| 145 | ### Dead code detection |
| 146 | |
| 147 | The `Dead Code` CI workflow reports likely-orphaned code every Monday, and can be run on demand. Findings land in the run's Step Summary and never fail the build. Run the same checks locally: |
| 148 | |
| 149 | ```bash |
| 150 | # TypeScript: unused files, exports, types, and dependencies |
| 151 | pnpm dlx knip@5 # config in knip.json |
| 152 | |
| 153 | # Python: unused functions, classes, and variables |
| 154 | cd python && make dead-code # vulture; allowlist in python/config/vulture_allowlist.py |
| 155 | |
| 156 | # GitHub Actions: orphaned reusable workflows and composite actions |
| 157 | bash .github/scripts/check-orphan-ci.sh |
| 158 | ``` |
| 159 | |
| 160 | These tools report false positives for public API surface, dynamic imports, and import-map targets. Verify that a finding is unreferenced before you delete it, and suppress confirmed false positives in `knip.json` or `vulture_allowlist.py`. |
| 161 | |
| 162 | ## Working with AI Coding Agents |
| 163 | |
| 164 | This repository ships its own agent guidance, and CI keeps it accurate. An agent that reads this repository inherits its layout, commands, and rules, including the [Contribution Policy](#contribution-policy). |
| 165 | |
| 166 | `AGENTS.md` files live at the root and inside each subtree (`ts/`, `python/`, `docs/`, and the packages). Coding agents read the nearest one automatically. Keep them accurate when you move code. The canonical skill tree is `.agents/skills/`, with `.claude/skills` as a compatibility symlink. |
| 167 | |
| 168 | Two deterministic checks guard this guidance: |
| 169 | |
| 170 | ```bash |
| 171 | bun run validate:agent-skills # frontmatter, reference links, stale guidance refs, command names |
| 172 | bun run validate:skill-routing # routing smoke test over skill descriptions |
| 173 | ``` |
| 174 | |
| 175 | `validate:agent-skills` parses `package.json`, `python/Makefile`, and `python/noxfile.py`, then verifies that every command mentioned in guidance exists. Both checks run in CI through `.github/workflows/agent-substrate.yml`. |
| 176 | |
| 177 | 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.ts`. Read [`.agents/skills/skill-maintenance/SKILL.md`](.agents/skills/skill-maintenance/SKILL.md) before you author or edit a skill. |
| 178 | |
| 179 | Using an agent doesn't change your responsibility: [read the code you submit](#read-the-code-you-submit). |
| 180 | |
| 181 | ## Coding Standards |
| 182 | |
| 183 | ### TypeScript |
| 184 | |
| 185 | - Follow the style of the package you're editing. |
| 186 | - Use named exports for public APIs unless the package uses another pattern. |
| 187 | - Type public API changes and document them with TSDoc. |
| 188 | - Add focused tests for new behavior and bug fixes. |
| 189 | - Use Oxlint and Prettier through the repository scripts. |
| 190 | |
| 191 | ### Python |
| 192 | |
| 193 | - Follow the existing layout under `python/`. |
| 194 | - Use Ruff formatting and linting through the Python make targets. |
| 195 | - Keep provider-specific changes inside the relevant `python/providers/*` package. |
| 196 | - Add pytest coverage for behavior changes. |
| 197 | |
| 198 | ### Error handling |
| 199 | |
| 200 | - Use the existing error classes and result shapes in the package you're editing. |
| 201 | - Include enough context in error messages to identify the failing operation. |
| 202 | - Don't swallow errors unless the caller has an explicit fallback path. |
| 203 | |
| 204 | ### Anti-slop checks |
| 205 | |
| 206 | Run the AST checks from the repository root: |
| 207 | |
| 208 | ```bash |
| 209 | pnpm lint:antislop # reject new findings and stale baseline entries |
| 210 | pnpm test:antislop # rule fixtures and enforcement tests |
| 211 | pnpm lint:antislop:scan # inspect all findings, including existing ones |
| 212 | ``` |
| 213 | |
| 214 | These checks also run through `pnpm lint` and the **Anti-slop (TypeScript, Python, YAML)** CI job on every push and pull request to `next` or `master`. They supplement Oxlint and Ruff. They flag specific patterns; they cannot determine whether code was written by AI. |
| 215 | |
| 216 | The rules in [`.ast-grep/rules`](.ast-grep/rules) cover handwritten TypeScript SDK and CLI packages, Python SDK and providers, maintenance scripts, GitHub workflows, and composite actions. TypeScript uses the TSX parser to cover `.ts`, `.tsx`, `.mts`, and `.cts` with the same rules. Generated code, dependencies, build output, and test files are excluded. Python examples are covered; TypeScript examples and the docs site are outside this check's scope. |
| 217 | |
| 218 | | Language | Patterns | |
| 219 | | ---------- | -------------------------------------------------------------------------------------------------------------------------------- | |
| 220 | | TypeScript | Double assertions through `unknown` or `any`, empty catch blocks (including comment-only blocks), `@ts-ignore` and `@ts-nocheck` | |
| 221 | | Python | Bare or broad `except` blocks containing only `pass`, `type: ignore` without error codes | |
| 222 | | CI YAML | Unconditional `continue-on-error: true`, empty `run` steps | |
| 223 | |
| 224 | Fix a finding by parsing or narrowing input, handling the failure, or keeping the original check effective. Some soft failures are intentional, such as collecting an audit result before a later step enforces its outcome. For a justified exception, explain the invariant or later failure gate in a comment, then put a [rule-specific ast-grep suppression](https://ast-grep.github.io/guide/project/severity.html#ignore-linting-error) immediately before the matched node. For `yaml-continue-on-error`, the matched node is the containing step or job mapping, so place its suppression before the step or job. Blanket and unused suppressions fail the check. Avoid file-wide suppressions. |
| 225 | |
| 226 | Existing findings are recorded in [`.ast-grep/baseline.json`](.ast-grep/baseline.json) by rule, path, full matched source lines, and occurrence count. The baseline records adoption debt, not approved patterns. A new source, a changed source, a moved file, or another identical occurrence fails the check. Line-number changes alone do not. After fixing an existing finding, run `pnpm lint:antislop:prune` and include the reduced baseline in your change. Pruning refuses to add allowances. Do not regenerate or expand the baseline to pass CI. |
| 227 | |
| 228 | CLI source also enables two local Oxlint rules from [`tools/oxlint/effect`](tools/oxlint/effect/UPSTREAM.md), adapted from MIT-licensed anti-slop rules: |
| 229 | |
| 230 | - `composio-effect/require-cause-when-narrowing` rejects broad Effect recovery or error-mapping callbacks that ignore their error and construct a replacement. Keep the original as `cause`, or capture it before replacing it. Tag-specific recovery is excluded. This syntax check does not prove that every error is preserved: callbacks that read their error, object spreads, and preceding error taps are left to review. |
| 231 | - `composio-effect/no-ordie-in-service-construction` rejects `Effect.orDie`/`orDieWith` in inline service construction and `Layer.orDie`. Keep expected failures in the typed error channel with the package's tagged errors. Operations returned by a service are outside the construction check; it does not follow imported or separately defined helper effects. |
| 232 | |
| 233 | Both rules run through `pnpm lint:antislop` and its CI job. Tests, fixtures, and generated files are excluded. Run `pnpm test:effect-rules` for their fixtures and config-enforcement test, and `pnpm typecheck:effect-rules` to typecheck the plugin. A justified exception needs a nearby invariant comment and a rule-specific `oxlint-disable-next-line` directive. |
| 234 | |
| 235 | ## Documentation Changes |
| 236 | |
| 237 | Update docs when a change affects public behavior, install flows, examples, environment variables, release steps, or provider usage. |
| 238 | |
| 239 | For the documentation site, read [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) and [`docs/AGENTS.md`](docs/AGENTS.md). They cover the docs app, MDX conventions, link checks, generated data, and validation. |
| 240 | |
| 241 | Docs changes follow the [third-party links policy](#third-party-links-in-docs). |
| 242 | |
| 243 | ## Pull Request Process |
| 244 | |
| 245 | 1. For external contributions, confirm that an open issue exists. For large changes, get maintainer agreement on the approach before you start implementation. |
| 246 | |
| 247 | 2. Branch from `next`, which is the base for most SDK and docs work: |
| 248 | |
| 249 | ```bash |
| 250 | git checkout next |
| 251 | git pull origin next |
| 252 | git checkout -b feat/your-change |
| 253 | ``` |
| 254 | |
| 255 | 3. Keep the change focused on the issue. Split unrelated changes into separate pull requests. |
| 256 | |
| 257 | 4. Add or update tests for behavior changes, and update docs for user-facing changes. |
| 258 | |
| 259 | 5. Add a changeset for public Python or TypeScript SDK behavior changes. Select each affected TypeScript package and/or the private `@composio/python-sdk` marker: |
| 260 | |
| 261 | ```bash |
| 262 | pnpm changeset |
| 263 | ``` |
| 264 | |
| 265 | Documentation-only and agent-guidance-only changes don't need a changeset. |
| 266 | |
| 267 | 6. Read your full diff and run the smallest meaningful checks locally. |
| 268 | |
| 269 | 7. Open a pull request against `next`. Fill in the template, link the issue for external contributions (or when one exists for team contributions), and describe how you tested the change. Request review from [@jkomyno](mailto:alberto@composio.dev). |
| 270 | |
| 271 | ## Creating New Providers |
| 272 | |
| 273 | For external contributions, open an issue before you build a new provider. Get maintainer agreement before implementing large changes. We may decline providers we can't maintain. |
| 274 | |
| 275 | ### TypeScript providers |
| 276 | |
| 277 | ```bash |
| 278 | pnpm create:provider my-provider [--agentic] |
| 279 | ``` |
| 280 | |
| 281 | Implement the required provider methods, add tests under the provider package, and add docs or examples for user-facing setup. |
| 282 | |
| 283 | ### Python providers |
| 284 | |
| 285 | Run from the `python/` directory: |
| 286 | |
| 287 | ```bash |
| 288 | cd python |
| 289 | make create-provider name=my-provider |
| 290 | make create-provider name=my-provider agentic=true # agentic provider |
| 291 | ``` |
| 292 | |
| 293 | Then add provider tests and run the relevant Python checks. |
| 294 | |
| 295 | ## Testing Guidelines |
| 296 | |
| 297 | ### TypeScript SDK |
| 298 | |
| 299 | ```bash |
| 300 | pnpm test # Unit tests |
| 301 | pnpm test:e2e # All end-to-end tests |
| 302 | pnpm test:e2e:node # Runtime-specific end-to-end tests |
| 303 | pnpm test:e2e:cli |
| 304 | pnpm test:e2e:cloudflare |
| 305 | pnpm test:ui # Vitest UI |
| 306 | ``` |
| 307 | |
| 308 | ### Python SDK |
| 309 | |
| 310 | ```bash |
| 311 | cd python |
| 312 | make env |
| 313 | source .venv/bin/activate |
| 314 | make fmt |
| 315 | make chk |
| 316 | make tst |
| 317 | make snt |
| 318 | ``` |
| 319 | |
| 320 | For a focused run, use pytest through uv: |
| 321 | |
| 322 | ```bash |
| 323 | uv run pytest tests/test_sdk.py -v |
| 324 | ``` |
| 325 | |
| 326 | ### Docs site |
| 327 | |
| 328 | Run from `docs/`: |
| 329 | |
| 330 | ```bash |
| 331 | cd docs |
| 332 | bun install |
| 333 | bun run build |
| 334 | bun run lint:links |
| 335 | ``` |
| 336 | |
| 337 | [`docs/CONTRIBUTING.md`](docs/CONTRIBUTING.md) lists the full set of docs checks. |
| 338 | |
| 339 | ## Release Process |
| 340 | |
| 341 | Any active ComposioHQ member can request a stable or beta SDK release through the SDK release issue form. Repository writers can also run **SDK release** on `next`. A repository writer other than the PR author approves the final release PR, a person merges it, and automation publishes the candidates the PR built and checked. The requester may approve only with repository `admin` permission, checked at release time. See the shared runbook below. CLI binaries and the 1.0 prerelease train on `main` keep their separate workflows. |
| 342 | |
| 343 | - TypeScript packages and the CLI: [`ts/docs/internal/release.md`](ts/docs/internal/release.md) |
| 344 | - Python packages: [`python/docs/release.md`](python/docs/release.md) |
| 345 | |
| 346 | ## Questions and Support |
| 347 | |
| 348 | - [Documentation](https://docs.composio.dev) |
| 349 | - [Discord community](https://discord.gg/composio) |
| 350 | - [Support guide](.github/SUPPORT.md) |
| 351 | - Partnerships: [composio.dev/contact](https://composio.dev/contact) |
| 352 | |
| 353 | ## License |
| 354 | |
| 355 | By contributing to Composio, you agree that your contributions are licensed under the [MIT License](LICENSE). |