Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: update CLAUDE.md for composio SDK
Zen Agentf273e95f922b
diff --git a/CLAUDE.md b/CLAUDE.mdindex a0f516094..cd9ef06a2 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -1,404 +1,97 @@# CLAUDE.md-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.+Guidance for Claude Code when working in this repository. For Codex / generic-agent guidance see `AGENTS.md`.## Overview-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.+Composio SDK v3 — monorepo containing the **TypeScript SDK** (primary, under `ts/`) and the **Python SDK** (under `python/`). Built with **pnpm workspaces + Turbo** for TS, **uv + nox** for Python. Default branch: `next`.-## Memories and Notes+## Repository Layout-- For documentation tasks, refer to `docs/CLAUDE.md`--## Effect.ts Reference Source--The CLI package (`@composio/cli`) is built on the Effect.ts ecosystem. A local copy of the Effect source code is available as a git submodule:--- **Location:** `ts/vendor/effect/`-- **Repo:** [Effect-TS/effect](https://github.com/Effect-TS/effect)-- **Branch:** `main`--When working on CLI code, reference the Effect source for accurate patterns:-- `ts/vendor/effect/packages/effect/src/` — core Effect runtime-- `ts/vendor/effect/packages/cli/src/` — @effect/cli (Command, Options, Args)-- `ts/vendor/effect/packages/platform/src/` — @effect/platform (FileSystem, Terminal)--**Important:** The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/`. The CLI's actual dependencies come from npm via `pnpm install`.--## Clack Reference Source--The CLI uses [`@clack/prompts`](https://github.com/bombshell-dev/clack) for interactive terminal UI. A local copy of the Clack source code is available as a git submodule:--- **Location:** `ts/vendor/clack/`-- **Repo:** [bombshell-dev/clack](https://github.com/bombshell-dev/clack)--When working on CLI prompts and terminal UI, reference the Clack source for accurate APIs:-- `ts/vendor/clack/packages/prompts/src/` — `@clack/prompts` (high-level API: text, select, confirm, spinner, etc.)-- `ts/vendor/clack/packages/core/src/` — `@clack/core` (low-level primitives)--See `ts/packages/cli/AGENTS.md` for detailed Clack usage guidelines.--**Important:** The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/`. The CLI's actual `@clack/prompts` dependency comes from npm via `pnpm install`.--## Common Development Commands--### Build and Development-```bash-# Build all packages-pnpm build--# Build only TypeScript packages-pnpm build:packages--# Clean build artifacts-pnpm clean-pnpm clean:workspace--# Lint code-pnpm lint-pnpm lint:fix--# Format code-pnpm format--# Run tests-pnpm test-```--### Package Management-```bash-# Install dependencies-pnpm install--# Check peer dependencies-pnpm check:peer-deps--# Update peer dependencies-pnpm update:peer-deps-```--### Creating New Components-```bash-# Create a new provider-pnpm create:provider <provider-name> [--agentic]--# Create a new example-pnpm create:example <example-name>-```--### Release Management-```bash-# Create changeset for releases-pnpm changeset--# Version packages-pnpm changeset:version--# Publish packages-pnpm changeset:release-```--## Project Architecture--### Repository Structure```composio/-├── ts/ # TypeScript SDK (main development)+├── ts/│ ├── packages/-│ │ ├── core/ # Core SDK functionality-│ │ ├── providers/ # AI provider integrations (OpenAI, Anthropic, etc.)-│ │ ├── cli/ # Command-line interface-│ │ ├── json-schema-to-zod/ # Schema conversion utility-│ │ └── ts-builders/ # TypeScript code generation utilities-│ └── examples/ # Usage examples for different providers-├── python/ # Python SDK-├── docs/ # Documentation (Fumadocs)-└── examples/ # Cross-platform examples-```--### Core Packages--**@composio/core** - Main SDK functionality:-- `src/composio.ts` - Main Composio class-- `src/models/` - Core models (Tools, Toolkits, ConnectedAccounts, etc.)-- `src/provider/` - Base provider implementations-- `src/services/` - Internal services (telemetry, pusher)-- `src/types/` - TypeScript type definitions-- `src/utils/` - Utility functions and helpers--**Provider Packages** - AI integrations:-- `@composio/openai` - OpenAI integration-- `@composio/anthropic` - Anthropic integration-- `@composio/google` - Google GenAI integration-- `@composio/langchain` - LangChain integration-- `@composio/vercel` - Vercel AI integration-- `@composio/mastra` - Mastra integration--### Key Concepts--**Tools** - Individual functions that can be executed (e.g., GITHUB_CREATE_REPO, GMAIL_SEND_EMAIL)--**Toolkits** - Collections of related tools grouped by service (e.g., github, gmail, slack)--**Connected Accounts** - User authentication/authorization for external services--**Auth Configs** - Configuration for different authentication methods--**Custom Tools** - User-defined tools with custom logic--**Providers** - Integrations with AI frameworks (OpenAI, Anthropic, etc.)--**Modifiers** - Middleware to transform tool inputs/outputs--## Development Workflow--### For Tool Development-1. Tools are auto-generated from OpenAPI specifications-2. Custom tools can be created using the Custom Tools API-3. Tool execution happens through the main Composio class--### For Provider Development-1. Use `pnpm create:provider <name>` to scaffold new providers-2. Implement required methods: `wrapTool`, `wrapTools`-3. For agentic providers, also implement execution handlers-4. Add comprehensive tests and documentation--### Testing-- Unit tests use Vitest-- Run tests with `pnpm test`-- Tests are located in `test/` directories within each package-- Mock implementations are available in `test/utils/mocks/`--### Code Quality-- ESLint configuration in `eslint.config.mjs`-- Prettier for code formatting-- TypeScript strict mode enabled-- Comprehensive TSDoc documentation required-- Husky pre-commit hooks for quality checks--## Environment Variables--```bash-COMPOSIO_API_KEY # Required: Your Composio API key-COMPOSIO_BASE_URL # Optional: Custom API base URL-COMPOSIO_LOG_LEVEL # Optional: Logging level (silent, error, warn, info, debug)-COMPOSIO_DISABLE_TELEMETRY # Optional: Set to "true" to disable telemetry-DEVELOPMENT # Development mode flag-CI # CI environment flag-```--## Key Files and Locations--- **Main SDK Entry**: `ts/packages/core/src/index.ts`-- **Core Composio Class**: `ts/packages/core/src/composio.ts`-- **Type Definitions**: `ts/packages/core/src/types/`-- **Error Classes**: `ts/packages/core/src/errors/`-- **Examples**: `ts/examples/` and `examples/`-- **Documentation**: `docs/`-- **Build Configs**: `turbo.jsonc`, `tsconfig.base.json`, `tsdown.config.base.ts`-- **E2E Tests**: `ts/e2e-tests/`--## Maintenance Tasks--### When Updating GitHub Actions--When modifying files in `.github/workflows/`, update the "Prerequisites" section in `ts/docs/internal/release.md` with the current tool versions:--- **Node.js**: `cat .nvmrc`-- **Bun**: `cat .bun-version`-- **pnpm**: `cat package.json | jq -r .packageManager | cut -d'@' -f2`--## Testing Commands+│ │ ├── core/ # @composio/core — main SDK+│ │ ├── providers/ # @composio/openai, anthropic, google, langchain, vercel, mastra, ...+│ │ ├── cli/ # @composio/cli — Effect.ts + Bun (see ts/packages/cli/AGENTS.md)+│ │ ├── cli-keyring/ # @composio/cli-keyring — macOS Keychain / Linux Secret Service+│ │ ├── cli-local-tools/ # @composio/cli-local-tools — local toolkit declarations+│ │ ├── json-schema-to-zod/+│ │ └── ts-builders/ # AST builders for code generation+│ ├── vendor/ # Read-only Effect + Clack submodules (do NOT modify)+│ ├── e2e-tests/ # Docker-based Node/Deno/Cloudflare runtime tests+│ └── examples/+├── python/ # Python SDK (composio, providers, examples)+└── docs/ # Fumadocs site (see docs/CLAUDE.md)+```++## TypeScript Commands```bash-# Run all tests-pnpm test--# Run tests for core package only-cd ts/packages/core && pnpm test--# Run tests with UI-pnpm test:ui-```--### TypeScript E2E Tests--E2E tests for `@composio/core` are located in `ts/e2e-tests/` and test runtime compatibility across different JavaScript environments.--```bash-# Run all e2e tests (Node.js + Deno + Cloudflare)-pnpm test:e2e--# Run only Node.js e2e tests (CJS/ESM compatibility, runs in Docker)-pnpm test:e2e:node--# Run only Deno e2e tests (npm: specifier compatibility, runs in Docker)-pnpm test:e2e:deno--# Run only Cloudflare Workers e2e tests+pnpm install # First-time setup. Use BYPASS_BUN_VERSION_CHECK=1 if .bun-version mismatch+pnpm build # Build all packages (Turbo)+pnpm build:packages # TS packages only+pnpm lint / lint:fix+pnpm format+pnpm typecheck # MANDATORY before pushing CLI changes+pnpm test # Vitest, all packages+pnpm test:e2e # All runtimes (Node CJS+ESM, Deno, Cloudflare Workers) via Docker+pnpm test:e2e:node # Override with COMPOSIO_E2E_NODE_VERSION=22.12.0+pnpm test:e2e:deno # Override with COMPOSIO_E2E_DENO_VERSION=2.6.7pnpm test:e2e:cloudflare--# Run Node.js tests with a specific Node version-COMPOSIO_E2E_NODE_VERSION=22.12.0 pnpm test:e2e:node--# Run Deno tests with a specific Deno version-COMPOSIO_E2E_DENO_VERSION=2.6.7 pnpm test:e2e:deno-```--**E2E Test Structure:**-```-ts/e2e-tests/-├── _utils/ # Shared Docker infrastructure-├── runtimes/-│ ├── node/ # Node.js runtime tests-│ │ ├── cjs-basic/ # CommonJS compatibility-│ │ └── esm-basic/ # ESM compatibility-│ ├── deno/ # Deno runtime tests-│ │ └── esm-basic/ # npm: specifier compatibility-│ └── cloudflare/ # Cloudflare runtime tests-│ └── cf-workers-basic/ # Cloudflare Workers tests-└── README.md # E2E test documentation+pnpm changeset # Create release changeset (required for stable CLI/SDK releases)+pnpm create:provider <name> [--agentic]+pnpm create:example <name>```-> **Note:** When adding new e2e tests, update `ts/e2e-tests/README.md` with the new test information.+Pinned tool versions: Node `.nvmrc` (20.20.2), Bun `.bun-version` (1.3.10), pnpm via `packageManager` in `package.json`. CI sets `BYPASS_BUN_VERSION_CHECK=1`; local sandboxes often need it too.-## Common Patterns+## Python Commands-### Tool Execution-```typescript-const composio = new Composio({ apiKey: 'your-key' });-const result = await composio.tools.execute('TOOL_NAME', {- userId: 'user-id',- arguments: { /* tool args */ }-});-```--### Provider Integration-```typescript-import { OpenAIProvider } from '@composio/openai';-const provider = new OpenAIProvider({ apiKey: 'openai-key' });-const tools = await composio.tools.get('user-id', { toolkits: ['github'] });-const wrappedTools = provider.wrapTools(tools);-```--### Custom Tool Creation-```typescript-import { z } from 'zod';--const customTool = await composio.tools.createCustomTool({- name: 'My Tool',- description: 'Tool description',- slug: 'MY_TOOL',- inputParams: z.object({- param: z.string().describe('Parameter description')- }),- execute: async (input) => {- // Implementation- return {- data: { result: input.param },- error: null,- successful: true- };- }-});-```--This monorepo uses pnpm workspaces and Turbo for efficient builds and development.--## Python SDK Development--### Setup-The Python SDK is located in the `/python/` directory and uses `uv` for dependency management and `nox` for automation.--### Environment Setup```bash-# Create and setup Python development environmentcd python-make env-source .venv/bin/activate+make env # uv-managed venv with all deps (NOT pre-built in sandboxes)+source .venv/bin/activate # ALWAYS activate before pytest/ruff/pip+make fmt # ruff format+make chk # ruff check + mypy+make tst / make snt # pytest / sanity tests+pytest -m core # Markers: core, openai, langchain, agno+make build / make bump```-### Python Development Commands-```bash-# Setup environment (creates virtual env with all dependencies)-make env--# Sync dependencies (when in an existing environment)-make sync--# Install provider packages-make provider--# Format code using ruff-make fmt-# Or directly: nox -s fmt+Python: >=3.10, <4. Formatter/linter: Ruff (88 char). Type checker: mypy strict. Core deps include `composio-client` (Stainless-generated; source repo is `ComposioHQ/composio-base-py`).-# Check linting and type issues-make chk-# Or directly: nox -s chk--# Fix linting issues-nox -s fix--# Run tests (requires implementing tst session)-make tst-# Or directly: nox -s tst--# Run sanity tests (requires implementing snt session)-make snt-# Or directly: nox -s snt--# Clean build artifacts-make clean-build--# Bump version-make bump+## Environment Variables-# Build packages-make build+```bash+COMPOSIO_API_KEY # Required+COMPOSIO_BASE_URL # Optional override+COMPOSIO_LOG_LEVEL # silent | error | warn | info | debug+COMPOSIO_DISABLE_TELEMETRY # "true" to disable```-### Python Project Structure-```-python/-├── composio/ # Main SDK package-├── providers/ # Provider implementations-├── tests/ # Test suite-├── examples/ # Usage examples-├── scripts/ # Development scripts-├── config/ # Configuration files-│ ├── pytest.ini # Pytest configuration-│ ├── mypy.ini # MyPy type checking config-│ ├── ruff.toml # Ruff linter/formatter config-│ └── codecov.yml # Code coverage config-├── Makefile # Development shortcuts-├── noxfile.py # Nox automation sessions-└── pyproject.toml # Project configuration-```+## Gotchas-### Python Code Quality-- **Formatter**: Ruff (Black-compatible, 88 char line length)-- **Linter**: Ruff with custom configuration-- **Type Checker**: mypy with strict optional typing-- **Test Framework**: pytest with custom markers (core, openai, langchain, agno)-- **Python Version**: >=3.10, <4-- **Dependency Managers**: uv+- **Default branch is `next`**, not `main`/`master`. Branch from `next` and target `next` for PRs.+- **Docs PRs also target `next`** (see `docs/CLAUDE.md` rule).+- `pnpm install` hard-fails on Bun version mismatch — use `BYPASS_BUN_VERSION_CHECK=1`.+- `ts/vendor/effect/` and `ts/vendor/clack/` are **read-only reference submodules** — npm provides the actual deps.+- The CLI is **Effect.ts + Bun**, not plain Node — see `ts/packages/cli/AGENTS.md` (CLI's `CLAUDE.md` is a symlink to it).+- E2E tests run in **Docker** and require Docker daemon access; skip them in restricted sandboxes.+- Tool execution code generation is auto-derived from OpenAPI specs in hermes — don't hand-edit generated files under `@composio/core/generated`.-### Python Testing-```bash-# Run tests with pytest markers-pytest -m core # Run core tests only-pytest -m openai # Run OpenAI provider tests-pytest -m langchain # Run LangChain provider tests-pytest -m agno # Run Agno provider tests-```+## Key Files-### Python Package Dependencies-- Core: `pysher`, `pydantic>=2.6.4`, `composio-client==1.4.0`, `typing-extensions>=4.0.0`, `openai`-- Dev: `nox`, `pytest`, `ruff`, `langchain_openai`, `fastapi`, `twine`, `click`, `semver`+- Main SDK entry: `ts/packages/core/src/index.ts`+- Core Composio class: `ts/packages/core/src/composio.ts`+- Types: `ts/packages/core/src/types/`, errors: `ts/packages/core/src/errors/`+- Build configs: `turbo.jsonc`, `tsconfig.base.json`, `tsdown.config.base.ts`+- CI release docs to update when bumping toolchain: `ts/docs/internal/release.md` (Node/Bun/pnpm versions)+- Python config: `python/Makefile`, `python/noxfile.py`, `python/config/{pytest.ini,ruff.toml}`-### Python Environment Variables-Same as TypeScript SDK, with additional:-```bash-OPENAI_API_KEY # Required for OpenAI provider examples-```\ No newline at end of file+## See Also++- `AGENTS.md` — Codex/generic-agent variant of this file+- `docs/CLAUDE.md` — Fumadocs site, link-checker, API-reference versioning+- `ts/packages/cli/AGENTS.md` — CLI architecture, services, commands, release flowdiff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.mdindex d61092e6a..f7445f453 100644--- a/ts/packages/cli/AGENTS.md+++ b/ts/packages/cli/AGENTS.md@@ -1,18 +1,18 @@# AGENTS.md-Instructions for AI agents working on `@composio/cli`.+Instructions for AI agents working on `@composio/cli`. The sibling `CLAUDE.md` is a symlink to this file.-## Architecture Overview+## Required Checks-The CLI is built on the **Effect.ts ecosystem** and runs on **Bun**. It follows a service-oriented architecture with dependency injection via Effect layers, generator-based control flow (`Effect.gen`), and structured error handling.+When you touch CLI code (anything under `ts/packages/cli/src/`), run `pnpm typecheck` from the repo root before pushing. Fix all type errors. Build/lint failures block CI.-## Required Checks+## Architecture-When you touch CLI commands (anything under `ts/packages/cli/src/commands/`), you must run `pnpm typecheck` from the repo root. If it fails, fix the issues before proceeding.+The CLI is built on the **Effect.ts ecosystem** and runs on **Bun**. Service-oriented architecture with dependency injection via Effect layers, generator-based control flow (`Effect.gen`), and structured error handling.-### Entry Point+### Entry Point — `src/bin.ts`-`src/bin.ts` bootstraps the CLI by composing Effect layers and running the root command via `BunRuntime.runMain()`:+Bootstraps the CLI by composing Effect layers and running the root command via `BunRuntime.runMain()`:- `CliConfigLive` — @effect/cli behavior (case-sensitive, no auto-correct, no built-ins)- `ComposioUserContextLive` — User authentication state from `~/.composio/`@@ -21,27 +21,44 @@ When you touch CLI commands (anything under `ts/packages/cli/src/commands/`), yo- `UpgradeBinaryLive` — Self-update from GitHub releases- `BunFileSystem.layer`, `BunContext.layer` — Bun runtime integration-Errors are captured via the custom `effect-errors/` module, which provides source-mapped stack traces, Effect span timelines, and formatted output.--### Commands (`src/commands/`)--Each command is declared with `@effect/cli`'s `Command.make()` pattern:--| Command | Description |-| -------------------------------------------------------- | ------------------------------------------------------------------------------------- |-| `composio version` | Display CLI version |-| `composio whoami` | Show logged-in user's API key |-| `composio login [--no-browser] [--no-wait] [--key text] [--user-api-key text] [--org text]` | Login with browser redirect or direct user API key |-| `composio logout` | Clear stored API key |-| `composio upgrade` | Self-update binary from GitHub releases |-| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |-| `composio generate ts` | Generate TypeScript type stubs for toolkits/tools/triggers |-| `composio generate py` | Generate Python type stubs |-| `composio manage <command>` | Manage Composio resources (toolkits, tools, accounts, triggers, logs, orgs, projects) |--Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.--### Services (`src/services/`)+Errors are captured via the custom `effect-errors/` module (source-mapped stack traces, Effect span timelines, formatted output).++### Commands — `src/commands/`++Each command uses `@effect/cli`'s `Command.make()` pattern. Top-level command files end in `.cmd.ts`; nested command groups live in their own subdirectory with a `<group>.cmd.ts` entry. Current top-level commands:++| Group / Command | Purpose |+| ------------------------- | ------------------------------------------------------------------------------------------------------ |+| `version` | Display CLI version |+| `whoami` | Show logged-in user info (writes raw API key to stdout when piped — see Output Conventions) |+| `login` | Login with browser redirect or direct user/API key (`--no-browser`, `--no-wait`, `--key`, `--user-api-key`, `--org`) |+| `logout` | Clear stored API key |+| `signup` | Create a Composio account |+| `upgrade` | Self-update binary from GitHub releases |+| `init` | Bootstrap a Composio project in the current directory |+| `install` | Install local-tool integrations |+| `generate {ts|py}` | Generate type stubs (auto-detects project language if no subcommand) |+| `agent` | Manage AI agent presets |+| `toolkits` | List / inspect / version toolkits |+| `tools` | List / inspect / `execute` tools |+| `triggers` | List / manage trigger types |+| `auth-configs` | Manage auth-config resources (`ac_*`) |+| `connected-accounts` | Manage connected accounts (`ca_*`) |+| `connections` | Alias / helper for connected-account flows |+| `orgs` | Manage organizations |+| `projects` | Manage projects |+| `local-tools` | Manage local toolkits (via `@composio/cli-local-tools`) |+| `logs` | View tool-execution logs (`logs-cmd/`) |+| `config` | Read/write CLI config |+| `listen` | Listen for events |+| `proxy` | Proxy authenticated API requests |+| `run` | Run a saved script / preset |+| `dev` | Developer-only utilities |+| `artifacts` | Manage generated artifacts |++Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation. Feature flags live in `feature-tags.ts` and `experimental-features.ts`.++### Services — `src/services/`| Service | Purpose || ---------------------------------- | ---------------------------------------------------------------------------- |@@ -50,330 +67,131 @@ Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.| `ComposioToolkitsRepository` | API client — fetches toolkits, tools, trigger types; validates versions || `ComposioToolkitsRepositoryCached` | Decorator over base repository with file-based caching and graceful fallback || `NodeOs` | OS abstraction (`homedir`, `platform`, `arch`) |-| `EnvLangDetector` | Detects project language (TS/Python) from config files and lock files |-| `JsPackageManagerDetector` | Detects npm/pnpm/yarn/bun for helpful install instructions |+| `EnvLangDetector` | Detects project language (TS/Python) from config / lock files |+| `JsPackageManagerDetector` | Detects npm/pnpm/yarn/bun for install instructions || `UpgradeBinary` | Fetches latest release from GitHub, downloads and replaces binary |-### Effects (`src/effects/`)--Reusable Effect computations for cross-cutting concerns:--| Effect | Purpose |-| ------------------------------ | --------------------------------------------------------------------- |-| `app-config` | Reads `COMPOSIO_*` env vars (API_KEY, BASE_URL, CACHE_DIR, etc.) |-| `debug-config` | Debug overrides (DEBUG_OVERRIDE_VERSION, etc.) |-| `force-config` | Force flags (FORCE_USE_CACHE) |-| `setup-cache-dir` | Ensures `~/.composio/` directory exists |-| `toolkit-version-overrides` | Parses `COMPOSIO_TOOLKIT_VERSION_<NAME>=<ver>` env vars |-| `validate-toolkit-versions` | Validates overrides against available API versions |-| `with-log-level` | Configures logger from CLI flag or env var |-| `find-composio-core-generated` | Locates `@composio/core` in node_modules (handles pnpm virtual store) |-| `version` | Resolves CLI version from package.json |-| `compare-semver` | Semantic version comparison for upgrade checks |-| `log-metrics` | Formats and logs API request count and bytes transferred |+OS credential storage uses the sibling package `@composio/cli-keyring` (macOS Keychain / Linux Secret Service).-### Models (`src/models/`)+### Effects — `src/effects/`-Effect Schema definitions for type-safe serialization:+Reusable Effect computations: `app-config` (reads `COMPOSIO_*` env), `debug-config`, `force-config`, `setup-cache-dir`, `toolkit-version-overrides` (parses `COMPOSIO_TOOLKIT_VERSION_<NAME>=<ver>`), `validate-toolkit-versions`, `with-log-level`, `find-composio-core-generated`, `version`, `compare-semver`, `log-metrics`.-- `Toolkit` — name, slug, auth_schemes, is_local_toolkit, meta-- `Tool` — name, slug, available_versions, input/output_parameters, description, tags-- `TriggerType` — slug, name, description, input/output parameters-- `UserData` — apiKey, baseURL, webURL (with defaults)-- `Session` — id, status (pending|linked), retrieved session with api_key+### Models — `src/models/`-Each model has `fromJSON`/`toJSON` helpers using `JSONTransformSchema()`.+Effect Schema definitions with `fromJSON` / `toJSON` helpers via `JSONTransformSchema()`: `Toolkit`, `Tool`, `TriggerType`, `UserData`, `Session`.-### Code Generation (`src/generation/`)+### Code Generation — `src/generation/`-Multi-stage pipeline for `composio generate ts` and `composio generate py`:+Pipeline for `composio generate {ts,py}`:-1. **Fetch** — Toolkits, tools, trigger types from API (optionally filtered by `--toolkits`)-2. **Index** — Groups tools/triggers by toolkit prefix into a `ToolkitIndex` map-3. **Generate** — Builds TypeScript/Python source using `@composio/ts-builders` AST builders-4. **Transpile** — Optionally converts TS → ESM JS (when writing to @composio/core/generated)+1. **Fetch** — Toolkits, tools, trigger types (filterable via `--toolkits`)+2. **Index** — Groups by toolkit prefix into `ToolkitIndex`+3. **Generate** — Builds TS/Python source using `@composio/ts-builders` AST builders+4. **Transpile** — Optionally converts TS → ESM JS for `@composio/core/generated`-Generated output includes toolkit objects, tool/trigger enums, and optionally full type definitions (with `--type-tools`).+`--type-tools` includes full type definitions.-### Error Handling (`src/effect-errors/`)+### Configuration-Custom error capture and formatting system:--- **Capture** — Extracts error chain from Effect's `Cause`, handles interrupts separately-- **Source maps** — Maps compiled `.mjs` stack traces back to TypeScript source-- **Spans** — Extracts timing from Effect spans for execution timeline display-- **Pretty print** — Colored, boxed error output with source context and suggestions--### UI & Output (`src/ui/`)--- `picocolors` and `ansis` for colored terminal output-- Respects `NO_COLOR` env var-- `@clack/prompts` symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`) for box-drawing in formatted output-- Effect's `Console.log()` / `Console.error()` for output--### Configuration (`src/cli-config.ts`, `src/constants.ts`)--- CLI behavior: `showBuiltIns: false`, `autoCorrectLimit: 0`, `isCaseSensitive: true`-- Prefixes: `COMPOSIO_` for app config, `DEBUG_OVERRIDE_` for debug-- User config stored in `~/.composio/`+- CLI: `cli-config.ts` — `showBuiltIns: false`, `autoCorrectLimit: 0`, `isCaseSensitive: true`+- Constants: `constants.ts` — env prefixes (`COMPOSIO_`, `DEBUG_OVERRIDE_`)+- User config: `~/.composio/user-config.json`- Cache files: `toolkits.json`, `tools.json`, `tools-as-enums.json`, `trigger-types.json`-### Effect.ts Patterns--The CLI uses the generator-based syntax throughout:--```typescript-Effect.gen(function* () {- const service = yield* ServiceName; // resolve dependency- const result = yield* someEffect; // await computation- yield* Effect.log('message'); // side effect- return result;-});-```--Key patterns:--- `Effect.all([...], { concurrency: 'unbounded' })` for parallel fetches-- `Layer.provide()` for dependency composition-- `Effect.mapError()` / `Effect.catchTag()` for typed error handling-- `Effect.scoped` for resource cleanup-### Key Dependencies-| Package | Role |-| ----------------------- | ------------------------------------------------------------------- |-| `effect` | Core runtime, data types, concurrency |-| `@effect/cli` | Command, Options, Args declaration and parsing |-| `@effect/platform` | FileSystem, Terminal abstraction |-| `@effect/platform-bun` | Bun runtime layer |-| `@clack/prompts` | Terminal UI — prompts, spinners, logs, notes (all output to stderr) |-| `ansis`, `picocolors` | Colored output |-| `@composio/client` | Raw Composio API client |-| `@composio/core` | Core SDK types and constants |-| `@composio/ts-builders` | TypeScript AST code generation |-| `semver` | Version comparison for upgrades |-| `open` | Opens URLs in browser (login flow) |-| `decompress` | Extracts downloaded binaries |-----+`effect`, `@effect/cli`, `@effect/platform`, `@effect/platform-bun`, `@clack/prompts` (terminal UI — stderr by default), `ansis` / `picocolors`, `@composio/client` (Composio API), `@composio/core` (types), `@composio/ts-builders` (AST gen), `@composio/cli-keyring` (OS credential store), `@composio/cli-local-tools` (local toolkit defs), `semver`, `open`, `decompress`.## Output Conventions: Composable CLI Output-The CLI follows the Unix convention of separating human-readable decoration from machine-readable data:+Follow the Unix convention of separating human-readable decoration from machine-readable data:-- **stdout** — data output only (`ui.output()`). This is what scripts and pipes capture.+- **stdout** — data only (`ui.output()`). Captured by pipes / `$(...)` / `> file`.- **stderr** — all decoration (Clack spinners, logs, notes, intro/outro). Visible in terminal, invisible in pipes.-### Rules--1. **All `TerminalUI` methods except `output()` write to stderr** via Clack's `{ output: process.stderr }` option — but only in interactive mode.-2. **`ui.output(data)` writes to stdout only when piped** — it checks `process.stdout.isTTY` and is a no-op in interactive terminals (the human already sees the data via decoration on stderr).-3. **When stdout is piped, ALL decoration is suppressed** — `isInteractive` (`process.stdout.isTTY`) gates every decoration method. Only `ui.output()` writes in piped mode. This keeps `composio whoami | pbcopy` completely silent.-4. **Action commands** (logout, upgrade) produce no stdout data — their output is purely decorative.-5. **Data commands** (whoami, version, login, generate) call both decoration (stderr) and `ui.output()` (stdout). In interactive mode, only decoration is visible. In pipes/scripts, only the raw data is captured.-6. **Never write data to stderr** — decoration methods are for human context only.-7. **Never write decoration to stdout** — it breaks pipes, `$(...)` captures, and `> file` redirects.--### Pattern+Rules:-```typescript-// Data command (e.g., whoami):-yield * ui.note(apiKey, 'API Key'); // Decoration → stderr (human sees pretty box)-yield * ui.output(apiKey); // Data → stdout (scripts capture plain value)--// Action command (e.g., login):-yield * ui.intro('composio login'); // Decoration → stderr-yield * ui.log.step('Redirecting'); // Decoration → stderr-// No ui.output() call — nothing for scripts to capture-```--### How it works in practice+1. All `TerminalUI` methods **except `output()`** write to stderr via Clack's `{ output: process.stderr }`, and only in interactive mode.+2. `ui.output(data)` writes to stdout **only when piped** (checked via `process.stdout.isTTY`).+3. When stdout is piped, **all decoration is suppressed** — `composio whoami | pbcopy` is completely silent and clipboard gets the clean key.+4. **Data commands** (whoami, version, login, generate, etc.) call both decoration (stderr) and `ui.output()` (stdout).+5. **Action commands** (logout, upgrade) produce no stdout data — output is purely decorative.+6. **Never** write data to stderr or decoration to stdout.-The CLI checks `process.stdout.isTTY` once at startup to determine the output mode:+When adding a new command: ask "Does this produce a value scripts should capture?" — yes → `ui.output(value)` + `ui.log.*`/`ui.note()`. No → decoration only.-- **Interactive** (`stdout` is TTY): decoration visible on stderr, `ui.output()` is a no-op.-- **Piped** (`stdout` is NOT TTY): decoration suppressed, `ui.output()` writes raw data to stdout.+## Effect.ts Patterns-```bash-composio whoami # Pretty box only (interactive)-composio whoami | pbcopy # Silent — clipboard gets clean key-API_KEY=$(composio whoami) # Silent — variable gets clean key-composio whoami > file.txt # Silent — file gets clean key+Generator-based syntax throughout:-composio version # Decorated version (interactive)-composio version | cat # Raw version string--composio login # All decoration visible, browser opens-composio login 2>/dev/null # Silent (but still opens browser, polls API)+```typescript+Effect.gen(function* () {+ const service = yield* ServiceName; // resolve dependency+ const result = yield* someEffect; // await computation+ yield* Effect.log('message');+ return result;+});```-### Adding new commands+Key patterns: `Effect.all([...], { concurrency: 'unbounded' })` for parallel work, `Layer.provide()` for dependency composition, `Effect.mapError()` / `Effect.catchTag()` for typed errors, `Effect.scoped` for resource cleanup.-When creating a new command, ask: "Does this command produce a value that scripts should capture?"+## Vendor Reference Sources-- **Yes** → Use `ui.output(value)` for the data, `ui.log.*` / `ui.note()` for context-- **No** → Use only `ui.log.*` / `ui.note()` / `ui.intro()` / `ui.outro()` — everything goes to stderr automatically-------## Clack Reference Source--The CLI uses [`@clack/prompts`](https://github.com/bombshell-dev/clack) for interactive terminal UI (prompts, spinners, logs, etc.). A local copy of the Clack source code is available as a git submodule:--- **Location:** `ts/vendor/clack/`-- **Repo:** [bombshell-dev/clack](https://github.com/bombshell-dev/clack)--When working on CLI code that involves terminal UI, reference the Clack source for accurate APIs and patterns:--- `ts/vendor/clack/packages/prompts/src/` — `@clack/prompts` (the high-level API used by this CLI)-- `ts/vendor/clack/packages/core/src/` — `@clack/core` (low-level primitives underlying prompts)--### Key modules in `@clack/prompts`--| Module | Purpose |-| ----------------------- | ------------------------------------------------------ |-| `text.ts` | Text input prompt |-| `password.ts` | Password input prompt |-| `confirm.ts` | Yes/no confirmation prompt |-| `select.ts` | Single-select list prompt |-| `multi-select.ts` | Multi-select list prompt |-| `group-multi-select.ts` | Grouped multi-select prompt |-| `autocomplete.ts` | Autocomplete/search prompt |-| `spinner.ts` | Loading spinner |-| `progress-bar.ts` | Progress bar |-| `log.ts` | Styled log messages |-| `note.ts` | Boxed note output |-| `task.ts` | Task runner with status |-| `task-log.ts` | Task with streaming log output |-| `stream.ts` | Streaming text output |-| `box.ts` | Box drawing utility |-| `messages.ts` | Intro/outro messages |-| `common.ts` | Shared symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`, etc.) |--### Current clack usage in the CLI--The CLI currently imports from `@clack/prompts`:--- `S_BAR`, `S_BAR_H`, `unicodeOr` — Unicode box-drawing symbols for custom formatted output--### Guidelines--- The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/clack/`.-- The CLI's actual dependency comes from npm (`@clack/prompts` v1.0.1) via `pnpm install`.-- When adding new interactive prompts or terminal UI, consult the source in `ts/vendor/clack/packages/prompts/src/` for the correct API surface and available options.-- Prefer `@clack/prompts` (high-level) over `@clack/core` (low-level) unless you need custom prompt behavior.-------## Effect.ts Reference Source--The CLI is built on the Effect.ts ecosystem. A local copy of the Effect source code is available as a git submodule:--- **Location:** `ts/vendor/effect/`-- **Repo:** [Effect-TS/effect](https://github.com/Effect-TS/effect)-- **Branch:** `main`--When working on CLI code, reference the Effect source for accurate patterns:+Read-only submodules under `ts/vendor/` (do NOT modify — actual deps come from npm):- `ts/vendor/effect/packages/effect/src/` — core Effect runtime-- `ts/vendor/effect/packages/cli/src/` — @effect/cli (Command, Options, Args)-- `ts/vendor/effect/packages/platform/src/` — @effect/platform (FileSystem, Terminal)--### Guidelines--- The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/effect/`.-- The CLI's actual dependencies come from npm via `pnpm install`.-----+- `ts/vendor/effect/packages/cli/src/` — `@effect/cli` (Command, Options, Args)+- `ts/vendor/effect/packages/platform/src/` — `@effect/platform`+- `ts/vendor/clack/packages/prompts/src/` — `@clack/prompts` (text, select, confirm, spinner, note, task, etc.)+- `ts/vendor/clack/packages/core/src/` — `@clack/core` primitives## CLI Design Guidelines-For principles on how to design CLI interactions (arguments, flags, help text, output, errors, interactivity, config precedence), see:+Principles for arguments, flags, help, output, errors, interactivity, config precedence:-- **Cursor rules**: `ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc`-- **Claude skill**: `.claude/skills/create-cli/SKILL.md` (standalone, trimmed for Claude Code context)+- Cursor rules: `ts/packages/cli/.cursor/rules/cli-design-guidelines.mdc`+- Claude skill: `/workspace/zen/skills/create-cli/` (also available as `/create-cli`)-Use these guidelines when adding new commands, designing flag interfaces, or making UX decisions for the CLI.-----+Use these when adding new commands or making UX decisions.## Recording CLI Demos-New commands should have VHS recordings for documentation. The recording script produces SVGs and asciicasts that demonstrate the CLI in action.--### Adding Recordings--1. Add entries to `recordings/recordings.yaml` under the appropriate group-2. Run `bun scripts/record.ts` (requires `COMPOSIO_API_KEY` and `vhs` on PATH)--### Recording Config--Each entry in `recordings.yaml` accepts:--| Field | Required | Description |-| ----------------- | -------- | --------------------------------------------------------------------------------------- |-| `name` | Yes | Filename stem (`<name>.svg`, `<name>.ascii`, `<name>.tape`) |-| `command` | Yes | Shell command to record |-| `description` | No | Comment shown instantly above the command (via VHS `Hide`/`Show`) |-| `sleepAfterEnter` | No | Wait time after Enter (default: `6s` from `vhs.sleepAfterEnter`) |-| `height` | No | `'dynamic'` for two-pass auto-sizing, or a fixed pixel number. Omit for default (750px) |+New commands should ship with VHS recordings (SVG + asciicast). Workflow:-Use `height: dynamic` for commands with long output (help text, full listings). The recorder probes with 2x height, parses the SVG to measure content, then re-records at the computed height (capped at `vhs.height * 2`).+1. Add entry to `recordings/recordings.yaml` (fields: `name`, `command`, `description`, `sleepAfterEnter`, `height: dynamic` for long output).+2. Run `bun scripts/record.ts` — requires `COMPOSIO_API_KEY` and `vhs` on `PATH`.-### Output Structure--```-recordings/-├── recordings.yaml # Config-├── tapes/<group>/<name>.tape # Generated VHS tape files-├── svgs/<group>/<name>.svg # SVG recordings-└── ascii/<group>/<name>.ascii # Asciicast recordings-```--### Key Files--- **Config**: `recordings/recordings.yaml`-- **Script**: `scripts/record.ts` — Bun + Effect.ts, parallel VHS execution-- **Shared tape**: `recordings/tapes/shared-config.tape` — common VHS settings (auto-generated)-----+Outputs land in `recordings/{tapes,svgs,ascii}/<group>/<name>.{tape,svg,ascii}`.## Release Workflow-CLI releases use a two-channel system: **beta** (automatic) and **stable** (manual promotion).--### Beta Releases (automatic)+Two channels: **beta** (automatic) and **stable** (manual promotion via changeset).-Every push to `next` that touches `ts/packages/cli/**` automatically triggers `.github/workflows/build-cli-binaries.yml`, which:+### Beta (automatic)-1. Finds the latest stable `@composio/[email protected]` release-2. Computes the next patch version (`X.Y.Z+1`)-3. Builds cross-platform binaries (linux-x64, linux-aarch64, darwin-x64, darwin-aarch64)-4. Creates a GitHub prerelease tagged `@composio/[email protected].(Z+1)-beta.<run_number>`+Every push to `next` touching `ts/packages/cli/**` triggers `.github/workflows/build-cli-binaries.yml`:-You can also trigger a beta build from **any branch** via `workflow_dispatch` → `build-beta`.+1. Find latest stable `@composio/[email protected]`+2. Compute next patch `X.Y.Z+1`+3. Build cross-platform binaries (linux-x64, linux-aarch64, darwin-x64, darwin-aarch64)+4. Publish GitHub prerelease `@composio/[email protected].(Z+1)-beta.<run_number>`-Users install beta releases with `composio upgrade --beta`.+Also triggerable from any branch via `workflow_dispatch` → `build-beta`. Users install with `composio upgrade --beta`.-### Stable Releases (via changeset)+### Stable (via changeset)-To promote to a stable release:--1. Create a changeset PR (`.changeset/<name>.md` with `"@composio/cli": patch`)-2. Merge it into `next`-3. The changeset bot creates a "Release: update version" PR that bumps `package.json`-4. Merge that PR → the push to `next` detects the `package.json` version changed → builds a **stable** release (`@composio/[email protected]`, marked as `latest`)+1. Create changeset PR (`.changeset/<name>.md` with `"@composio/cli": patch`)+2. Merge into `next`+3. Changeset bot opens "Release: update version" PR bumping `package.json`+4. Merge that PR → push to `next` detects version change → builds **stable** release (`@composio/[email protected]`, marked `latest`)5. `ts.release.yml` also publishes to npm-### Manual Promotion--You can also promote an existing beta to stable via `workflow_dispatch` → `promote-stable` with the beta tag (e.g. `@composio/[email protected]`).+Promote an existing beta to stable via `workflow_dispatch` → `promote-stable` with the beta tag (e.g. `@composio/[email protected]`).-### Key Files+### Key Workflow Files-| File | Purpose |-| --------------------------------------------- | -------------------------------- |-| `.github/workflows/build-cli-binaries.yml` | Binary build + release workflow |-| `.github/workflows/ts.release.yml` | Changeset bot + npm publish |-| `.github/workflows/cli.test-installation.yml` | Post-release install smoke tests |-| `.changeset/config.json` | Changeset configuration |+- `.github/workflows/build-cli-binaries.yml` — binary build + release+- `.github/workflows/ts.release.yml` — changeset bot + npm publish+- `.github/workflows/cli.test-installation.yml` — post-release install smoke tests+- `.changeset/config.json`