Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Contributing to Composio
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!
Table of Contents
- Contribution Policy
- Development Setup
- Project Structure
- Development Commands
- Working with AI Coding Agents
- Coding Standards
- Documentation Changes
- Pull Request Process
- Creating New Providers
- Testing Guidelines
- Release Process
- Questions and Support
- License
Contribution Policy
Open an issue first
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.
- Composio team members and designated maintainers can open issues and pull requests directly.
- 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.
Use the issue templates for bug reports, feature requests, and tool requests. For support questions, see Questions and Support. For security issues, follow SECURITY.md instead of opening a public issue.
PR reviewer
@jkomyno is the designated reviewer for pull requests. Involve the relevant SDK, CLI, or docs owner when the change needs their expertise.
Pull requests we may close
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:
- have no linked issue, when opened by an external contributor
- make cosmetic, speculative, or drive-by changes without a clear user benefit
- are too broad to review, or mix unrelated changes
- add third-party links or promotional content outside the third-party links policy
- show that the author hasn't read or verified the submitted code
Read the code you submit
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:
- Read and understand the whole diff.
- Run the relevant checks and describe what you ran.
- Remove unrelated edits, generated noise, and speculative code.
- Be ready to explain any change a reviewer asks about.
AI assistance is welcome. Unreviewed AI output is not.
Third-party links in docs
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.
Other third-party links and promotional content are limited to:
- frontier model providers, such as OpenAI and Anthropic
- frameworks and platforms that Composio provider packages support, such as LangChain, the Vercel AI SDK, and Google Vertex AI
- partners that have an agreement with Composio
Partnerships
To propose a partnership, including a docs listing or integration, contact us through composio.dev/contact. Don't open an issue or a pull request for a partnership request.
Development Setup
Prerequisites
Tool versions are pinned in 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:
mise install
mise installs pnpm through its npm backend. Don't rely on Corepack for this repository.
Getting started
- Fork and clone the repository:
git clone https://github.com/YOUR_USERNAME/composio.git
cd composio
- Install the toolchain and dependencies, then build and test:
mise install
pnpm install
pnpm build
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
│ │ ├── 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
Don't hand-edit generated or vendored paths, such as ts/vendor/**, ts/packages/core/generated/**, and lockfiles. AGENTS.md has the full list.
Development Commands
pnpm build # Build all packages
pnpm build:packages # Build TypeScript packages only
pnpm lint # Lint TypeScript packages
pnpm lint:fix # Fix lint issues where possible
pnpm format # Format supported files
pnpm typecheck # Type-check TypeScript packages
pnpm check:peer-deps # Check peer dependencies
pnpm update:peer-deps # Update peer dependencies
pnpm create:provider <provider-name> [--agentic] # New TypeScript provider
pnpm create:example <example-name> # New TypeScript example
Dead code detection
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:
# 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 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.
Working with AI Coding Agents
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.
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.
Two deterministic checks guard this guidance:
bun run validate:agent-skills # frontmatter, reference links, stale guidance refs, command names
bun run validate:skill-routing # routing smoke test over skill descriptions
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.
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 before you author or edit a skill.
Using an agent doesn't change your responsibility: read the code you submit.
Coding Standards
TypeScript
- Follow the style of the package you're editing.
- Use named exports for public APIs unless the package uses another pattern.
- Type public API changes and document them with TSDoc.
- Add focused tests for new behavior and bug fixes.
- Use Oxlint and Prettier through the repository scripts.
Python
- Follow the existing layout under
python/. - Use Ruff formatting and linting through the Python make targets.
- Keep provider-specific changes inside the relevant
python/providers/*package. - Add pytest coverage for behavior changes.
Error handling
- Use the existing error classes and result shapes in the package you're editing.
- Include enough context in error messages to identify the failing operation.
- Don't swallow errors unless the caller has an explicit fallback path.
Anti-slop checks
Run the AST checks from the repository root:
pnpm lint:antislop # reject new findings and stale baseline entries
pnpm test:antislop # rule fixtures and enforcement tests
pnpm lint:antislop:scan # inspect all findings, including existing ones
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.
The rules in .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.
| Language | Patterns |
|---|---|
| TypeScript | Double assertions through unknown or any, empty catch blocks (including comment-only blocks), @ts-ignore and @ts-nocheck |
| Python | Bare or broad except blocks containing only pass, type: ignore without error codes |
| CI YAML | Unconditional continue-on-error: true, empty run steps |
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 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.
Existing findings are recorded in .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.
CLI source also enables two local Oxlint rules from tools/oxlint/effect, adapted from MIT-licensed anti-slop rules:
composio-effect/require-cause-when-narrowingrejects broad Effect recovery or error-mapping callbacks that ignore their error and construct a replacement. Keep the original ascause, 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.composio-effect/no-ordie-in-service-constructionrejectsEffect.orDie/orDieWithin inline service construction andLayer.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.
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.
Documentation Changes
Update docs when a change affects public behavior, install flows, examples, environment variables, release steps, or provider usage.
For the documentation site, read docs/CONTRIBUTING.md and docs/AGENTS.md. They cover the docs app, MDX conventions, link checks, generated data, and validation.
Docs changes follow the third-party links policy.
Pull Request Process
For external contributions, confirm that an open issue exists. For large changes, get maintainer agreement on the approach before you start implementation.
Branch from
next, which is the base for most SDK and docs work:
git checkout next
git pull origin next
git checkout -b feat/your-change
Keep the change focused on the issue. Split unrelated changes into separate pull requests.
Add or update tests for behavior changes, and update docs for user-facing changes.
Add a changeset for public Python or TypeScript SDK behavior changes. Select each affected TypeScript package and/or the private
@composio/python-sdkmarker:
pnpm changeset
Documentation-only and agent-guidance-only changes don't need a changeset.
Read your full diff and run the smallest meaningful checks locally.
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.
Creating New Providers
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.
TypeScript providers
pnpm create:provider my-provider [--agentic]
Implement the required provider methods, add tests under the provider package, and add docs or examples for user-facing setup.
Python providers
Run from the python/ directory:
cd python
make create-provider name=my-provider
make create-provider name=my-provider agentic=true # agentic provider
Then add provider tests and run the relevant Python checks.
Testing Guidelines
TypeScript SDK
pnpm test # Unit tests
pnpm test:e2e # All end-to-end tests
pnpm test:e2e:node # Runtime-specific end-to-end tests
pnpm test:e2e:cli
pnpm test:e2e:cloudflare
pnpm test:ui # Vitest UI
Python SDK
cd python
make env
source .venv/bin/activate
make fmt
make chk
make tst
make snt
For a focused run, use pytest through uv:
uv run pytest tests/test_sdk.py -v
Docs site
Run from docs/:
cd docs
bun install
bun run build
bun run lint:links
docs/CONTRIBUTING.md lists the full set of docs checks.
Release Process
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.
- TypeScript packages and the CLI:
ts/docs/internal/release.md - Python packages:
python/docs/release.md
Questions and Support
- Documentation
- Discord community
- Support guide
- Partnerships: composio.dev/contact
License
By contributing to Composio, you agree that your contributions are licensed under the MIT License.