Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 355 lines 17.6 KB
Rendered Raw
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).