@devries-cameron20 / composio-1 / commits / dcb6768e0
Fork 0

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

chore: switch changelog-to-docs workflow to Codex and add AGENTS.md

Replace claude-code-action (which doesn't support push events) with openai/codex-action in the changelog-to-docs workflow. Codex runs on push to next, updates docs, and creates a PR with the changes. Add AGENTS.md as a tool-agnostic version of CLAUDE.md that any AI coding agent (Codex, Claude, etc.) can use for repo context. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmitha Mallesh committed Feb 23, 2026 at 16:33 UTC dcb6768e0b54fb8d965cf49e9de48f0e233d8a34
2 files changed +237 -5
.github/workflows/docs.changelog-to-docs.yml
+33 -5
@@ -14,8 +14,6 @@ jobs:
14 permissions:
15 contents: write
16 pull-requests: write
17 - issues: write
18 - id-token: write
17
18 steps:
19 - name: Checkout repository
@@ -44,11 +42,11 @@ jobs:
42 echo "EOF" >> $GITHUB_OUTPUT
43 fi
44
47 - - name: Claude suggests docs updates
45 + - name: Codex updates docs
46 if: steps.detect.outputs.found == 'true'
49 - uses: anthropics/claude-code-action@v1
47 + uses: openai/codex-action@v1
48 with:
51 - anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
49 + openai-api-key: ${{ secrets.OPENAI_API_KEY }}
50 prompt: |
51 New changelog entries were merged to next. Read the agent instructions and update documentation accordingly.
52
@@ -58,3 +56,33 @@ jobs:
56 3. For each change, search docs/content/docs/ for pages that need updating
57 4. Make the documentation updates following the agent instructions
58 5. If no docs changes are needed, make no file changes and explain why
59 +
60 + - name: Create PR if docs changed
61 + if: steps.detect.outputs.found == 'true'
62 + env:
63 + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
64 + run: |
65 + if [ -z "$(git status --porcelain)" ]; then
66 + echo "No documentation changes needed"
67 + exit 0
68 + fi
69 +
70 + BRANCH="docs/changelog-update-${GITHUB_SHA::7}"
71 + git config user.name "github-actions[bot]"
72 + git config user.email "github-actions[bot]@users.noreply.github.com"
73 + git checkout -b "$BRANCH"
74 + git add -A
75 + git commit -m "docs: update documentation for new changelog entries"
76 + git push -u origin "$BRANCH"
77 +
78 + gh pr create \
79 + --base next \
80 + --head "$BRANCH" \
81 + --title "docs: update documentation for new changelog entries" \
82 + --body "$(cat <<'EOF'
83 + ## Summary
84 + Automated documentation updates triggered by new changelog entries merged to next.
85 +
86 + Generated by Codex via GitHub Actions.
87 + EOF
88 + )"
AGENTS.md new
+204
@@ -0,0 +1,204 @@
1 +# AGENTS.md
2 +
3 +This file provides guidance to AI coding agents (Codex, Claude Code, etc.) when working with code in this repository.
4 +
5 +## Overview
6 +
7 +This is the Composio SDK v3 repository containing both TypeScript and Python SDKs. The main development focus is on the TypeScript SDK located in `/ts/` directory. The project uses a monorepo structure with multiple packages and examples.
8 +
9 +## Notes
10 +
11 +- For documentation tasks, refer to `docs/CLAUDE.md`
12 +- Vendor submodules in `ts/vendor/` are **read-only reference only** — do not modify them
13 +
14 +## Common Development Commands
15 +
16 +### Build and Development
17 +```bash
18 +pnpm build # Build all packages
19 +pnpm build:packages # Build only TypeScript packages
20 +pnpm clean # Clean build artifacts
21 +pnpm lint # Lint code
22 +pnpm lint:fix # Lint and auto-fix
23 +pnpm format # Format code
24 +pnpm test # Run tests
25 +```
26 +
27 +### Package Management
28 +```bash
29 +pnpm install # Install dependencies
30 +pnpm check:peer-deps # Check peer dependencies
31 +pnpm update:peer-deps # Update peer dependencies
32 +```
33 +
34 +### Creating New Components
35 +```bash
36 +pnpm create:provider <provider-name> [--agentic]
37 +pnpm create:example <example-name>
38 +```
39 +
40 +### Release Management
41 +```bash
42 +pnpm changeset # Create changeset for releases
43 +pnpm changeset:version # Version packages
44 +pnpm changeset:release # Publish packages
45 +```
46 +
47 +## Project Architecture
48 +
49 +### Repository Structure
50 +```
51 +composio/
52 +├── ts/ # TypeScript SDK (main development)
53 +│ ├── packages/
54 +│ │ ├── core/ # Core SDK functionality
55 +│ │ ├── providers/ # AI provider integrations (OpenAI, Anthropic, etc.)
56 +│ │ ├── cli/ # Command-line interface (Effect.ts + @clack/prompts)
57 +│ │ ├── json-schema-to-zod/ # Schema conversion utility
58 +│ │ └── ts-builders/ # TypeScript code generation utilities
59 +│ ├── vendor/ # Read-only reference submodules (Effect, Clack)
60 +│ └── examples/ # Usage examples for different providers
61 +├── python/ # Python SDK
62 +├── docs/ # Documentation (Fumadocs)
63 +└── examples/ # Cross-platform examples
64 +```
65 +
66 +### Core Packages
67 +
68 +**@composio/core** — Main SDK functionality:
69 +- `src/composio.ts` — Main Composio class
70 +- `src/models/` — Core models (Tools, Toolkits, ConnectedAccounts, etc.)
71 +- `src/provider/` — Base provider implementations
72 +- `src/services/` — Internal services (telemetry, pusher)
73 +- `src/types/` — TypeScript type definitions
74 +- `src/utils/` — Utility functions and helpers
75 +
76 +**Provider Packages** — AI integrations:
77 +- `@composio/openai`, `@composio/anthropic`, `@composio/google`
78 +- `@composio/langchain`, `@composio/vercel`, `@composio/mastra`
79 +
80 +### Key Concepts
81 +
82 +- **Tools** — Individual functions (e.g., GITHUB_CREATE_REPO, GMAIL_SEND_EMAIL)
83 +- **Toolkits** — Collections of related tools grouped by service (github, gmail, slack)
84 +- **Connected Accounts** — User authentication/authorization for external services
85 +- **Auth Configs** — Configuration for different authentication methods
86 +- **Custom Tools** — User-defined tools with custom logic
87 +- **Providers** — Integrations with AI frameworks (OpenAI, Anthropic, etc.)
88 +- **Modifiers** — Middleware to transform tool inputs/outputs
89 +
90 +## Development Workflow
91 +
92 +### Testing
93 +- Unit tests use **Vitest** — run with `pnpm test`
94 +- Tests are in `test/` directories within each package
95 +- Mock implementations in `test/utils/mocks/`
96 +
97 +### Code Quality
98 +- **ESLint** — config in `eslint.config.mjs`
99 +- **Prettier** — for code formatting
100 +- **TypeScript** — strict mode enabled
101 +- **Husky** — pre-commit hooks for quality checks
102 +
103 +### TypeScript E2E Tests
104 +```bash
105 +pnpm test:e2e # All (Node.js + Deno + Cloudflare)
106 +pnpm test:e2e:node # Node.js CJS/ESM compatibility (Docker)
107 +pnpm test:e2e:deno # Deno npm: specifier compatibility (Docker)
108 +pnpm test:e2e:cloudflare # Cloudflare Workers
109 +```
110 +
111 +## Environment Variables
112 +
113 +```bash
114 +COMPOSIO_API_KEY # Required: Your Composio API key
115 +COMPOSIO_BASE_URL # Optional: Custom API base URL
116 +COMPOSIO_LOG_LEVEL # Optional: silent, error, warn, info, debug
117 +COMPOSIO_DISABLE_TELEMETRY # Optional: Set to "true" to disable telemetry
118 +```
119 +
120 +## Key Files and Locations
121 +
122 +- **Main SDK Entry**: `ts/packages/core/src/index.ts`
123 +- **Core Composio Class**: `ts/packages/core/src/composio.ts`
124 +- **Type Definitions**: `ts/packages/core/src/types/`
125 +- **Error Classes**: `ts/packages/core/src/errors/`
126 +- **Documentation**: `docs/`
127 +- **Build Configs**: `turbo.jsonc`, `tsconfig.base.json`, `tsdown.config.base.ts`
128 +
129 +## Common Patterns
130 +
131 +### Tool Execution
132 +```typescript
133 +const composio = new Composio({ apiKey: 'your-key' });
134 +const result = await composio.tools.execute('TOOL_NAME', {
135 + userId: 'user-id',
136 + arguments: { /* tool args */ }
137 +});
138 +```
139 +
140 +### Provider Integration
141 +```typescript
142 +import { OpenAIProvider } from '@composio/openai';
143 +const provider = new OpenAIProvider({ apiKey: 'openai-key' });
144 +const tools = await composio.tools.get('user-id', { toolkits: ['github'] });
145 +const wrappedTools = provider.wrapTools(tools);
146 +```
147 +
148 +### Custom Tool Creation
149 +```typescript
150 +import { z } from 'zod';
151 +
152 +const customTool = await composio.tools.createCustomTool({
153 + name: 'My Tool',
154 + description: 'Tool description',
155 + slug: 'MY_TOOL',
156 + inputParams: z.object({
157 + param: z.string().describe('Parameter description')
158 + }),
159 + execute: async (input) => {
160 + return {
161 + data: { result: input.param },
162 + error: null,
163 + successful: true
164 + };
165 + }
166 +});
167 +```
168 +
169 +## Python SDK Development
170 +
171 +### Setup
172 +```bash
173 +cd python
174 +make env # Create virtual env with all dependencies
175 +source .venv/bin/activate
176 +```
177 +
178 +### Commands
179 +```bash
180 +make fmt # Format code (ruff)
181 +make chk # Check linting and type issues
182 +make tst # Run tests
183 +make snt # Run sanity tests
184 +make build # Build packages
185 +```
186 +
187 +### Code Quality
188 +- **Formatter**: Ruff (Black-compatible, 88 char line length)
189 +- **Linter**: Ruff
190 +- **Type Checker**: mypy with strict optional typing
191 +- **Test Framework**: pytest with markers (core, openai, langchain, agno)
192 +- **Python Version**: >=3.10, <4
193 +
194 +## Maintenance Tasks
195 +
196 +### When Updating GitHub Actions
197 +
198 +Update the "Prerequisites" section in `ts/docs/internal/release.md` with current tool versions:
199 +
200 +- **Node.js**: `cat .nvmrc`
201 +- **Bun**: `cat .bun-version`
202 +- **pnpm**: `cat package.json | jq -r .packageManager | cut -d'@' -f2`
203 +
204 +This monorepo uses pnpm workspaces and Turbo for efficient builds and development.