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.

chore(ts/ai): add references to clack in AGENTS.md

jkomyno4a762597898e
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index dfd234a4e..3393c2c91 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -12,6 +12,12 @@ catalogs:
'@arethetypeswrong/cli':
specifier: ^0.18.2
version: 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.2
version: 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.1
version: 16.6.1
llamaindex:
specifier: ^0.12.0
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
devDependencies:
'@composio/core':
specifier: workspace:*
@@ -7509,43 +7518,26 @@ snapshots:
tree-sitter: 0.22.4
web-tree-sitter: 0.24.7
dependencies:
'@llamaindex/core': 0.6.22
'@llamaindex/env': 0.1.30
transitivePeerDependencies:
- ws
- zod
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
-
- optionalDependencies:
zod: 4.3.6
- 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
-
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.1
wrap-ansi: 9.0.2
- 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
-
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.13
lodash: 4.17.23
@@ -10233,11 +10203,6 @@ snapshots:
is-inside-container: 1.0.0
wsl-utils: 0.1.0
- optionalDependencies:
- ws: 8.19.0
- zod: 3.25.76
-
optionalDependencies:
ws: 8.19.0
diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml
index 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.56
diff --git a/ts/packages/cli/AGENTS.md b/ts/packages/cli/AGENTS.md
new file mode 100644
index 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.md
new file mode 120000
index 000000000..47dc3e3d8
--- /dev/null
+++ b/ts/packages/cli/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file
diff --git a/ts/packages/cli/package.json b/ts/packages/cli/package.json
index 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:*",