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
chore(ts/ai): add references to clack in AGENTS.md
jkomyno4a762597898e
diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex dfd234a4e..3393c2c91 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -12,6 +12,12 @@ catalogs:'@arethetypeswrong/cli':specifier: ^0.18.2version: 0.18.2+ '@clack/core':+ specifier: ^1.0.1+ version: 1.0.1+ '@clack/prompts':+ specifier: ^1.0.1+ version: 1.0.1'@cloudflare/vitest-pool-workers':specifier: ^0.9.2version: 0.9.14@@ -644,16 +650,16 @@ importers:version: link:../../packages/providers/llamaindex'@llamaindex/openai':specifier: ^0.4.20- version: 0.4.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])+ version: 0.4.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])'@llamaindex/workflow':specifier: ^1.1.24- version: 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])+ version: 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])dotenv:specifier: ^16.4.1version: 16.6.1llamaindex:specifier: ^0.12.0- version: 0.12.1(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])([email protected])([email protected])+ version: 0.12.1(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])([email protected])([email protected])devDependencies:'@types/bun':specifier: ^1.2.9@@ -975,8 +981,11 @@ importers:ts/packages/cli:dependencies:+ '@clack/core':+ specifier: 'catalog:'+ version: 1.0.1'@clack/prompts':- specifier: 1.0.1+ specifier: 'catalog:'version: 1.0.1'@composio/client':specifier: 'catalog:'@@ -1247,7 +1256,7 @@ importers:dependencies:llamaindex:specifier: ^0.12.0+ version: 0.12.1(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])([email protected])([email protected])devDependencies:'@composio/core':specifier: workspace:*@@ -7509,43 +7518,26 @@ snapshots:tree-sitter: 0.22.4web-tree-sitter: 0.24.7- '@llamaindex/[email protected](@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])':+ '@llamaindex/[email protected](@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])':dependencies:'@llamaindex/core': 0.6.22'@llamaindex/env': 0.1.30- openai: 5.23.2([email protected])([email protected])+ openai: 5.23.2([email protected])([email protected])transitivePeerDependencies:- ws- zod- '@llamaindex/[email protected](@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])':+ '@llamaindex/[email protected](@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])':optionalDependencies:- '@modelcontextprotocol/sdk': 1.26.0(@cfworker/[email protected])([email protected])+ '@modelcontextprotocol/sdk': 1.26.0(@cfworker/[email protected])([email protected])hono: 4.11.9- zod: 3.25.76-- '@llamaindex/[email protected]([email protected])':- optionalDependencies:zod: 4.3.6- '@llamaindex/[email protected](@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])':- dependencies:- '@llamaindex/core': 0.6.22- '@llamaindex/env': 0.1.30- '@llamaindex/workflow-core': 1.3.3(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])- transitivePeerDependencies:- - '@modelcontextprotocol/sdk'- - hono- - next- - p-retry- - rxjs- - zod-- '@llamaindex/[email protected](@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])':+ '@llamaindex/[email protected](@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])':dependencies:'@llamaindex/core': 0.6.22'@llamaindex/env': 0.1.30- '@llamaindex/workflow-core': 1.3.3([email protected])+ '@llamaindex/workflow-core': 1.3.3(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])transitivePeerDependencies:- '@modelcontextprotocol/sdk'- hono@@ -9926,34 +9918,12 @@ snapshots:rfdc: 1.4.1wrap-ansi: 9.0.2- [email protected](@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])([email protected])([email protected]):- dependencies:- '@llamaindex/core': 0.6.22- '@llamaindex/env': 0.1.30- '@llamaindex/node-parser': 2.0.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])- '@llamaindex/workflow': 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])- '@types/lodash': 4.17.23- '@types/node': 24.10.13- lodash: 4.17.23- magic-bytes.js: 1.13.0- transitivePeerDependencies:- - '@huggingface/transformers'- - '@modelcontextprotocol/sdk'- - gpt-tokenizer- - hono- - next- - p-retry- - rxjs- - tree-sitter- - web-tree-sitter- - zod-+ [email protected](@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])([email protected])([email protected]):dependencies:'@llamaindex/core': 0.6.22'@llamaindex/env': 0.1.30'@llamaindex/node-parser': 2.0.22(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])([email protected])- '@llamaindex/workflow': 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])([email protected])+ '@llamaindex/workflow': 1.1.24(@llamaindex/[email protected])(@llamaindex/[email protected])(@modelcontextprotocol/[email protected](@cfworker/[email protected])([email protected]))([email protected])([email protected])'@types/lodash': 4.17.23'@types/node': 24.10.13lodash: 4.17.23@@ -10233,11 +10203,6 @@ snapshots:is-inside-container: 1.0.0wsl-utils: 0.1.0- optionalDependencies:- ws: 8.19.0- zod: 3.25.76-optionalDependencies:ws: 8.19.0diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yamlindex 2f00f40a0..3b4748938 100644--- a/pnpm-workspace.yaml+++ b/pnpm-workspace.yaml@@ -14,6 +14,8 @@ packages:catalog:'@ai-sdk/openai': ^3.0.19'@arethetypeswrong/cli': ^0.18.2+ '@clack/core': '^1.0.1'+ '@clack/prompts': '^1.0.1''@cloudflare/vitest-pool-workers': ^0.9.2'@cloudflare/workers-types': ^4.20250917.0'@composio/client': 0.1.0-alpha.56diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.mdnew file mode 100644index 000000000..f05ccf216--- /dev/null+++ b/ts/packages/cli/AGENTS.md@@ -0,0 +1,218 @@+# AGENTS.md++Instructions for AI agents working on `@composio/cli`.++## Architecture Overview++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.++### Entry Point++`src/bin.ts` 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/`+- `ComposioSessionRepositoryLive` — OAuth2 session management+- `ComposioToolkitsRepositoryCachedLive` — Cached API client for toolkits/tools+- `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]` | OAuth2 login with browser redirect |+| `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 ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |+| `composio py generate` | Generate Python type stubs |++Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.++### Services (`src/services/`)++| Service | Purpose |+|---|---|+| `ComposioUserContext` | Auth state — reads/writes `~/.composio/user-config.json`, merges env vars |+| `ComposioSessionRepository` | Creates OAuth2 sessions, polls until `linked` state |+| `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 |+| `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 |++### Models (`src/models/`)++Effect Schema definitions for type-safe serialization:++- `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++Each model has `fromJSON`/`toJSON` helpers using `JSONTransformSchema()`.++### Code Generation (`src/generation/`)++Multi-stage pipeline for `composio ts generate` and `composio py generate`:++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)++Generated output includes toolkit objects, tool/trigger enums, and optionally full type definitions (with `--type-tools`).++### Error Handling (`src/effect-errors/`)++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/`+- 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 symbols (expanding to full interactive prompts) |+| `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 |++---++## 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:+- `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`.diff --git a/ts/packages/cli/CLAUDE.md b/ts/packages/cli/CLAUDE.mdnew file mode 120000index 000000000..47dc3e3d8--- /dev/null+++ b/ts/packages/cli/CLAUDE.md@@ -0,0 +1 @@+AGENTS.md\ No newline at end of filediff --git a/ts/packages/cli/package.json b/ts/packages/cli/package.jsonindex 1c19701ad..68ce8b09a 100644--- a/ts/packages/cli/package.json+++ b/ts/packages/cli/package.json@@ -61,7 +61,8 @@"vitest": "catalog:"},"dependencies": {- "@clack/prompts": "1.0.1",+ "@clack/core": "catalog:",+ "@clack/prompts": "catalog:","@composio/client": "catalog:","@composio/core": "workspace:*","@composio/ts-builders": "workspace:*",