Skip to content

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

docs: update CLAUDE.md for composio SDK

Zen Agentf273e95f922b
diff --git a/CLAUDE.md b/CLAUDE.md
index 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.7
pnpm 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 environment
cd 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 flow
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
index 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`