Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 21, 03:37 UTC
| 1 | # AGENTS.md |
| 2 | |
| 3 | Repository guidance for Codex, Claude Code, Cursor, pi.dev, and other AI coding agents. |
| 4 | |
| 5 | ## Scope |
| 6 | |
| 7 | This is the Composio SDK v3 monorepo. Most product code lives in `ts/` and `python/`; docs live in `docs/`. Branch new work from `next` and target PRs at `next` unless the user says otherwise. |
| 8 | |
| 9 | ## First Steps |
| 10 | |
| 11 | 1. Read the nearest nested `AGENTS.md` before editing a subtree. |
| 12 | 2. Preserve unrelated dirty work. Do not revert, delete, or reformat files outside the requested scope. |
| 13 | 3. Treat `.agents/skills` as the canonical local skill tree. `.claude/skills` is a compatibility symlink and must not be edited as a separate copy. |
| 14 | 4. Do not edit generated SDK surfaces or vendor trees — see [Generated And Vendored Paths](#generated-and-vendored-paths). |
| 15 | 5. Verify every command you write against the current `package.json`, `Makefile`, `noxfile.py`, or workflow file. |
| 16 | |
| 17 | ## Contribution Policy |
| 18 | |
| 19 | Follow the [Contribution Policy in `CONTRIBUTING.md`](CONTRIBUTING.md#contribution-policy). When helping an author prepare a PR: |
| 20 | |
| 21 | - Composio team members and designated maintainers can open PRs directly. External contributors need an existing, open issue; if none is linked, tell the author to open one first. For large external changes, get maintainer agreement on the approach before implementation. |
| 22 | - [@jkomyno](mailto:alberto@composio.dev) is the designated PR reviewer. Involve the relevant owner when the change needs their expertise. |
| 23 | - Keep the change focused on meaningful improvements to the SDKs, CLI, or docs. Don't produce cosmetic, speculative, or drive-by edits. |
| 24 | - The author is responsible for every line. Keep diffs small enough to read, report the checks you actually ran, and tell the author to review the full diff before submitting. |
| 25 | - Follow the [third-party links policy](CONTRIBUTING.md#third-party-links-in-docs). Authoritative technical references needed to use or contribute to Composio are allowed; other third-party links and promotional content must fit the listed exceptions. Route partnership requests to https://composio.dev/contact. |
| 26 | |
| 27 | ## Skill Routing |
| 28 | |
| 29 | Use the smallest relevant skill: |
| 30 | |
| 31 | - `repo-guidance`: repo layout, branch/PR workflow, changesets, generated files, or cross-repo maintenance. |
| 32 | - `skill-maintenance`: adding or changing local skills, skill references, compatibility mirrors, or validation. |
| 33 | - `verify-change`: resumable task records, verification profiles, revision-bound receipts, or carrying work between coding agents. |
| 34 | - `bug-fixing`: fixing a defect and choosing regression tests. |
| 35 | - `cross-sdk-parity`: aligning TypeScript and Python behavior, generated client bumps, or API contract drift. |
| 36 | - `docs-decisions`: docs site work, changelogs, docs decisions, or docs automation. |
| 37 | - `good-docs-writing`: drafting or revising docs prose in the house writing voice. |
| 38 | - `good-docs-audit`: reviewing existing docs or prose against that voice and reporting violations. |
| 39 | - `eve`: durable backend AI agents built with the eve framework. |
| 40 | - `typescript-sdk`, `typescript-testing`, `typescript-providers`: TypeScript SDK/core/provider work. |
| 41 | - `cli-command`, `cli-e2e`: CLI design/implementation or CLI end-to-end tests. |
| 42 | - `cli-release`: first-party CLI beta builds, stable promotion, release verification, or recovery. |
| 43 | - `python-sdk`, `python-testing`, `python-providers`, `python-release`: Python SDK/provider/testing/release work. |
| 44 | |
| 45 | ## Repository Map |
| 46 | |
| 47 | ```text |
| 48 | ts/ TypeScript SDK workspace |
| 49 | packages/core/ @composio/core |
| 50 | packages/providers/ TypeScript provider adapters |
| 51 | packages/cli/ Effect-based CLI |
| 52 | e2e-tests/ Docker runtime and CLI E2E tests |
| 53 | python/ Python SDK and provider packages |
| 54 | docs/ Fumadocs documentation site |
| 55 | .agents/skills/ Canonical local agent skills |
| 56 | docs/agent-guidance/ Neutral docs-agent context and workflow instructions |
| 57 | docs/decisions/ Neutral docs decisions and ADR-style records |
| 58 | ``` |
| 59 | |
| 60 | ## Generated And Vendored Paths |
| 61 | |
| 62 | Do not hand-edit these. They are regenerated or vendored, and edits will be overwritten. They are also marked `linguist-generated`/`linguist-vendored` in `.gitattributes`. |
| 63 | |
| 64 | - `ts/vendor/**` — vendored read-only snapshots of Effect and Clack (git submodules); reference only. |
| 65 | - `ts/packages/core/generated/**`, `ts/packages/core/pack/generated/**` — generated SDK surfaces produced by `composio generate` / the build pipeline. |
| 66 | - `pnpm-lock.yaml`, `uv.lock`, `**/bun.lock` — package-manager lockfiles; change them by running the package manager, never by hand. |
| 67 | |
| 68 | ## Common Commands |
| 69 | |
| 70 | Use `mise install` for the pinned toolchain. pnpm is managed through mise, not Corepack. |
| 71 | |
| 72 | ```bash |
| 73 | pnpm install |
| 74 | pnpm build |
| 75 | pnpm build:packages |
| 76 | pnpm lint |
| 77 | pnpm format |
| 78 | pnpm typecheck |
| 79 | pnpm test |
| 80 | pnpm test:e2e |
| 81 | pnpm test:e2e:cli |
| 82 | bun run validate:agent-skills |
| 83 | bun run validate:skill-routing |
| 84 | bun run typecheck:agent-workflow |
| 85 | bun run test:agent-workflow |
| 86 | ``` |
| 87 | |
| 88 | Both validators are deterministic Bun TypeScript programs; the guidance validator uses the existing Zod dependency to read package manifests. `.github/workflows/agent-substrate.yml` runs them in CI on every push and pull request — the stale-guidance scan covers the whole repo, so any change can affect the result. |
| 89 | |
| 90 | Python commands run from `python/` unless otherwise noted: |
| 91 | |
| 92 | ```bash |
| 93 | make env |
| 94 | source .venv/bin/activate |
| 95 | make fmt |
| 96 | make chk |
| 97 | make tst |
| 98 | make snt |
| 99 | make build |
| 100 | ``` |
| 101 | |
| 102 | ## Release And Package Notes |
| 103 | |
| 104 | - Stable Python and TypeScript SDK releases share Changesets. Public SDK behavior changes need a note for each affected package/language; Python uses the private `@composio/python-sdk` marker. See `ts/docs/internal/release.md` for the shared request/approval/retry process. |
| 105 | - `@composio/cli` is excluded from Changesets; use `cli-release` for CLI binaries and never target that package in a changeset while it remains ignored. |
| 106 | - Documentation-only and agent-guidance-only changes do not need a changeset. |
| 107 | - Python release metadata lives in `python/pyproject.toml`, `python/setup.py`, and `uv.lock`. |
| 108 | - Bumping generated clients is manual. Verify the package version is published before changing pins. |
| 109 | |
| 110 | ## Local Guidance Files |
| 111 | |
| 112 | - TypeScript workspace: `ts/AGENTS.md` |
| 113 | - Core SDK: `ts/packages/core/AGENTS.md` |
| 114 | - TypeScript providers: `ts/packages/providers/AGENTS.md` |
| 115 | - CLI: `ts/packages/cli/AGENTS.md` |
| 116 | - E2E tests: `ts/e2e-tests/AGENTS.md` |
| 117 | - Python SDK: `python/AGENTS.md` |
| 118 | - Python providers: `python/providers/AGENTS.md` |
| 119 | - Docs: `docs/AGENTS.md` |