February 8, 2026 5 min read TypeScript fork

composio

Abstract

Composio equips your AI agents & LLMs with 100+ high-quality integrations via function calling

The Problem

Developers building AI agents must manually stitch dozens of third‑party APIs, write boilerplate request code, and keep authentication in sync. The effort multiplies when the same integrations are needed across TypeScript and Python projects, leading to duplicated logic and fragile maintenance.

What This Does

The repo ships two first‑party SDKs ( /ts and /python ) that expose 100+ curated integrations through a single client object.

The TypeScript entry lives in ts/packages/core/src/composio.ts (exported via ts/packages/core/src/index.ts). It builds an HTTP wrapper around the Composio backend and returns typed tool objects.
The Python counterpart starts in python/composio/__init__.py (generated from python/composio/core/models/tools.py). It mirrors the same methods (tools.get, tools.run) with async support.

Both SDKs are generated from the OpenAPI spec pulled by the Fern generator (fern/generators/tool_doc_generator/main.py). The spec lives in fern/openapi/ (not listed) and is refreshed via the pnpm api:pull script described in the README.

How It Is Wired

Runtime start – A consumer imports Composio from @composio/core (TS) or composio (Python).
Client construction – ts/packages/core/src/composio.ts creates a BaseClient that holds the API key and optional provider (e.g., OpenAI Agents). The same pattern exists in python/composio/core/client.py.
Tool request – client.tools.get(userId, options) calls src/api/tools.ts (TS) or python/composio/core/endpoints/tools.py. These modules issue a single GET /tools request to the Composio service.
Response handling – The JSON payload is parsed into strongly‑typed classes defined in ts/packages/core/src/types/tool.types.ts and python/composio/core/models/tools.py. These files are among the hub modules: ts/packages/ts-builders/src/Writer has 41 inbound imports, and the core type files are referenced by dozens of other modules, giving them a large blast radius.
Export – The populated tool objects are returned to the caller, who can pass them to an LLM agent (e.g., OpenAIAgentsProvider).

The internal import graph contains 859 modules and 911 edges, with 37 circular dependencies. The most connected module (ts/packages/ts-builders/src/Writer) sits in a cycle, meaning any change there risks widespread breakage.

How To Use It

# Clone the repo
git clone https://github.com/moses-y/composio
cd composio

# Install TypeScript SDK (pnpm is the lockfile manager)
pnpm install   # installs root dev deps and docs/ deps
pnpm add @composio/core   # or use the published package

# Install Python SDK
python -m venv .venv && source .venv/bin/activate
pip install composio   # pulls from PyPI; the repo contains the source for reference

Configuration – Both SDKs read the API key from the client constructor; no external config file is required. Example in docs/components/quickstart/index.tsx shows a minimal new Composio({}) call.

Running a quick test – In TS:

import { Composio } from '@composio/core';
const c = new Composio({ apiKey: process.env.COMPOSIO_KEY });
c.tools.get('user@example.com', { toolkits: ['HACKERNEWS'] })
  .then(console.log);

In Python:

from composio import Composio
c = Composio(api_key=os.getenv("COMPOSIO_KEY"))
tools = c.tools.get(user_id="user@example.com", toolkits=["HACKERNEWS"])
print(tools)

Real‑World Use

A SaaS platform that auto‑generates market‑research reports can instantiate Composio inside an OpenAI‑driven agent. The agent calls tools.get to fetch the latest news via the HACKERNEWS toolkit, then aggregates the data into a structured summary returned to the end user—all without writing any HTTP client code.

Code Health & Issues

Measured findings (static analysis)

HIGH – Import cycles – 29 files (e.g., ts/packages/ts-builders/src/Writer.ts) participate in circular imports. Break cycles by extracting shared types.
HIGH – Hub module – ts/packages/ts-builders/src/Writer is depended on by 41 modules; keep it stable.
MEDIUM – Oversized files – ts/packages/core/src/models/Tools.ts (647 lines) and its Python analogue are hard to maintain; split by responsibility.
MEDIUM – High branching density – ts/packages/json-schema-to-zod/src/parsers/parse-schema.ts has 51 branches over 147 lines; consider strategy dispatch.
HIGH – Deep nesting – python/composio/core/models/tools.py reaches 8 levels of indentation; flatten with guard clauses.
HIGH – Duplicated code blocks – Repeated 6‑line snippets across ~200 UI pages (docs/app/.../page.tsx); extract to shared helpers.

Health audit (CI/CD & ops)

CRITICAL – .github/workflows/publish_docs.yml uses permissions: write-all. Limit to required scopes.
HIGH – All GitHub Actions reference tags (e.g., softprops/action-gh-release@v2). Pin to commit SHAs.
MEDIUM – No explicit permissions in cli.test-installation.yml; add least‑privilege token scopes.
MEDIUM – Dockerfile base image debian:bookworm-slim is unpinned; use a digest.
MEDIUM – No dependency‑vulnerability scan in CI; add dependency-review-action or osv-scanner.
MEDIUM – Large dataset docs/public/data/toolkits.json (6.9 MiB) should be stored via Git LFS or external storage.
MEDIUM – checkout step keeps credentials; set persist-credentials: false.
MEDIUM – Container runs as root; add a non‑root USER.
MEDIUM – preinstall script in package.json runs unreviewed code; disable scripts in CI or move logic to explicit build steps.
LOW – Workflow jobs lack timeout-minutes; define realistic limits.

The Bottom Line

Composio delivers a well‑documented, dual‑language SDK that dramatically reduces the boilerplate for integrating third‑party services into LLM agents. The codebase is functional but suffers from import cycles, large hub modules, and several operational security hardening gaps that should be addressed before using it in a production‑critical environment. Teams comfortable fixing structural issues and tightening CI/CD policies will find it a solid foundation for agentic tooling.

What the analyser found

Deployment readiness

7/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

1,724 files

TypeScript596
Python211
Markdown186
JSON178
TSX51
YAML36

ReactNext.jsDjangoFlaskFastAPITailwindDockerTransformersLangChain

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["ts 506 modules"] g1["fern 148 modules"] g2["python 133 modules"] g3["docs 68 modules"] g4["(root) 4 modules"] g0 -->|14| g4

Module dependencies

The 10 most depended-upon modules of 859, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_kages_ts_builders_src_Writer["Writer"] n1_json_schema_to_zod_src_types["types"] n2_es_ts_builders_src_NamedType["NamedType"] n3__ts_builders_src_TypeBuilder["TypeBuilder"] n4_es_core_src_types_tool_types["tool.types"] n5_ts_builders_src_BasicBuilder["BasicBuilder"] n6_ckages_core_src_utils_logger["logger"] n7_es_ts_builders_src_stringify["stringify"] n8_lders_src_OperatorPrecedence["OperatorPrecedence"] n9_core_src_telemetry_Telemetry["Telemetry"] n9_core_src_telemetry_Telemetry --> n6_ckages_core_src_utils_logger n5_ts_builders_src_BasicBuilder --> n0_kages_ts_builders_src_Writer n2_es_ts_builders_src_NamedType --> n3__ts_builders_src_TypeBuilder n2_es_ts_builders_src_NamedType --> n0_kages_ts_builders_src_Writer n2_es_ts_builders_src_NamedType --> n8_lders_src_OperatorPrecedence n3__ts_builders_src_TypeBuilder --> n5_ts_builders_src_BasicBuilder n3__ts_builders_src_TypeBuilder --> n0_kages_ts_builders_src_Writer n3__ts_builders_src_TypeBuilder --> n8_lders_src_OperatorPrecedence n0_kages_ts_builders_src_Writer --> n5_ts_builders_src_BasicBuilder n7_es_ts_builders_src_stringify --> n5_ts_builders_src_BasicBuilder n7_es_ts_builders_src_stringify --> n0_kages_ts_builders_src_Writer classDef cyc stroke:#ef4444,stroke-width:2px; class n0_kages_ts_builders_src_Writer,n4_es_core_src_types_tool_types,n5_ts_builders_src_BasicBuilder cyc;

Dependencies

18 of 74 declared dependencies are a major version behind. Resolved 74 of 74 against the registry.

Package	Declared	Latest	Behind
`fern-api`	^0.51.39	5.106.1	5 major
`@types/node`	^24.10.2	26.2.0	2 major
`typescript`	^5.9.3	7.0.2	2 major
`@shikijs/twoslash`	^3.21.0	4.4.3	1 major
`@vercel/analytics`	^1.6.1	2.0.1	1 major
`fumadocs-mdx`	^14.2.4	15.2.3	1 major
`fumadocs-openapi`	^10.2.2	11.3.4	1 major
`lucide-react`	^0.562.0	1.31.0	1 major

Open in Code Brain → See its neighbourhood →

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

critical1

high2

medium7

low1

Replace write-all with the scopes the job actually needscritical

.github/workflows/publish_docs.yml

permissions: write-all

One malicious step gets simultaneous write to code, packages, releases, deployments and Actions itself.

Fix: Enumerate only the scopes each job uses and default the workflow to contents: read.

Pin third-party GitHub Actions to a commit SHAhigh3 occurrences

.github/workflows

softprops/action-gh-release@v2, oven-sh/setup-bun@v2, pypa/gh-action-pypi-publish@release/v1

A tag can be moved, so the action running with your token and secrets is whatever its owner last pushed; this is how tj-actions/changed-files leaked secrets from thousands of repos.

Fix: Replace each @vN with the 40-character commit SHA, keep # vN as a comment, and let Dependabot bump the SHAs.

Upgrade the pinned dependency carrying a published advisoryhigh31 occurrences

next@16.1.0 CVE-2026-44575 (high) +30 more

The pinned version is the one that installs, so a published advisory against it describes this deployment rather than a hypothetical one, and the advisory is also a public description of how to exploit it.

Fix: Upgrade to the fixed version named in the advisory, then commit the lockfile.

Declare least-privilege permissions for GITHUB_TOKENmedium2 occurrences

.github/workflows/cli.test-installation.yml

2 workflow(s) declare no permissions, 1 of them reference secrets

With no declaration the token inherits the repository default, so any injected step can push commits or mint releases from inside your own CI.

Fix: Add permissions: contents: read at the top of the workflow and widen per job only where needed.

Pin the container base image by digestmedium2 occurrences

Dockerfile

debian:bookworm-slim, debian:bookworm-slim

An untagged or mutable base means today's build and last month's contain different libc and a different CVE set, with no record of which shipped.

Fix: Use image:tag@sha256:<digest> and enable Dependabot's docker ecosystem.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Move large binaries to Git LFS or out of the repositorymedium

docs/public/data/toolkits.json

1 blobs over 5MB: toolkits.json 6.9MB

One repository here carries twenty blobs over 5MB including a 10.9MB spreadsheet, so every clone and every CI checkout pays for data nobody diffs.

Fix: Track those extensions with LFS, or move datasets to object storage and fetch them in a setup step.

Set persist-credentials: false on checkoutmedium

.github/workflows/build-cli-binaries.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add a non-root USER to the imagemedium

Dockerfile

CMD or ENTRYPOINT with no USER directive

A process running as root in the container is root against every mounted volume, and it turns any container escape or writable-mount mistake from a contained problem into a host one.

Fix: Create an unprivileged user, chown what it needs, and end the Dockerfile with USER.

Review the install lifecycle script and disable scripts in CImedium

package.json

preinstall

Install scripts are the execution vector for every npm compromise from event-stream onward, and a postinstall that fetches a binary makes the build depend on a URL nobody reviews.

Fix: Move the work into an explicit build step, or set ignore-scripts in CI and run it by name.

Set timeout-minutes on the workflow jobslow4 occurrences

.github/workflows/build-cli-binaries.yml

4 workflow(s) declare no job timeout

A wedged step runs to the six-hour platform default, which on a two-hourly schedule means three runs overlap behind it.

Fix: Add timeout-minutes with a realistic bound to each job.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.

View on GitHub All Projects