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:*",