@devries-cameron20 / composio-1 / commits / f2beb2f25
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.

feat(cli): install agent plugins with composio setup

Kshitij Jhunjhunwala committed Jul 13, 2026 at 14:14 UTC f2beb2f25972d1865899370e134277507a3c37cb
12 files changed +1052 -46
.changeset/cli-setup-agent-plugins.md new
+5
@@ -0,0 +1,5 @@
1 +---
2 +'@composio/cli': minor
3 +---
4 +
5 +Add `composio setup` to idempotently install and enable the Composio marketplace and plugin for Claude Code and Codex. Claude setup also installs the matching standalone CLI skill; the Codex plugin bundles it.
docs/content/docs/claude-code-plugin.mdx
+103 -45
@@ -1,62 +1,77 @@
1 ---
2 title: Claude Code Plugin
3 -description: Install Composio in Claude Code as a plugin — connect 1000+ apps with managed OAuth and ready-made skills.
4 -keywords: [claude code, plugin, marketplace, mcp, composio connect, skills]
3 +description: Install the Composio CLI plugin for Claude Code — connect and act across 1000+ apps with managed authentication.
4 +keywords: [claude code, plugin, marketplace, composio cli, composio connect, skills]
5 ---
6
7 -The **Composio plugin for Claude Code** bundles the Composio Connect MCP server with a set of opinionated skills, so Claude Code can search, connect, and act across 1000+ apps right after install. Authentication is fully managed — no API key handling, no manual MCP config.
7 +The **Composio plugin for Claude Code** helps Claude discover and run the right Composio CLI command when a task involves an external app. It is a thin, CLI-based plugin: the plugin adds Claude Code hooks and a connection command, while the `composio` CLI handles tool search, execution, and authentication.
8
9 -<Callout type="info">
10 -Looking for the API-key based MCP setup (or other clients like Cursor, Codex, Claude Desktop)? See [Composio Connect](/docs/composio-connect).
11 -</Callout>
9 +The plugin does **not** bundle an MCP server or a skill. If you want to add the remote Composio MCP server to Claude Code, see [Composio Connect](/docs/composio-connect).
10
11 ## What you get
12
15 -The plugin ships two things together:
13 +| Component | Purpose |
14 +| ------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
15 +| **SessionStart hook** | Tells Claude about Composio's `search` → `execute` workflow, reports CLI authentication status, and warms a local cache of popular toolkits. It runs when a session starts, resumes, clears, or compacts. |
16 +| **UserPromptSubmit hook** | Nudges Claude toward `composio search` when your prompt names an app in the local toolkit cache. It uses the cache and does not make a network request for each prompt. |
17 +| **`/composio-connect <app>` command** | Connects an app with `composio link` and managed OAuth, then verifies the connection. |
18
17 -- **Composio Connect MCP server** — the same gateway documented in [Composio Connect](/docs/composio-connect), pre-configured. Auth is handled via in-flow OAuth, so you don't paste API keys into your config.
18 -- **Bundled skills** — pre-written prompts that show Claude how to use the MCP server effectively:
19 - - **`composio-mcp`** — reference for the 7 meta-tools (`COMPOSIO_SEARCH_TOOLS`, `COMPOSIO_MANAGE_CONNECTIONS`, etc.) and the recommended search → connect → execute flow.
20 - - **`onboarding`** — interactive setup that asks what you want to automate, recommends 2–4 apps, and walks you through connecting them.
21 - - **`company-activity-summary`** — cross-app activity summary across Slack, GitHub, Notion, Linear, Gmail, and more.
22 - - **`prefer-composio`** — routing skill that tells Claude to reach for Composio first whenever you paste an app URL or mention an external service, so you don't end up using less reliable native connectors.
19 +The Composio CLI installs the full `composio-cli` skill separately when you sign in. That skill contains the detailed CLI reference; it is not packaged inside this plugin.
20
21 ## Install
22
23 <Steps>
24 <Step>
28 -<StepTitle>Add the Composio marketplace</StepTitle>
25 +<StepTitle>Install and set up Composio</StepTitle>
26
30 -In Claude Code, run:
27 +If the CLI is not already installed, run:
28
29 ```bash
33 -/plugin marketplace add ComposioHQ/composio-plugin-cc
30 +curl -fsSL https://composio.dev/install | bash
31 +composio login
32 +composio setup --target claude
33 ```
34
36 -This registers the catalog. No plugins are installed yet.
35 +Login authenticates the CLI. Setup then adds the GitHub-hosted marketplace, installs and enables `composio@composio`, and installs the matching `composio-cli` skill. Setup is safe to rerun.
36
37 </Step>
38 <Step>
40 -<StepTitle>Install the Composio plugin</StepTitle>
39 +<StepTitle>Try it</StepTitle>
40
42 -```bash
43 -/plugin install composio-mcp@composio
44 -```
41 +Ask Claude to act on an app, for example: _"List my open GitHub pull requests."_ Claude can search for the appropriate tool, ask you to connect GitHub if necessary, and execute it.
42
46 -Restart Claude Code (or run `/reload-plugins`) when prompted.
43 +You can also connect an app directly:
44
48 -</Step>
49 -<Step>
50 -<StepTitle>Connect your first app</StepTitle>
51 -
52 -Ask Claude something that needs an external service — for example: *"Star `composiohq/composio` on GitHub"* — and Claude will run the `onboarding` skill, walk you through connecting GitHub, and execute the action. Subsequent runs reuse the same connection.
45 +```text
46 +/composio-connect github
47 +```
48
49 </Step>
50 </Steps>
51
52 +### Manual plugin fallback
53 +
54 +If you need to register the plugin directly in Claude Code, add the marketplace:
55 +
56 +In Claude Code, run:
57 +
58 +```text
59 +/plugin marketplace add ComposioHQ/composio-plugin-cc
60 +```
61 +
62 +This adds Composio's GitHub-hosted marketplace. It does not install the plugin yet.
63 +
64 +Then install the plugin:
65 +
66 +```text
67 +/plugin install composio@composio
68 +```
69 +
70 +Finish the local prerequisites with `composio login` and `composio --install-skill claude` if they are not already ready. `composio setup --target claude` is preferred for plugin and skill installation because it verifies those pieces together.
71 +
72 ## Team setup
73
59 -To pre-install the plugin for everyone on your team, add this to your project's `.claude/settings.json`:
74 +To make the marketplace and plugin available to everyone working in a repository, add this to the project's `.claude/settings.json`:
75
76 ```json title=".claude/settings.json"
77 {
@@ -69,42 +84,85 @@ To pre-install the plugin for everyone on your team, add this to your project's
84 }
85 },
86 "enabledPlugins": {
72 - "composio-mcp@composio": true
87 + "composio@composio": true
88 }
89 }
90 ```
91
77 -Anyone who clones the repo and opens it in Claude Code will be prompted to enable the plugin. See the Claude Code [plugin scopes](https://docs.claude.com/en/docs/claude-code/plugins-reference#plugin-installation-scopes) reference for `user` vs `project` vs `local` scope behavior.
92 +Claude Code prompts teammates to trust and enable the plugin when they open the project. Each teammate still needs the `composio` CLI installed and must sign in on their machine.
93 +
94 +## How it works
95 +
96 +The plugin keeps the integration lightweight and lets the CLI own its capabilities:
97 +
98 +1. **Session context** — the SessionStart hook tells Claude to use Composio for external apps, surfaces CLI authentication status, and caches a small list of popular toolkits.
99 +2. **Prompt routing** — the UserPromptSubmit hook checks the prompt against that local cache. When it recognizes an app, it reminds Claude to use Composio's just-in-time tool search.
100 +3. **Tool discovery and execution** — Claude runs `composio search "<task>"`, then `composio execute` with the selected tool. If an app is not connected, it runs `composio link <app>` to start managed OAuth.
101 +4. **CLI-provided guidance** — the separately installed `composio-cli` skill gives Claude the full command and workflow reference.
102 +
103 +The hooks guide Claude; they do not expose tools or execute app actions themselves.
104
105 ## Updating
106
81 -The plugin is versioned via the `version` field in its `plugin.json`. To pull the latest release:
107 +Plugin updates and CLI updates are separate. Update the marketplace checkout and reload plugins in Claude Code:
108
83 -```bash
109 +```text
110 /plugin marketplace update composio
111 /reload-plugins
112 ```
113
88 -## How it differs from the API-key MCP setup
114 +Update the CLI to receive the latest Composio commands, tool-routing behavior, and generated skill:
115 +
116 +```bash
117 +composio upgrade
118 +```
119
90 -Both paths give Claude Code access to the same Composio Connect MCP server and the same 1000+ apps. The differences:
120 +## Plugin or MCP setup?
121
92 -| | Plugin install | `claude mcp add` |
93 -|---|---|---|
94 -| Setup steps | Two slash commands | One terminal command, requires copying an API key |
95 -| Auth | OAuth, no API key in your config | API key in `--header "x-consumer-api-key: ..."` |
96 -| Bundled skills | Yes (onboarding, routing, summaries) | No |
97 -| Discoverable in Claude Code marketplace | Yes | No |
98 -| Updates | `/plugin marketplace update composio` | Manual re-run of `claude mcp add` |
122 +The Claude Code plugin and the API-key MCP setup are two different ways to use Composio:
123
100 -Pick the plugin path if you want the fastest install and the bundled skills. Pick the `claude mcp add` path if you already have an API key and want a single-command setup script you can replicate across machines.
124 +| | Claude Code plugin | Composio Connect MCP |
125 +| ------------------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------- |
126 +| Runtime | Local `composio` CLI | Remote MCP server |
127 +| Tool access | Claude runs `composio search`, `composio execute`, and `composio link` | Claude calls Composio's MCP meta-tools |
128 +| Claude Code integration | Session and prompt hooks plus `/composio-connect` | MCP tools registered with `claude mcp add` |
129 +| Skill | Installed and updated separately by the CLI | No CLI skill required |
130 +| Initial Composio authentication | `composio login` | Consumer API key in the MCP configuration |
131 +| Updates | Update both the marketplace plugin and CLI | Server-side; the MCP configuration remains in Claude Code |
132 +
133 +Choose the plugin when you want Claude Code to use the local CLI and its scripting workflows. Choose [Composio Connect](/docs/composio-connect) when you want an MCP-native setup or the same remote MCP interface across multiple clients.
134
135 ## Source code
136
104 -The plugin is open source: [ComposioHQ/composio-plugin-cc](https://github.com/ComposioHQ/composio-plugin-cc). Issues and PRs welcome.
137 +The plugin is open source at [ComposioHQ/composio-plugin-cc](https://github.com/ComposioHQ/composio-plugin-cc).
138
139 ## Troubleshooting
140
108 -For tools-not-appearing, OAuth, and connection issues, see the [Composio Connect troubleshooting section](/docs/composio-connect#troubleshooting). The same checks apply to the plugin install (the underlying MCP server is identical).
141 +### The plugin installs, but Claude cannot run Composio
142 +
143 +Confirm the CLI is available and that you are signed in:
144 +
145 +```bash
146 +composio --version
147 +composio whoami
148 +```
149 +
150 +If the first command fails, [install the CLI](#install). If the second reports that you are signed out, run `composio login`.
151 +
152 +### The CLI skill is missing
153 +
154 +The plugin does not bundle the `composio-cli` skill. Rerun `composio setup --target claude`, or install the skill explicitly:
155 +
156 +```bash
157 +composio --install-skill claude
158 +```
159 +
160 +### Claude does not receive an app-specific nudge
161 +
162 +The UserPromptSubmit hook only matches apps in its cached popular-toolkit list. Claude can still use Composio for any supported app: ask it to run `composio search "<task>"`, or connect the app with `/composio-connect <app>`.
163 +
164 +### An app is not connected or a tool call fails
165 +
166 +Run `composio link <app>` to connect the app, then retry the action. For CLI-specific diagnostics, use the troubleshooting guidance in the installed `composio-cli` skill. For the separate MCP integration, see [Composio Connect troubleshooting](/docs/composio-connect#troubleshooting).
167
110 -For plugin-specific issues — install errors, marketplace not updating, skills not appearing — see the [Claude Code plugin troubleshooting docs](https://docs.claude.com/en/docs/claude-code/plugins-reference#common-issues).
168 +For marketplace registration, plugin loading, or hook errors, see the [Claude Code plugin troubleshooting documentation](https://code.claude.com/docs/en/plugins-reference#common-issues).
ts/packages/cli/README.md
+9
@@ -96,6 +96,15 @@ To pull from the beta channel instead of the stable channel:
96 composio upgrade --beta
97 ```
98
99 +### Plugin setup release dependency
100 +
101 +`composio setup` installs plugins from these public marketplace repositories:
102 +
103 +- Claude Code: `ComposioHQ/composio-plugin-cc`
104 +- Codex: `ComposioHQ/composio-plugin-openai`
105 +
106 +Both repositories must be publicly accessible with a `composio@composio` entry before releasing a CLI version that advertises automatic plugin setup. The CLI release must also contain `composio-skill.zip`; Claude setup installs that standalone skill, while the Codex plugin bundles its own copy.
107 +
108 ## Caching
109
110 The CLI implements a file-based caching system for improved performance and offline capabilities.
ts/packages/cli/src/cli-main.ts
+2
@@ -38,6 +38,7 @@ import {
38 } from 'src/analytics/events';
39 import { trackCliEvent, trackCliEventEffect } from 'src/analytics/dispatch';
40 import { mapOnlyComposioOverrideError } from 'src/services/composio-error-overrides';
41 +import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
42
43 // eslint-disable-next-line @typescript-eslint/no-explicit-any
44 type RequiredLayer = Layer.Layer<any, any, never>;
@@ -108,6 +109,7 @@ const layers = Layer.mergeAll(
109 JsPackageManagerDetector.Default,
110 ProjectEnvironmentDetector.Default,
111 CommandRunner.Default,
112 + SetupSkillInstaller.Default,
113 TriggersRealtimeLive,
114 ProjectContextLive,
115 BunContext.layer,
ts/packages/cli/src/commands/index.ts
+2
@@ -8,6 +8,7 @@ import { upgradeCmd } from './upgrade.cmd';
8 import { whoamiCmd } from './whoami.cmd';
9 import { loginCmd } from './login.cmd';
10 import { signupCmd } from './signup.cmd';
11 +import { setupCmd } from './setup.cmd';
12 import { listenCmd } from './listen.cmd';
13 import { logoutCmd } from './logout.cmd';
14 import { runCmd } from './run.cmd';
@@ -63,6 +64,7 @@ const ROOT_COMMANDS: ReadonlyArray<TaggedValue<Command.Command<any, any, any, an
64 tagged(whoamiCmd),
65 tagged(loginCmd),
66 tagged(signupCmd),
67 + tagged(setupCmd),
68 tagged(agentCmd),
69 experimental(CLI_EXPERIMENTAL_FEATURES.LISTEN, listenCmd),
70 tagged(logoutCmd),
ts/packages/cli/src/commands/root-help.ts
+20
@@ -162,6 +162,7 @@ const GENERATE_COMMAND: TaggedValue<CompactCommand> = tagged({
162 // ── Account commands ───────────────────────────────────────────────────
163
164 const ACCOUNT_COMMANDS: ReadonlyArray<TaggedValue<CompactCommand>> = [
165 + tagged({ name: 'setup', description: 'Install agent plugins' }),
166 tagged({ name: 'login', description: 'Log in to Composio' }),
167 tagged({ name: 'logout', description: 'Log out from Composio' }),
168 tagged({ name: 'whoami', description: 'Show current account info' }),
@@ -868,6 +869,25 @@ const SUBCOMMAND_HELP: Record<string, SubcommandHelp | TaggedValue<SubcommandHel
869 usage: 'composio whoami',
870 description: 'Display your account information.',
871 },
872 + setup: {
873 + usage: 'composio setup [--target auto|claude|codex|all] [--yes]',
874 + description: 'Install plugins for supported agent hosts.',
875 + examples: [
876 + 'composio setup',
877 + 'composio setup --target auto --yes',
878 + 'composio setup --target all',
879 + 'composio setup status --json',
880 + ],
881 + options: [
882 + { name: '--target <target>', description: 'auto, claude, codex, or all' },
883 + { name: '-y, --yes', description: 'Accept setup changes without prompting' },
884 + ],
885 + },
886 + 'setup status': {
887 + usage: 'composio setup status [--json]',
888 + description: 'Inspect agent plugin installation status.',
889 + flags: [{ name: '--json', description: 'Print machine-readable JSON' }],
890 + },
891 version: {
892 usage: 'composio version',
893 description: 'Display the current Composio CLI version.',
ts/packages/cli/src/commands/setup.cmd.ts new
+110
@@ -0,0 +1,110 @@
1 +import { Command, Options } from '@effect/cli';
2 +import { Effect } from 'effect';
3 +import {
4 + inspectSetupTargets,
5 + installSetupTargets,
6 + resolveSetupTargets,
7 + SETUP_TARGETS,
8 + type SetupTarget,
9 +} from 'src/services/setup';
10 +import { TerminalUI } from 'src/services/terminal-ui';
11 +
12 +const target = Options.choice('target', SETUP_TARGETS).pipe(
13 + Options.withDefault('auto' as SetupTarget),
14 + Options.withDescription('Agent host to configure: auto, claude, codex, or all')
15 +);
16 +
17 +const yes = Options.boolean('yes').pipe(
18 + Options.withAlias('y'),
19 + Options.withDefault(false),
20 + Options.withDescription('Accept setup changes without prompting')
21 +);
22 +
23 +const json = Options.boolean('json').pipe(
24 + Options.withDefault(false),
25 + Options.withDescription('Print machine-readable JSON')
26 +);
27 +
28 +const setupStatusCmd = Command.make('status', { json }).pipe(
29 + Command.withDescription('Inspect agent plugin installation status.'),
30 + Command.withHandler(({ json }) =>
31 + Effect.gen(function* () {
32 + const ui = yield* TerminalUI;
33 + const targets = yield* inspectSetupTargets;
34 + const result = { targets };
35 +
36 + if (!json) {
37 + yield* ui.note(
38 + [
39 + ...targets.map(item => {
40 + const state = !item.available
41 + ? 'not detected'
42 + : !item.plugin_installed
43 + ? 'not installed'
44 + : item.plugin_enabled
45 + ? 'installed and enabled'
46 + : 'installed but disabled';
47 + return `${item.target}: ${state}`;
48 + }),
49 + ...targets
50 + .filter(item => item.available)
51 + .map(
52 + item => `${item.target} CLI skill: ${item.cli_skill_ready ? 'ready' : 'not ready'}`
53 + ),
54 + ].join('\n'),
55 + 'Composio setup status'
56 + );
57 + }
58 + yield* ui.output(JSON.stringify(result), { force: json });
59 + })
60 + )
61 +);
62 +
63 +const setupBaseCmd = Command.make('setup', { target, yes }, ({ target, yes }) =>
64 + Effect.gen(function* () {
65 + const ui = yield* TerminalUI;
66 + yield* ui.intro('composio setup');
67 +
68 + const targets = yield* resolveSetupTargets(target);
69 + if (!yes) {
70 + const confirmed = yield* ui.confirm(`Install Composio for ${targets.join(' and ')}?`, {
71 + defaultValue: true,
72 + });
73 + if (!confirmed) {
74 + yield* ui.outro('Setup cancelled.');
75 + return;
76 + }
77 + }
78 +
79 + const results = yield* installSetupTargets(targets);
80 + for (const result of results) {
81 + yield* ui.log.success(
82 + result.plugin_changed
83 + ? `Configured and enabled the Composio plugin for ${result.target}.`
84 + : `The Composio plugin for ${result.target} is already installed and enabled.`
85 + );
86 + if (result.target === 'claude') {
87 + yield* ui.log.success(
88 + result.skill_changed
89 + ? 'Installed the composio-cli skill for Claude Code.'
90 + : 'The composio-cli skill for Claude Code is already installed.'
91 + );
92 + } else {
93 + yield* ui.log.success('The Codex plugin includes the composio-cli skill.');
94 + }
95 + }
96 +
97 + yield* ui.output(
98 + JSON.stringify({
99 + success: true,
100 + targets: results,
101 + })
102 + );
103 + yield* ui.outro('Composio setup complete.');
104 + })
105 +);
106 +
107 +export const setupCmd = setupBaseCmd.pipe(
108 + Command.withDescription('Install Composio plugins for supported agent hosts.'),
109 + Command.withSubcommands([setupStatusCmd])
110 +);
ts/packages/cli/src/services/command-runner.ts
+21 -1
@@ -1,9 +1,29 @@
1 import { Command } from '@effect/platform';
2 -import { Effect } from 'effect';
2 +import { Effect, Stream } from 'effect';
3 +
4 +export interface CommandResult {
5 + readonly exitCode: number;
6 + readonly stdout: string;
7 + readonly stderr: string;
8 +}
9 +
10 +const collectText = (stream: Stream.Stream<Uint8Array, unknown>) =>
11 + Stream.runFold(stream, '', (output, chunk) => output + new TextDecoder().decode(chunk));
12
13 export class CommandRunner extends Effect.Service<CommandRunner>()('services/CommandRunner', {
14 sync: () => ({
15 run: (command: Command.Command) => Command.exitCode(command),
16 + capture: (command: Command.Command) =>
17 + Effect.scoped(
18 + Effect.gen(function* () {
19 + const process = yield* Command.start(command);
20 + const [exitCode, stdout, stderr] = yield* Effect.all(
21 + [process.exitCode, collectText(process.stdout), collectText(process.stderr)],
22 + { concurrency: 'unbounded' }
23 + );
24 + return { exitCode: Number(exitCode), stdout, stderr } satisfies CommandResult;
25 + })
26 + ),
27 }),
28 dependencies: [],
29 }) {}
ts/packages/cli/src/services/setup-skill-installer.ts new
+32
@@ -0,0 +1,32 @@
1 +import { FileSystem } from '@effect/platform';
2 +import { Effect } from 'effect';
3 +import path from 'node:path';
4 +import { inferSkillReleaseChannel, installSkill } from 'src/effects/install-skill';
5 +import { APP_VERSION } from 'src/constants';
6 +import { NodeOs } from './node-os';
7 +
8 +export class SetupSkillInstaller extends Effect.Service<SetupSkillInstaller>()(
9 + 'services/SetupSkillInstaller',
10 + {
11 + sync: () => ({
12 + isClaudeSkillInstalled: Effect.gen(function* () {
13 + const fs = yield* FileSystem.FileSystem;
14 + const os = yield* NodeOs;
15 + return yield* fs.exists(path.join(os.homedir, '.claude', 'skills', 'composio-cli'));
16 + }),
17 + ensureClaudeSkill: Effect.gen(function* () {
18 + const fs = yield* FileSystem.FileSystem;
19 + const os = yield* NodeOs;
20 + const target = path.join(os.homedir, '.claude', 'skills', 'composio-cli');
21 + if (yield* fs.exists(target)) return false;
22 +
23 + yield* installSkill({
24 + target: 'claude',
25 + channel: inferSkillReleaseChannel(APP_VERSION),
26 + });
27 + return true;
28 + }),
29 + }),
30 + dependencies: [],
31 + }
32 +) {}
ts/packages/cli/src/services/setup.ts new
+304
@@ -0,0 +1,304 @@
1 +import { Command } from '@effect/platform';
2 +import { Effect } from 'effect';
3 +import { CommandRunner, type CommandResult } from './command-runner';
4 +import { SetupSkillInstaller } from './setup-skill-installer';
5 +
6 +export const SETUP_TARGETS = ['auto', 'claude', 'codex', 'all'] as const;
7 +export type SetupTarget = (typeof SETUP_TARGETS)[number];
8 +export type AgentHost = Exclude<SetupTarget, 'auto' | 'all'>;
9 +
10 +export const CLAUDE_PLUGIN_MARKETPLACE = {
11 + name: 'composio',
12 + source: 'ComposioHQ/composio-plugin-cc',
13 + plugin: 'composio@composio',
14 +} as const;
15 +
16 +export const CODEX_PLUGIN_MARKETPLACE = {
17 + name: 'composio',
18 + source: 'ComposioHQ/composio-plugin-openai',
19 + plugin: 'composio@composio',
20 +} as const;
21 +
22 +export interface SetupTargetStatus {
23 + readonly target: AgentHost;
24 + readonly available: boolean;
25 + readonly marketplace_configured: boolean;
26 + readonly plugin_installed: boolean;
27 + readonly plugin_enabled: boolean;
28 + /** Whether this host can load the authenticated composio-cli skill. */
29 + readonly cli_skill_ready: boolean;
30 +}
31 +
32 +export interface SetupTargetResult extends SetupTargetStatus {
33 + readonly changed: boolean;
34 + readonly plugin_changed: boolean;
35 + readonly skill_changed: boolean;
36 +}
37 +
38 +interface SetupTargetAdapter {
39 + readonly target: AgentHost;
40 + readonly executable: string;
41 + readonly marketplace: typeof CLAUDE_PLUGIN_MARKETPLACE | typeof CODEX_PLUGIN_MARKETPLACE;
42 + readonly marketplaceListArgs: ReadonlyArray<string>;
43 + readonly pluginListArgs: ReadonlyArray<string>;
44 + readonly marketplaceAddArgs: ReadonlyArray<string>;
45 + readonly pluginInstallArgs: ReadonlyArray<string>;
46 + readonly pluginEnableArgs: ReadonlyArray<string>;
47 +}
48 +
49 +const CLAUDE_ADAPTER: SetupTargetAdapter = {
50 + target: 'claude',
51 + executable: 'claude',
52 + marketplace: CLAUDE_PLUGIN_MARKETPLACE,
53 + marketplaceListArgs: ['plugin', 'marketplace', 'list', '--json'],
54 + pluginListArgs: ['plugin', 'list', '--json'],
55 + marketplaceAddArgs: [
56 + 'plugin',
57 + 'marketplace',
58 + 'add',
59 + CLAUDE_PLUGIN_MARKETPLACE.source,
60 + '--scope',
61 + 'user',
62 + ],
63 + pluginInstallArgs: ['plugin', 'install', CLAUDE_PLUGIN_MARKETPLACE.plugin, '--scope', 'user'],
64 + pluginEnableArgs: ['plugin', 'enable', CLAUDE_PLUGIN_MARKETPLACE.plugin],
65 +};
66 +
67 +const CODEX_ADAPTER: SetupTargetAdapter = {
68 + target: 'codex',
69 + executable: 'codex',
70 + marketplace: CODEX_PLUGIN_MARKETPLACE,
71 + marketplaceListArgs: ['plugin', 'marketplace', 'list', '--json'],
72 + pluginListArgs: ['plugin', 'list', '--json'],
73 + marketplaceAddArgs: ['plugin', 'marketplace', 'add', CODEX_PLUGIN_MARKETPLACE.source, '--json'],
74 + pluginInstallArgs: ['plugin', 'add', CODEX_PLUGIN_MARKETPLACE.plugin, '--json'],
75 + // Codex has no separate enable command. Re-adding is its native install/repair path.
76 + pluginEnableArgs: ['plugin', 'add', CODEX_PLUGIN_MARKETPLACE.plugin, '--json'],
77 +};
78 +
79 +const ADAPTERS: ReadonlyArray<SetupTargetAdapter> = [CLAUDE_ADAPTER, CODEX_ADAPTER];
80 +
81 +const asRecord = (value: unknown): Record<string, unknown> | undefined =>
82 + value !== null && typeof value === 'object' && !Array.isArray(value)
83 + ? (value as Record<string, unknown>)
84 + : undefined;
85 +
86 +const parseJson = (value: string): unknown => {
87 + try {
88 + return JSON.parse(value) as unknown;
89 + } catch {
90 + return undefined;
91 + }
92 +};
93 +
94 +const recordsFrom = (value: unknown, key?: string): ReadonlyArray<Record<string, unknown>> => {
95 + const selected = key ? asRecord(value)?.[key] : value;
96 + return Array.isArray(selected)
97 + ? selected.flatMap(item => {
98 + const record = asRecord(item);
99 + return record ? [record] : [];
100 + })
101 + : [];
102 +};
103 +
104 +const normalizeGitHubRepository = (value: string): string | undefined => {
105 + const trimmed = value.trim();
106 + if (!trimmed) return undefined;
107 +
108 + let repository = trimmed;
109 + const scpStyle = /^git@github\.com:(.+)$/i.exec(repository);
110 + if (scpStyle) {
111 + repository = scpStyle[1] ?? '';
112 + } else if (/^[a-z][a-z0-9+.-]*:\/\//i.test(repository)) {
113 + try {
114 + const url = new URL(repository);
115 + if (url.hostname.toLowerCase() !== 'github.com') return undefined;
116 + repository = url.pathname;
117 + } catch {
118 + return undefined;
119 + }
120 + }
121 +
122 + repository = repository.replace(/^\/+|\/+$/g, '').replace(/\.git$/i, '');
123 + const parts = repository.split('/');
124 + if (parts.length !== 2 || parts.some(part => !/^[a-z0-9._-]+$/i.test(part))) {
125 + return undefined;
126 + }
127 + return parts.join('/').toLowerCase();
128 +};
129 +
130 +const marketplaceIsConfigured = (adapter: SetupTargetAdapter, output: string): boolean => {
131 + const parsed = parseJson(output);
132 + const records = recordsFrom(parsed, adapter.target === 'codex' ? 'marketplaces' : undefined);
133 + return records.some(record => {
134 + const repo = typeof record.repo === 'string' ? record.repo : undefined;
135 + const nestedSource = asRecord(record.source);
136 + const marketplaceSource = asRecord(record.marketplaceSource);
137 + const source =
138 + (typeof record.source === 'string' ? record.source : undefined) ??
139 + (typeof nestedSource?.repo === 'string' ? nestedSource.repo : undefined) ??
140 + (typeof nestedSource?.source === 'string' ? nestedSource.source : undefined) ??
141 + (typeof marketplaceSource?.source === 'string' ? marketplaceSource.source : undefined);
142 + const expected = normalizeGitHubRepository(adapter.marketplace.source);
143 + return [repo, source].some(
144 + candidate =>
145 + typeof candidate === 'string' && normalizeGitHubRepository(candidate) === expected
146 + );
147 + });
148 +};
149 +
150 +const pluginState = (
151 + adapter: SetupTargetAdapter,
152 + output: string
153 +): { readonly installed: boolean; readonly enabled: boolean } => {
154 + const parsed = parseJson(output);
155 + const records = recordsFrom(parsed, adapter.target === 'codex' ? 'installed' : undefined);
156 + const plugin = records.find(record => {
157 + const id = record.id ?? record.pluginId;
158 + return id === adapter.marketplace.plugin;
159 + });
160 + if (!plugin || plugin.installed === false) return { installed: false, enabled: false };
161 + return { installed: true, enabled: plugin.enabled !== false };
162 +};
163 +
164 +const capture = (executable: string, args: ReadonlyArray<string>) =>
165 + Effect.gen(function* () {
166 + const runner = yield* CommandRunner;
167 + return yield* runner
168 + .capture(Command.make(executable, ...args))
169 + .pipe(Effect.catchAll(() => Effect.succeed<CommandResult | undefined>(undefined)));
170 + });
171 +
172 +const inspectAdapter = (adapter: SetupTargetAdapter) =>
173 + Effect.gen(function* () {
174 + const skillInstaller = yield* SetupSkillInstaller;
175 + const version = yield* capture(adapter.executable, ['--version']);
176 + if (!version || version.exitCode !== 0) {
177 + return {
178 + target: adapter.target,
179 + available: false,
180 + marketplace_configured: false,
181 + plugin_installed: false,
182 + plugin_enabled: false,
183 + cli_skill_ready: false,
184 + } satisfies SetupTargetStatus;
185 + }
186 +
187 + const [marketplaces, plugins] = yield* Effect.all([
188 + capture(adapter.executable, adapter.marketplaceListArgs),
189 + capture(adapter.executable, adapter.pluginListArgs),
190 + ]);
191 + const plugin =
192 + plugins && plugins.exitCode === 0
193 + ? pluginState(adapter, plugins.stdout)
194 + : { installed: false, enabled: false };
195 +
196 + const pluginReady = plugin.installed && plugin.enabled;
197 + return {
198 + target: adapter.target,
199 + available: true,
200 + marketplace_configured: Boolean(
201 + marketplaces &&
202 + marketplaces.exitCode === 0 &&
203 + marketplaceIsConfigured(adapter, marketplaces.stdout)
204 + ),
205 + plugin_installed: plugin.installed,
206 + plugin_enabled: plugin.enabled,
207 + // Codex loads the composio-cli skill from the plugin package itself. Claude's
208 + // plugin uses the standalone skill installed from the matching CLI release.
209 + cli_skill_ready:
210 + adapter.target === 'codex' ? pluginReady : yield* skillInstaller.isClaudeSkillInstalled,
211 + } satisfies SetupTargetStatus;
212 + });
213 +
214 +const runRequired = (adapter: SetupTargetAdapter, args: ReadonlyArray<string>, operation: string) =>
215 + Effect.gen(function* () {
216 + const runner = yield* CommandRunner;
217 + const result = yield* runner.capture(Command.make(adapter.executable, ...args));
218 + if (result.exitCode !== 0) {
219 + const detail = result.stderr.trim() || result.stdout.trim();
220 + return yield* Effect.fail(
221 + new Error(`${operation} failed${detail ? `: ${detail}` : ` (exit ${result.exitCode})`}`)
222 + );
223 + }
224 + });
225 +
226 +const installAdapter = (adapter: SetupTargetAdapter) =>
227 + Effect.gen(function* () {
228 + const initial = yield* inspectAdapter(adapter);
229 + if (!initial.available) {
230 + return yield* Effect.fail(
231 + new Error(
232 + `${adapter.executable} is not installed or not available on PATH. Install it and rerun \`composio setup --target ${adapter.target}\`.`
233 + )
234 + );
235 + }
236 +
237 + let pluginChanged = false;
238 + if (!initial.marketplace_configured) {
239 + yield* runRequired(
240 + adapter,
241 + adapter.marketplaceAddArgs,
242 + `Adding the ${adapter.target} marketplace`
243 + );
244 + pluginChanged = true;
245 + }
246 + if (!initial.plugin_installed) {
247 + yield* runRequired(
248 + adapter,
249 + adapter.pluginInstallArgs,
250 + `Installing the ${adapter.target} plugin`
251 + );
252 + pluginChanged = true;
253 + } else if (!initial.plugin_enabled) {
254 + yield* runRequired(
255 + adapter,
256 + adapter.pluginEnableArgs,
257 + `Enabling the ${adapter.target} plugin`
258 + );
259 + pluginChanged = true;
260 + }
261 +
262 + const skillInstaller = yield* SetupSkillInstaller;
263 + const skillChanged =
264 + adapter.target === 'claude' && !initial.cli_skill_ready
265 + ? yield* skillInstaller.ensureClaudeSkill
266 + : false;
267 +
268 + return {
269 + target: adapter.target,
270 + available: true,
271 + marketplace_configured: true,
272 + plugin_installed: true,
273 + plugin_enabled: true,
274 + cli_skill_ready: true,
275 + changed: pluginChanged || skillChanged,
276 + plugin_changed: pluginChanged,
277 + skill_changed: skillChanged,
278 + } satisfies SetupTargetResult;
279 + });
280 +
281 +export const inspectSetupTargets = Effect.all(ADAPTERS.map(inspectAdapter));
282 +
283 +export const resolveSetupTargets = (target: SetupTarget) =>
284 + Effect.gen(function* () {
285 + if (target === 'claude' || target === 'codex') return [target] as const;
286 + if (target === 'all') return ['claude', 'codex'] as const;
287 +
288 + const statuses = yield* inspectSetupTargets;
289 + const detected = statuses.filter(status => status.available).map(status => status.target);
290 + if (detected.length === 0) {
291 + return yield* Effect.fail(
292 + new Error(
293 + 'No supported agent host was detected. Install Claude Code or Codex, or pass `--target claude|codex` after installing it.'
294 + )
295 + );
296 + }
297 + return detected;
298 + });
299 +
300 +export const installSetupTargets = (targets: ReadonlyArray<AgentHost>) =>
301 + Effect.forEach(targets, target => {
302 + const adapter = ADAPTERS.find(candidate => candidate.target === target);
303 + return installAdapter(adapter as SetupTargetAdapter);
304 + });
ts/packages/cli/test/__utils__/services/test-layer.ts
+20
@@ -69,6 +69,7 @@ import { ProjectEnvironmentDetector } from 'src/services/project-environment-det
69 import { CommandRunner } from 'src/services/command-runner';
70 import { TerminalUI } from 'src/services/terminal-ui';
71 import { CommandExecutor } from '@effect/platform';
72 +import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
73
74 export interface TestLiveInput {
75 /**
@@ -198,6 +199,9 @@ export interface TestLiveInput {
199 */
200 commandRunner?: CommandRunner;
201
202 + /** Override setup's Claude skill installer. Defaults to an idempotent no-op. */
203 + setupSkillInstaller?: SetupSkillInstaller;
204 +
205 /**
206 * Override TerminalUI behavior for tests.
207 * When set, replaces the default TerminalUITest (which auto-selects first option).
@@ -1235,6 +1239,12 @@ export const TestLayer = (input?: TestLiveInput) =>
1239 CommandRunner,
1240 new CommandRunner({
1241 run: () => Effect.succeed(CommandExecutor.ExitCode(0)),
1242 + capture: () =>
1243 + Effect.succeed({
1244 + exitCode: 0,
1245 + stdout: '',
1246 + stderr: '',
1247 + }),
1248 })
1249 );
1250
@@ -1243,6 +1253,15 @@ export const TestLayer = (input?: TestLiveInput) =>
1253 ? Layer.succeed(TerminalUI, input.terminalUI)
1254 : TerminalUITest;
1255
1256 + const SetupSkillInstallerTest = Layer.succeed(
1257 + SetupSkillInstaller,
1258 + input?.setupSkillInstaller ??
1259 + new SetupSkillInstaller({
1260 + isClaudeSkillInstalled: Effect.succeed(false),
1261 + ensureClaudeSkill: Effect.succeed(false),
1262 + })
1263 + );
1264 +
1265 const _console = yield* MockConsole.make;
1266
1267 const layers = Layer.mergeAll(
@@ -1259,6 +1278,7 @@ export const TestLayer = (input?: TestLiveInput) =>
1278 JsPackageManagerDetector.Default,
1279 ProjectEnvironmentDetector.Default,
1280 CommandRunnerTest,
1281 + SetupSkillInstallerTest,
1282 ToolsExecutorTest,
1283 BunFileSystem.layer,
1284 BunContext.layer,
ts/packages/cli/test/src/commands/setup.cmd.test.ts new
+424
@@ -0,0 +1,424 @@
1 +import { Command, CommandExecutor } from '@effect/platform';
2 +import { describe, expect, layer } from '@effect/vitest';
3 +import { Effect, Exit } from 'effect';
4 +import { afterEach, vi } from 'vitest';
5 +import { CommandRunner } from 'src/services/command-runner';
6 +import { SetupSkillInstaller } from 'src/services/setup-skill-installer';
7 +import { cli, MockConsole, TestLive } from 'test/__utils__';
8 +
9 +const commandParts = (command: Command.Command): ReadonlyArray<string> => {
10 + const flattened = Command.flatten(command);
11 + const first = flattened[0];
12 + return [first.command, ...first.args];
13 +};
14 +
15 +const makeRunner = (
16 + respond: (parts: ReadonlyArray<string>) => {
17 + readonly exitCode?: number;
18 + readonly stdout?: string;
19 + readonly stderr?: string;
20 + },
21 + onRun: (parts: ReadonlyArray<string>) => void = () => undefined
22 +) =>
23 + new CommandRunner({
24 + run: command =>
25 + Effect.sync(() => {
26 + onRun(commandParts(command));
27 + return CommandExecutor.ExitCode(0);
28 + }),
29 + capture: command => {
30 + const result = respond(commandParts(command));
31 + return Effect.succeed({
32 + exitCode: result.exitCode ?? 0,
33 + stdout: result.stdout ?? '',
34 + stderr: result.stderr ?? '',
35 + });
36 + },
37 + });
38 +
39 +describe('CLI: composio setup', () => {
40 + afterEach(() => {
41 + vi.restoreAllMocks();
42 + vi.unstubAllEnvs();
43 + process.exitCode = undefined;
44 + });
45 +
46 + const humanCommands: string[][] = [];
47 + const humanRunner = makeRunner(parts => {
48 + humanCommands.push([...parts]);
49 + if (parts.join(' ') === 'claude --version') return { stdout: '2.1.0' };
50 + if (parts.join(' ') === 'claude plugin marketplace list --json') {
51 + return { stdout: '[]' };
52 + }
53 + if (parts.join(' ') === 'claude plugin list --json') return { stdout: '[]' };
54 + return {};
55 + });
56 +
57 + layer(TestLive({ fixture: 'user-config-example', commandRunner: humanRunner }))(
58 + 'Claude plugin install',
59 + it => {
60 + it.scoped('registers and installs the Claude plugin with exact native commands', () =>
61 + Effect.gen(function* () {
62 + humanCommands.length = 0;
63 + yield* cli(['setup', '--target', 'claude', '--yes']);
64 +
65 + expect(humanCommands).toContainEqual([
66 + 'claude',
67 + 'plugin',
68 + 'marketplace',
69 + 'add',
70 + 'ComposioHQ/composio-plugin-cc',
71 + '--scope',
72 + 'user',
73 + ]);
74 + expect(humanCommands).toContainEqual([
75 + 'claude',
76 + 'plugin',
77 + 'install',
78 + 'composio@composio',
79 + '--scope',
80 + 'user',
81 + ]);
82 +
83 + const output = (yield* MockConsole.getLines()).join('\n');
84 + expect(output).toContain('Configured and enabled the Composio plugin for claude');
85 + expect(output).toContain('"success":true');
86 + })
87 + );
88 + }
89 + );
90 +
91 + const codexCommands: string[][] = [];
92 + const codexInstalledRunner = makeRunner(parts => {
93 + codexCommands.push([...parts]);
94 + if (parts.join(' ') === 'codex --version') return { stdout: 'codex-cli 0.144.1' };
95 + if (parts.join(' ') === 'codex plugin marketplace list --json') {
96 + return {
97 + stdout: JSON.stringify({
98 + marketplaces: [
99 + {
100 + name: 'composio',
101 + marketplaceSource: {
102 + sourceType: 'git',
103 + source: 'https://github.com/COMPOSIOHQ/composio-plugin-openai.git/',
104 + },
105 + },
106 + ],
107 + }),
108 + };
109 + }
110 + if (parts.join(' ') === 'codex plugin list --json') {
111 + return {
112 + stdout: JSON.stringify({
113 + installed: [{ pluginId: 'composio@composio', installed: true, enabled: true }],
114 + }),
115 + };
116 + }
117 + return {};
118 + });
119 +
120 + layer(TestLive({ fixture: 'user-config-example', commandRunner: codexInstalledRunner }))(
121 + 'existing Codex install',
122 + it => {
123 + it.scoped('is idempotent when the Codex marketplace and plugin are already installed', () =>
124 + Effect.gen(function* () {
125 + codexCommands.length = 0;
126 + yield* cli(['setup', '--target', 'codex', '--yes']);
127 +
128 + expect(codexCommands).not.toContainEqual([
129 + 'codex',
130 + 'plugin',
131 + 'marketplace',
132 + 'add',
133 + 'ComposioHQ/composio-plugin-openai',
134 + '--json',
135 + ]);
136 + expect(codexCommands).not.toContainEqual([
137 + 'codex',
138 + 'plugin',
139 + 'add',
140 + 'composio@composio',
141 + '--json',
142 + ]);
143 +
144 + const output = (yield* MockConsole.getLines()).join('\n');
145 + expect(output).toContain('already installed and enabled');
146 + expect(output).toContain('"changed":false');
147 + expect(output).toContain('"cli_skill_ready":true');
148 + expect(output).toContain('"success":true');
149 + expect(output).not.toContain('uak_');
150 + expect(process.exitCode).toBeUndefined();
151 + })
152 + );
153 + }
154 + );
155 +
156 + const disabledClaudeCommands: string[][] = [];
157 + const disabledClaudeRunner = makeRunner(parts => {
158 + disabledClaudeCommands.push([...parts]);
159 + if (parts.join(' ') === 'claude --version') return { stdout: '2.1.0' };
160 + if (parts.join(' ') === 'claude plugin marketplace list --json') {
161 + return {
162 + stdout: JSON.stringify([
163 + {
164 + name: 'composio',
165 + source: { source: 'github', repo: 'ComposioHQ/composio-plugin-cc' },
166 + },
167 + ]),
168 + };
169 + }
170 + if (parts.join(' ') === 'claude plugin list --json') {
171 + return {
172 + stdout: JSON.stringify([{ id: 'composio@composio', installed: true, enabled: false }]),
173 + };
174 + }
175 + return {};
176 + });
177 +
178 + layer(TestLive({ fixture: 'user-config-example', commandRunner: disabledClaudeRunner }))(
179 + 'disabled Claude plugin',
180 + it => {
181 + it.scoped('repairs a disabled Claude plugin with the native enable command', () =>
182 + Effect.gen(function* () {
183 + disabledClaudeCommands.length = 0;
184 + yield* cli(['setup', '--target', 'claude', '--yes']);
185 +
186 + expect(disabledClaudeCommands).toContainEqual([
187 + 'claude',
188 + 'plugin',
189 + 'enable',
190 + 'composio@composio',
191 + ]);
192 + expect(disabledClaudeCommands).not.toContainEqual([
193 + 'claude',
194 + 'plugin',
195 + 'install',
196 + 'composio@composio',
197 + '--scope',
198 + 'user',
199 + ]);
200 + const output = (yield* MockConsole.getLines()).join('\n');
201 + expect(output).toContain('"plugin_installed":true');
202 + expect(output).toContain('"plugin_enabled":true');
203 + })
204 + );
205 +
206 + it.scoped('reports a disabled plugin as not enabled in machine status', () =>
207 + Effect.gen(function* () {
208 + disabledClaudeCommands.length = 0;
209 + yield* cli(['setup', 'status', '--json']);
210 +
211 + const lines = yield* MockConsole.getLines();
212 + const jsonLine = lines.filter(line => line.startsWith('{')).at(-1);
213 + const status = JSON.parse(jsonLine ?? '{}') as {
214 + targets?: Array<Record<string, unknown>>;
215 + };
216 + expect(status.targets?.find(item => item.target === 'claude')).toMatchObject({
217 + plugin_installed: true,
218 + plugin_enabled: false,
219 + });
220 + expect(disabledClaudeCommands).not.toContainEqual([
221 + 'claude',
222 + 'plugin',
223 + 'enable',
224 + 'composio@composio',
225 + ]);
226 + })
227 + );
228 + }
229 + );
230 +
231 + const disabledCodexCommands: string[][] = [];
232 + const disabledCodexRunner = makeRunner(parts => {
233 + disabledCodexCommands.push([...parts]);
234 + if (parts.join(' ') === 'codex --version') return { stdout: 'codex-cli 0.144.1' };
235 + if (parts.join(' ') === 'codex plugin marketplace list --json') {
236 + return {
237 + stdout: JSON.stringify({
238 + marketplaces: [
239 + {
240 + name: 'composio',
241 + marketplaceSource: {
242 + sourceType: 'git',
243 + source: 'ComposioHQ/composio-plugin-openai',
244 + },
245 + },
246 + ],
247 + }),
248 + };
249 + }
250 + if (parts.join(' ') === 'codex plugin list --json') {
251 + return {
252 + stdout: JSON.stringify({
253 + installed: [{ pluginId: 'composio@composio', installed: true, enabled: false }],
254 + }),
255 + };
256 + }
257 + return {};
258 + });
259 +
260 + layer(TestLive({ fixture: 'user-config-example', commandRunner: disabledCodexRunner }))(
261 + 'disabled Codex plugin',
262 + it => {
263 + it.scoped('repairs a disabled Codex plugin through its native add path', () =>
264 + Effect.gen(function* () {
265 + disabledCodexCommands.length = 0;
266 + yield* cli(['setup', '--target', 'codex', '--yes']);
267 +
268 + expect(disabledCodexCommands).toContainEqual([
269 + 'codex',
270 + 'plugin',
271 + 'add',
272 + 'composio@composio',
273 + '--json',
274 + ]);
275 + const output = (yield* MockConsole.getLines()).join('\n');
276 + expect(output).toContain('"plugin_installed":true');
277 + expect(output).toContain('"plugin_enabled":true');
278 + expect(output).toContain('"success":true');
279 + })
280 + );
281 + }
282 + );
283 +
284 + const codexFreshCommands: string[][] = [];
285 + const codexFreshRunner = makeRunner(parts => {
286 + codexFreshCommands.push([...parts]);
287 + if (parts.join(' ') === 'codex --version') return { stdout: 'codex-cli 0.144.1' };
288 + if (parts.join(' ') === 'codex plugin marketplace list --json') {
289 + return { stdout: JSON.stringify({ marketplaces: [] }) };
290 + }
291 + if (parts.join(' ') === 'codex plugin list --json') {
292 + return { stdout: JSON.stringify({ installed: [], available: [] }) };
293 + }
294 + return {};
295 + });
296 + const codexBundledSkillInstaller = new SetupSkillInstaller({
297 + isClaudeSkillInstalled: Effect.die(
298 + new Error('Codex setup must not inspect the standalone Claude skill')
299 + ),
300 + ensureClaudeSkill: Effect.die(
301 + new Error('Codex setup must not install a redundant global CLI skill')
302 + ),
303 + });
304 +
305 + layer(
306 + TestLive({
307 + fixture: 'user-config-example',
308 + commandRunner: codexFreshRunner,
309 + setupSkillInstaller: codexBundledSkillInstaller,
310 + })
311 + )('fresh Codex install', it => {
312 + it.scoped('uses the planned OpenAI marketplace and exact Codex commands', () =>
313 + Effect.gen(function* () {
314 + codexFreshCommands.length = 0;
315 + yield* cli(['setup', '--target', 'codex', '--yes']);
316 +
317 + expect(codexFreshCommands).toContainEqual([
318 + 'codex',
319 + 'plugin',
320 + 'marketplace',
321 + 'add',
322 + 'ComposioHQ/composio-plugin-openai',
323 + '--json',
324 + ]);
325 + expect(codexFreshCommands).toContainEqual([
326 + 'codex',
327 + 'plugin',
328 + 'add',
329 + 'composio@composio',
330 + '--json',
331 + ]);
332 + const output = (yield* MockConsole.getLines()).join('\n');
333 + expect(output).toContain('"cli_skill_ready":true');
334 + expect(output).toContain('"success":true');
335 + })
336 + );
337 + });
338 +
339 + const unavailableRunner = makeRunner(() => ({ exitCode: 127, stderr: 'not found' }));
340 + layer(TestLive({ commandRunner: unavailableRunner }))('status', it => {
341 + it.scoped('prints machine-readable status without installing anything', () =>
342 + Effect.gen(function* () {
343 + yield* cli(['setup', 'status', '--json']);
344 + const lines = yield* MockConsole.getLines();
345 + expect(lines).toHaveLength(1);
346 + expect(JSON.parse(lines[0] ?? '{}')).toMatchObject({
347 + targets: [
348 + { target: 'claude', available: false, cli_skill_ready: false },
349 + { target: 'codex', available: false, cli_skill_ready: false },
350 + ],
351 + });
352 + })
353 + );
354 + });
355 +
356 + const wrongMarketplaceRunner = makeRunner(parts => {
357 + if (parts.join(' ') === 'claude --version') return { stdout: '2.1.0' };
358 + if (parts.join(' ') === 'codex --version') return { exitCode: 127 };
359 + if (parts.join(' ') === 'claude plugin marketplace list --json') {
360 + return {
361 + stdout: JSON.stringify([
362 + {
363 + name: 'composio',
364 + source: { source: 'github', repo: 'someone-else/not-composio' },
365 + },
366 + ]),
367 + };
368 + }
369 + if (parts.join(' ') === 'claude plugin list --json') return { stdout: '[]' };
370 + return {};
371 + });
372 + layer(TestLive({ commandRunner: wrongMarketplaceRunner }))('exact marketplace status', it => {
373 + it.scoped('does not accept a same-named marketplace from the wrong repository', () =>
374 + Effect.gen(function* () {
375 + yield* cli(['setup', 'status', '--json']);
376 + const [line] = yield* MockConsole.getLines();
377 + const status = JSON.parse(line ?? '{}') as {
378 + targets?: Array<Record<string, unknown>>;
379 + };
380 + expect(status.targets?.find(item => item.target === 'claude')).toMatchObject({
381 + marketplace_configured: false,
382 + });
383 + })
384 + );
385 + });
386 +
387 + const failingInstallRunner = makeRunner(parts => {
388 + if (parts.join(' ') === 'claude --version') return { stdout: '2.1.0' };
389 + if (parts.join(' ') === 'claude plugin marketplace list --json') return { stdout: '[]' };
390 + if (parts.join(' ') === 'claude plugin list --json') return { stdout: '[]' };
391 + if (parts.includes('install')) return { exitCode: 2, stderr: 'install failed' };
392 + return {};
393 + });
394 + layer(TestLive({ fixture: 'user-config-example', commandRunner: failingInstallRunner }))(
395 + 'partial failure',
396 + it => {
397 + it.scoped('fails the command when a native plugin install fails', () =>
398 + Effect.gen(function* () {
399 + const exit = yield* Effect.exit(cli(['setup', '--target', 'claude', '--yes']));
400 + expect(Exit.isFailure(exit)).toBe(true);
401 + })
402 + );
403 + }
404 + );
405 +
406 + const failingSkillInstaller = new SetupSkillInstaller({
407 + isClaudeSkillInstalled: Effect.succeed(false),
408 + ensureClaudeSkill: Effect.fail(new Error('skill download failed')),
409 + });
410 + layer(
411 + TestLive({
412 + fixture: 'user-config-example',
413 + commandRunner: humanRunner,
414 + setupSkillInstaller: failingSkillInstaller,
415 + })
416 + )('skill failure', it => {
417 + it.scoped('fails rather than reporting readiness when the required Claude skill fails', () =>
418 + Effect.gen(function* () {
419 + const exit = yield* Effect.exit(cli(['setup', '--target', 'claude', '--yes']));
420 + expect(Exit.isFailure(exit)).toBe(true);
421 + })
422 + );
423 + });
424 +});