@devries-cameron20 / composio-1 / commits / 4a7625978
Fork 0

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

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

jkomyno committed Feb 18, 2026 at 11:43 UTC 4a762597898ec528aaeb092ff44a033d746155bd
5 files changed +245 -58
pnpm-lock.yaml
+22 -57
@@ -12,6 +12,12 @@ catalogs:
12 '@arethetypeswrong/cli':
13 specifier: ^0.18.2
14 version: 0.18.2
15 + '@clack/core':
16 + specifier: ^1.0.1
17 + version: 1.0.1
18 + '@clack/prompts':
19 + specifier: ^1.0.1
20 + version: 1.0.1
21 '@cloudflare/vitest-pool-workers':
22 specifier: ^0.9.2
23 version: 0.9.14
@@ -644,16 +650,16 @@ importers:
650 version: link:../../packages/providers/llamaindex
651 '@llamaindex/openai':
652 specifier: ^0.4.20
647 - version: 0.4.22(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(ws@8.19.0)(zod@3.25.76)
653 + version: 0.4.22(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(ws@8.19.0)(zod@4.3.6)
654 '@llamaindex/workflow':
655 specifier: ^1.1.24
650 - version: 1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76))(hono@4.11.9)(zod@3.25.76)
656 + version: 1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(zod@4.3.6)
657 dotenv:
658 specifier: ^16.4.1
659 version: 16.6.1
660 llamaindex:
661 specifier: ^0.12.0
656 - version: 0.12.1(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76))(hono@4.11.9)(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)(zod@3.25.76)
662 + version: 0.12.1(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)(zod@4.3.6)
663 devDependencies:
664 '@types/bun':
665 specifier: ^1.2.9
@@ -975,8 +981,11 @@ importers:
981
982 ts/packages/cli:
983 dependencies:
984 + '@clack/core':
985 + specifier: 'catalog:'
986 + version: 1.0.1
987 '@clack/prompts':
979 - specifier: 1.0.1
988 + specifier: 'catalog:'
989 version: 1.0.1
990 '@composio/client':
991 specifier: 'catalog:'
@@ -1247,7 +1256,7 @@ importers:
1256 dependencies:
1257 llamaindex:
1258 specifier: ^0.12.0
1250 - version: 0.12.1(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)(zod@4.3.6)
1259 + version: 0.12.1(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)(zod@4.3.6)
1260 devDependencies:
1261 '@composio/core':
1262 specifier: workspace:*
@@ -7509,43 +7518,26 @@ snapshots:
7518 tree-sitter: 0.22.4
7519 web-tree-sitter: 0.24.7
7520
7512 - '@llamaindex/openai@0.4.22(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(ws@8.19.0)(zod@3.25.76)':
7521 + '@llamaindex/openai@0.4.22(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(ws@8.19.0)(zod@4.3.6)':
7522 dependencies:
7523 '@llamaindex/core': 0.6.22
7524 '@llamaindex/env': 0.1.30
7516 - openai: 5.23.2(ws@8.19.0)(zod@3.25.76)
7525 + openai: 5.23.2(ws@8.19.0)(zod@4.3.6)
7526 transitivePeerDependencies:
7527 - ws
7528 - zod
7529
7521 - '@llamaindex/workflow-core@1.3.3(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76))(hono@4.11.9)(zod@3.25.76)':
7530 + '@llamaindex/workflow-core@1.3.3(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(zod@4.3.6)':
7531 optionalDependencies:
7523 - '@modelcontextprotocol/sdk': 1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76)
7532 + '@modelcontextprotocol/sdk': 1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6)
7533 hono: 4.11.9
7525 - zod: 3.25.76
7526 -
7527 - '@llamaindex/workflow-core@1.3.3(zod@4.3.6)':
7528 - optionalDependencies:
7534 zod: 4.3.6
7535
7531 - '@llamaindex/workflow@1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76))(hono@4.11.9)(zod@3.25.76)':
7532 - dependencies:
7533 - '@llamaindex/core': 0.6.22
7534 - '@llamaindex/env': 0.1.30
7535 - '@llamaindex/workflow-core': 1.3.3(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76))(hono@4.11.9)(zod@3.25.76)
7536 - transitivePeerDependencies:
7537 - - '@modelcontextprotocol/sdk'
7538 - - hono
7539 - - next
7540 - - p-retry
7541 - - rxjs
7542 - - zod
7543 -
7544 - '@llamaindex/workflow@1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(zod@4.3.6)':
7536 + '@llamaindex/workflow@1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(zod@4.3.6)':
7537 dependencies:
7538 '@llamaindex/core': 0.6.22
7539 '@llamaindex/env': 0.1.30
7548 - '@llamaindex/workflow-core': 1.3.3(zod@4.3.6)
7540 + '@llamaindex/workflow-core': 1.3.3(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(zod@4.3.6)
7541 transitivePeerDependencies:
7542 - '@modelcontextprotocol/sdk'
7543 - hono
@@ -9926,34 +9918,12 @@ snapshots:
9918 rfdc: 1.4.1
9919 wrap-ansi: 9.0.2
9920
9929 - llamaindex@0.12.1(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76))(hono@4.11.9)(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)(zod@3.25.76):
9930 - dependencies:
9931 - '@llamaindex/core': 0.6.22
9932 - '@llamaindex/env': 0.1.30
9933 - '@llamaindex/node-parser': 2.0.22(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)
9934 - '@llamaindex/workflow': 1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@3.25.76))(hono@4.11.9)(zod@3.25.76)
9935 - '@types/lodash': 4.17.23
9936 - '@types/node': 24.10.13
9937 - lodash: 4.17.23
9938 - magic-bytes.js: 1.13.0
9939 - transitivePeerDependencies:
9940 - - '@huggingface/transformers'
9941 - - '@modelcontextprotocol/sdk'
9942 - - gpt-tokenizer
9943 - - hono
9944 - - next
9945 - - p-retry
9946 - - rxjs
9947 - - tree-sitter
9948 - - web-tree-sitter
9949 - - zod
9950 -
9951 - llamaindex@0.12.1(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)(zod@4.3.6):
9921 + llamaindex@0.12.1(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)(zod@4.3.6):
9922 dependencies:
9923 '@llamaindex/core': 0.6.22
9924 '@llamaindex/env': 0.1.30
9925 '@llamaindex/node-parser': 2.0.22(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(tree-sitter@0.22.4)(web-tree-sitter@0.24.7)
9956 - '@llamaindex/workflow': 1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(zod@4.3.6)
9926 + '@llamaindex/workflow': 1.1.24(@llamaindex/core@0.6.22)(@llamaindex/env@0.1.30)(@modelcontextprotocol/sdk@1.26.0(@cfworker/json-schema@4.1.1)(zod@4.3.6))(hono@4.11.9)(zod@4.3.6)
9927 '@types/lodash': 4.17.23
9928 '@types/node': 24.10.13
9929 lodash: 4.17.23
@@ -10233,11 +10203,6 @@ snapshots:
10203 is-inside-container: 1.0.0
10204 wsl-utils: 0.1.0
10205
10236 - openai@5.23.2(ws@8.19.0)(zod@3.25.76):
10237 - optionalDependencies:
10238 - ws: 8.19.0
10239 - zod: 3.25.76
10240 -
10206 openai@5.23.2(ws@8.19.0)(zod@4.3.6):
10207 optionalDependencies:
10208 ws: 8.19.0
pnpm-workspace.yaml
+2
@@ -14,6 +14,8 @@ packages:
14 catalog:
15 '@ai-sdk/openai': ^3.0.19
16 '@arethetypeswrong/cli': ^0.18.2
17 + '@clack/core': '^1.0.1'
18 + '@clack/prompts': '^1.0.1'
19 '@cloudflare/vitest-pool-workers': ^0.9.2
20 '@cloudflare/workers-types': ^4.20250917.0
21 '@composio/client': 0.1.0-alpha.56
ts/packages/cli/AGENTS.md new
+218
@@ -0,0 +1,218 @@
1 +# AGENTS.md
2 +
3 +Instructions for AI agents working on `@composio/cli`.
4 +
5 +## Architecture Overview
6 +
7 +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.
8 +
9 +### Entry Point
10 +
11 +`src/bin.ts` bootstraps the CLI by composing Effect layers and running the root command via `BunRuntime.runMain()`:
12 +
13 +- `CliConfigLive` — @effect/cli behavior (case-sensitive, no auto-correct, no built-ins)
14 +- `ComposioUserContextLive` — User authentication state from `~/.composio/`
15 +- `ComposioSessionRepositoryLive` — OAuth2 session management
16 +- `ComposioToolkitsRepositoryCachedLive` — Cached API client for toolkits/tools
17 +- `UpgradeBinaryLive` — Self-update from GitHub releases
18 +- `BunFileSystem.layer`, `BunContext.layer` — Bun runtime integration
19 +
20 +Errors are captured via the custom `effect-errors/` module, which provides source-mapped stack traces, Effect span timelines, and formatted output.
21 +
22 +### Commands (`src/commands/`)
23 +
24 +Each command is declared with `@effect/cli`'s `Command.make()` pattern:
25 +
26 +| Command | Description |
27 +|---|---|
28 +| `composio version` | Display CLI version |
29 +| `composio whoami` | Show logged-in user's API key |
30 +| `composio login [--no-browser]` | OAuth2 login with browser redirect |
31 +| `composio logout` | Clear stored API key |
32 +| `composio upgrade` | Self-update binary from GitHub releases |
33 +| `composio generate` | Auto-detect project language, delegate to `ts` or `py` |
34 +| `composio ts generate` | Generate TypeScript type stubs for toolkits/tools/triggers |
35 +| `composio py generate` | Generate Python type stubs |
36 +
37 +Options use `Options.text()`, `Options.boolean()`, `Options.choice()`, `Options.directory()` with Effect Schema validation.
38 +
39 +### Services (`src/services/`)
40 +
41 +| Service | Purpose |
42 +|---|---|
43 +| `ComposioUserContext` | Auth state — reads/writes `~/.composio/user-config.json`, merges env vars |
44 +| `ComposioSessionRepository` | Creates OAuth2 sessions, polls until `linked` state |
45 +| `ComposioToolkitsRepository` | API client — fetches toolkits, tools, trigger types; validates versions |
46 +| `ComposioToolkitsRepositoryCached` | Decorator over base repository with file-based caching and graceful fallback |
47 +| `NodeOs` | OS abstraction (`homedir`, `platform`, `arch`) |
48 +| `EnvLangDetector` | Detects project language (TS/Python) from config files and lock files |
49 +| `JsPackageManagerDetector` | Detects npm/pnpm/yarn/bun for helpful install instructions |
50 +| `UpgradeBinary` | Fetches latest release from GitHub, downloads and replaces binary |
51 +
52 +### Effects (`src/effects/`)
53 +
54 +Reusable Effect computations for cross-cutting concerns:
55 +
56 +| Effect | Purpose |
57 +|---|---|
58 +| `app-config` | Reads `COMPOSIO_*` env vars (API_KEY, BASE_URL, CACHE_DIR, etc.) |
59 +| `debug-config` | Debug overrides (DEBUG_OVERRIDE_VERSION, etc.) |
60 +| `force-config` | Force flags (FORCE_USE_CACHE) |
61 +| `setup-cache-dir` | Ensures `~/.composio/` directory exists |
62 +| `toolkit-version-overrides` | Parses `COMPOSIO_TOOLKIT_VERSION_<NAME>=<ver>` env vars |
63 +| `validate-toolkit-versions` | Validates overrides against available API versions |
64 +| `with-log-level` | Configures logger from CLI flag or env var |
65 +| `find-composio-core-generated` | Locates `@composio/core` in node_modules (handles pnpm virtual store) |
66 +| `version` | Resolves CLI version from package.json |
67 +| `compare-semver` | Semantic version comparison for upgrade checks |
68 +| `log-metrics` | Formats and logs API request count and bytes transferred |
69 +
70 +### Models (`src/models/`)
71 +
72 +Effect Schema definitions for type-safe serialization:
73 +
74 +- `Toolkit` — name, slug, auth_schemes, is_local_toolkit, meta
75 +- `Tool` — name, slug, available_versions, input/output_parameters, description, tags
76 +- `TriggerType` — slug, name, description, input/output parameters
77 +- `UserData` — apiKey, baseURL, webURL (with defaults)
78 +- `Session` — id, status (pending|linked), retrieved session with api_key
79 +
80 +Each model has `fromJSON`/`toJSON` helpers using `JSONTransformSchema()`.
81 +
82 +### Code Generation (`src/generation/`)
83 +
84 +Multi-stage pipeline for `composio ts generate` and `composio py generate`:
85 +
86 +1. **Fetch** — Toolkits, tools, trigger types from API (optionally filtered by `--toolkits`)
87 +2. **Index** — Groups tools/triggers by toolkit prefix into a `ToolkitIndex` map
88 +3. **Generate** — Builds TypeScript/Python source using `@composio/ts-builders` AST builders
89 +4. **Transpile** — Optionally converts TS → ESM JS (when writing to @composio/core/generated)
90 +
91 +Generated output includes toolkit objects, tool/trigger enums, and optionally full type definitions (with `--type-tools`).
92 +
93 +### Error Handling (`src/effect-errors/`)
94 +
95 +Custom error capture and formatting system:
96 +
97 +- **Capture** — Extracts error chain from Effect's `Cause`, handles interrupts separately
98 +- **Source maps** — Maps compiled `.mjs` stack traces back to TypeScript source
99 +- **Spans** — Extracts timing from Effect spans for execution timeline display
100 +- **Pretty print** — Colored, boxed error output with source context and suggestions
101 +
102 +### UI & Output (`src/ui/`)
103 +
104 +- `picocolors` and `ansis` for colored terminal output
105 +- Respects `NO_COLOR` env var
106 +- `@clack/prompts` symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`) for box-drawing in formatted output
107 +- Effect's `Console.log()` / `Console.error()` for output
108 +
109 +### Configuration (`src/cli-config.ts`, `src/constants.ts`)
110 +
111 +- CLI behavior: `showBuiltIns: false`, `autoCorrectLimit: 0`, `isCaseSensitive: true`
112 +- Prefixes: `COMPOSIO_` for app config, `DEBUG_OVERRIDE_` for debug
113 +- User config stored in `~/.composio/`
114 +- Cache files: `toolkits.json`, `tools.json`, `tools-as-enums.json`, `trigger-types.json`
115 +
116 +### Effect.ts Patterns
117 +
118 +The CLI uses the generator-based syntax throughout:
119 +
120 +```typescript
121 +Effect.gen(function* () {
122 + const service = yield* ServiceName; // resolve dependency
123 + const result = yield* someEffect; // await computation
124 + yield* Effect.log('message'); // side effect
125 + return result;
126 +})
127 +```
128 +
129 +Key patterns:
130 +- `Effect.all([...], { concurrency: 'unbounded' })` for parallel fetches
131 +- `Layer.provide()` for dependency composition
132 +- `Effect.mapError()` / `Effect.catchTag()` for typed error handling
133 +- `Effect.scoped` for resource cleanup
134 +
135 +### Key Dependencies
136 +
137 +| Package | Role |
138 +|---|---|
139 +| `effect` | Core runtime, data types, concurrency |
140 +| `@effect/cli` | Command, Options, Args declaration and parsing |
141 +| `@effect/platform` | FileSystem, Terminal abstraction |
142 +| `@effect/platform-bun` | Bun runtime layer |
143 +| `@clack/prompts` | Terminal UI symbols (expanding to full interactive prompts) |
144 +| `ansis`, `picocolors` | Colored output |
145 +| `@composio/client` | Raw Composio API client |
146 +| `@composio/core` | Core SDK types and constants |
147 +| `@composio/ts-builders` | TypeScript AST code generation |
148 +| `semver` | Version comparison for upgrades |
149 +| `open` | Opens URLs in browser (login flow) |
150 +| `decompress` | Extracts downloaded binaries |
151 +
152 +---
153 +
154 +## Clack Reference Source
155 +
156 +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:
157 +
158 +- **Location:** `ts/vendor/clack/`
159 +- **Repo:** [bombshell-dev/clack](https://github.com/bombshell-dev/clack)
160 +
161 +When working on CLI code that involves terminal UI, reference the Clack source for accurate APIs and patterns:
162 +
163 +- `ts/vendor/clack/packages/prompts/src/` — `@clack/prompts` (the high-level API used by this CLI)
164 +- `ts/vendor/clack/packages/core/src/` — `@clack/core` (low-level primitives underlying prompts)
165 +
166 +### Key modules in `@clack/prompts`
167 +
168 +| Module | Purpose |
169 +|---|---|
170 +| `text.ts` | Text input prompt |
171 +| `password.ts` | Password input prompt |
172 +| `confirm.ts` | Yes/no confirmation prompt |
173 +| `select.ts` | Single-select list prompt |
174 +| `multi-select.ts` | Multi-select list prompt |
175 +| `group-multi-select.ts` | Grouped multi-select prompt |
176 +| `autocomplete.ts` | Autocomplete/search prompt |
177 +| `spinner.ts` | Loading spinner |
178 +| `progress-bar.ts` | Progress bar |
179 +| `log.ts` | Styled log messages |
180 +| `note.ts` | Boxed note output |
181 +| `task.ts` | Task runner with status |
182 +| `task-log.ts` | Task with streaming log output |
183 +| `stream.ts` | Streaming text output |
184 +| `box.ts` | Box drawing utility |
185 +| `messages.ts` | Intro/outro messages |
186 +| `common.ts` | Shared symbols (`S_BAR`, `S_BAR_H`, `unicodeOr`, etc.) |
187 +
188 +### Current clack usage in the CLI
189 +
190 +The CLI currently imports from `@clack/prompts`:
191 +- `S_BAR`, `S_BAR_H`, `unicodeOr` — Unicode box-drawing symbols for custom formatted output
192 +
193 +### Guidelines
194 +
195 +- The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/clack/`.
196 +- The CLI's actual dependency comes from npm (`@clack/prompts` v1.0.1) via `pnpm install`.
197 +- 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.
198 +- Prefer `@clack/prompts` (high-level) over `@clack/core` (low-level) unless you need custom prompt behavior.
199 +
200 +---
201 +
202 +## Effect.ts Reference Source
203 +
204 +The CLI is built on the Effect.ts ecosystem. A local copy of the Effect source code is available as a git submodule:
205 +
206 +- **Location:** `ts/vendor/effect/`
207 +- **Repo:** [Effect-TS/effect](https://github.com/Effect-TS/effect)
208 +- **Branch:** `main`
209 +
210 +When working on CLI code, reference the Effect source for accurate patterns:
211 +- `ts/vendor/effect/packages/effect/src/` — core Effect runtime
212 +- `ts/vendor/effect/packages/cli/src/` — @effect/cli (Command, Options, Args)
213 +- `ts/vendor/effect/packages/platform/src/` — @effect/platform (FileSystem, Terminal)
214 +
215 +### Guidelines
216 +
217 +- The submodule is for **read-only reference only**. Do not modify files in `ts/vendor/effect/`.
218 +- The CLI's actual dependencies come from npm via `pnpm install`.
ts/packages/cli/CLAUDE.md new
+1
@@ -0,0 +1 @@
1 +AGENTS.md
\ No newline at end of file
ts/packages/cli/package.json
+2 -1
@@ -61,7 +61,8 @@
61 "vitest": "catalog:"
62 },
63 "dependencies": {
64 - "@clack/prompts": "1.0.1",
64 + "@clack/core": "catalog:",
65 + "@clack/prompts": "catalog:",
66 "@composio/client": "catalog:",
67 "@composio/core": "workspace:*",
68 "@composio/ts-builders": "workspace:*",