Connect coding agents

Use your own installed GitHub Copilot, Amazon Q / Kiro, Gemini CLI or OpenCode in Cleetus through the Agent Client Protocol (ACP). ACP connects a compatible coding agent to Cleetus conversations and agent workflows over its documented stdio interface.

These connections first shipped in Cleetus Beta 0.2.0-beta.2 for macOS Apple Silicon. Use the beta release notes to check its preview boundaries. Stable IDE and VSIX downloads have independent versions and may not include this connection flow. The guided Claude Code setup below is new for 0.2.0-beta.3; beta 2 does not include that guided flow. Check your installed release notes before using it.

This guide applies to builds with Cleetus: Connect coding agents in the Command Palette. If that command is absent, your installed build does not include this connection flow; check its release notes before updating. Extension and IDE releases remain independent. The release links in the installation guide do not by themselves establish ACP feature availability.

Claude API/cloud and Codex retain their existing setup. Claude Code uses the separate guided setup below. Connecting an ACP agent does not convert those engines or their saved conversations.

#Install and sign in with your own CLI

Install each provider's CLI using its official instructions, outside your project directory. Cleetus does not bundle or automatically install these runtimes. Your account, provider access, subscription requirements and usage charges remain with the provider.

The ACP column is a launch reference. An ACP command waits for protocol messages from its client; it is not the CLI's ordinary interactive chat or login command.

GitHub marks Copilot ACP as public preview. AWS has rebranded Amazon Q Developer CLI to Kiro; this connection uses Kiro V3, not a legacy q executable or the V2 private API. Kiro documents the explicit V3 launch and CLI-owned authentication. Gemini's current configuration reference documents --acp; OpenCode documents ACP stdio support. Use a provider version that supports its documented command.

#Connect in VS Code or Cleetus IDE

1. Open the project folder you intend to work in.
2. Run Cleetus: Connect coding agents from the Command Palette. In the VS Code extension, Get started → Connect more coding agents opens the same flow. In the native IDE, Agents in Studio's top bar opens it.
3. On the provider card, choose Installation guide if needed, then Refresh installed agents. Installed means Cleetus found a usable local executable. It does not establish sign-in or model access.
4. If the editor cannot find your CLI, expand Executable and launch arguments and enter its absolute executable path. Arguments are a JSON array of separate strings. Keep the provider's default ACP arguments.
5. Choose Sign in with provider when needed. Review the launch approval, then finish the provider's native sign-in in the editor terminal and its browser flow. Cleetus does not collect the credentials or copy them into an SDK.
6. Choose Connect. Review the exact executable, resolved path, arguments and project in the approval dialog. Enabled means the connection is registered for use in Cleetus.
7. Optionally choose Check protocol. This starts the CLI to check its ACP handshake. Refresh models in the conversation or agent settings, then send a small, bounded request and review its actual result.

Refresh installed agents performs filesystem discovery without starting a CLI. Check protocol and model discovery can start an ACP process and may encounter authentication requirements. A successful handshake does not establish that inference, a particular model, or a provider tool call will succeed.

If installation changed the PATH, restart the editor so it receives the updated environment, or use an absolute executable path. No shell expansion is applied: ~, environment assignments, pipelines and combined command strings are not executable paths. Windows .cmd, .bat and .ps1 launch wrappers are unsupported by this direct-executable connection path; Windows provider execution needs separate verification.

#Use a connected agent

Choose the enabled engine in a conversation, team member, task or Design agent setting where that engine is offered. Review the working directory and MCP assignments before starting. Team templates provide starting settings; inspect each member's engine and use Engine default when a model is not yet known. Supervised teams require a supervisor engine that supports Cleetus coordination; Claude and connected ACP engines support this path. Codex can join as a member.

Model and effort choices come from the running agent's advertised metadata. They may vary with CLI version, provider, account and session. An absent choice is not replaced with a guessed model name or High effort. A configured choice is not evidence of what executed; rely on reported results. Account details remain unknown when the provider does not report them. This ACP connection does not supply a subscription usage or cost meter.

ACP does not guarantee feature parity between agents. Resume depends on the running provider's advertised support. This connection does not provide image input, session forks, rewind, client-side file access or client terminal tools. MCP support depends on the provider's negotiated capabilities and your explicit assignments. An agent can still have its own native tools and configuration.

#Review permissions and connection changes

Enabling a connection approves that exact local launch configuration. It does not approve every later tool action. When an agent sends an ACP tool-permission request, Cleetus offers a one-time approval. It does not return persistent "allow always" choices. Missing approval UI, cancellation, timeout or an unsupported permission request denies or cancels the request.

These approvals cover requests the provider sends through ACP. The CLI retains its native access and configuration; a custom executable is not sandboxed by Cleetus. Use a trusted provider executable and review its own tool policy. Connection profiles reject known approval-bypass flags, including --yes, --allow-all-tools and --dangerously-skip-permissions, as well as credentials and environment overrides. Complete authentication through the provider instead.

Choose Disconnect to disable a connection. Use Close conversation in the IDE agent workspace or Close agent connection in VS Code chat to retain history while closing the provider. Close all live Cleetus sessions before disabling it or changing its executable or arguments; an idle open session still counts as live. Disconnecting retains saved conversations and does not sign out of the provider. Changing engines does not migrate a native session between vendors. Stop interrupts work; review any changes already made.

If settings or the executable change while an approval is open, Cleetus rejects the stale request. Refresh the connection panel and review the new configuration. Invalid external settings edits surface an error while retaining the previous registered engines; repair the settings before making further connection changes.

#Connect another ACP agent

Expand Custom ACP connection and use the provider's documented stdio server:

Choose Review and connect and inspect the exact launch approval. Custom ids start with acp- and use lowercase alphanumeric segments separated by hyphens. Up to 16 connection profiles can be saved. Arguments are limited to 32 strings, 4096 bytes each and 16 KiB in total.

Custom connections support ACP stdio only. An arbitrary terminal CLI, MCP server, interactive text stream or shell script does not become an integrated coding agent by adding a profile. Cleetus does not parse terminal text into chat or install an ACP wrapper automatically. Use the custom provider's own login flow; Cleetus cannot invent its authentication command or infer its account entitlement.

Executables inside the project are refused, including symlinks that resolve into the project or project-local links to external programs. Relative or empty PATH entries are ignored. Shells, shell builtins and command/package wrappers such as sh, env and npx are not accepted as agent executables. Install the agent independently and select its actual executable.

#Troubleshooting

This guide describes implemented connection behavior and provider documentation. It does not report successful real-account inference or tool execution for every listed CLI. Validate your own provider/version with a bounded request and inspect the actual output and changes. For other problems, see troubleshooting.

#Connect your own Claude Code

In beta 3 builds, Get started → Claude Code → Connect Claude Code opens the shared Coding agent connections dialog. You can also run Cleetus: Connect coding agents or choose Agents in native Studio. The Claude Code card runs your own unmodified Claude Code installation; this is separate from ACP and from the Claude API/cloud SDK engine.

1. If the CLI is unavailable, choose Installation guide for Claude Code's official setup instructions. Install it independently, then choose Refresh status. Cleetus does not run an installer or bundle the CLI. You can check installation and sign in before opening a project.
2. Choose Connect. Cleetus checks the CLI's own authentication status. If it already reports a sign-in, Connect reuses it without starting another login. If sign-in is needed, review the exact native CLI launch approval.
3. Sign in / change account explicitly starts the CLI's claude auth login flow. A browser may open. Claude Code owns authentication and its callback; Cleetus supplies no OAuth page, captured login URL, token field or code collector. Starting that process does not prove sign-in completed.
4. If a browser does not open, cannot finish, or asks for a manual code, choose Open native setup. This explicitly opens Claude Code's own setup in an editor terminal. Complete any manual-code step there. Cancel setup stops the setup owned by this connection.
5. Choose Enable hosted Claude Code to review the separate settings opt-in, then choose Reload Cleetus when offered. This enables the Terminal agents engine; it does not complete authentication or enable custom channels. The channel setting remains unchanged and defaults to off.
6. Once the engine is enabled and the card reports sign-in, open your project and choose Use in Cleetus. This selects Terminal agents in the composer. It does not launch an agent, send a goal or perform inference. Starting work remains a separate action.

The card distinguishes Installed, Signed in, Not signed in and Sign-in status unknown. It labels the reported authentication as Claude account, API credentials, Cloud provider or Authentication unknown. A displayed plan is a sanitized value reported by the CLI, not an entitlement check. Your subscription is used only when Claude Code selects Claude account authentication; native API or cloud configuration may take precedence. Cleetus preserves that configuration and environment rather than stripping overrides. These labels do not guarantee billing, usage allowances, model access or quotas for parallel agents. Usage remains with the provider.

While setup is active, the open dialog checks status every four seconds, with one polling read at a time, for at most ten minutes. Status updates preserve unsaved ACP connection fields. Cancel setup and Open native setup do not wait for an outstanding UI polling read before sending their control requests. Closing the dialog stops its UI polling; it does not itself cancel the separately bounded native setup. Reopen the dialog and choose Cancel setup if you want to stop that setup. Native setup also has a ten-minute deadline.

The ordinary Terminal agents mode can still require interaction in Claude Code's terminal. Guided sign-in does not make every native prompt available in Cleetus. Existing Claude API/cloud and Codex conversations remain separate and are not converted into hosted Claude Code sessions.

#Maintainer-only local channel preview

For maintainers developing and reviewing a Cleetus channel locally, compatible beta builds expose an opt-in local development experiment. This is separate from guided Claude Code setup. Production channel distribution and publisher approval remain unconfirmed; enabling the experiment does not establish them. To test a channel you are developing:

1. Open Cleetus Settings → Preferences (in native Studio, use the Workspace → Settings menu).
2. With hosted Claude Code explicitly enabled as described above, set terminalAgentsChannelMode to development. Save preferences, then run Developer: Reload Window. Guided setup never turns this setting on for you.
3. Select Terminal agents in the grouped model list and start a bounded conversation or a reviewed team member.
4. When Cleetus offers Complete native setup, open Claude Code and complete its own sign-in, folder trust, initial MCP consent and development-channel confirmation. These steps cannot be answered by the Cleetus channel.
5. After the channel connects, use the Cleetus agent workspace and conversation dock for messages, replies and supported one-time tool decisions. A connected local transport and a reply linked to a channel message are separate observations; only the latter establishes a working channel round trip. Sent to channel means transport delivery. Reply linked means the agent explicitly associated a reply with that message; it does not mean the task is complete. Expired Cleetus approval windows and reused request IDs retain a Review in Claude Code action. They cannot grant a new approval or prove that the native prompt closed.
6. Use Open Claude Code for unsupported native prompts, or reconnect an ordinary disconnected conversation explicitly. Task/team work must restart through its own authorized execution path.

This requires a Claude Code version with the documented channels feature and any applicable organization permission. Custom development channels require Claude Code's own explicit confirmation. Hosted mode and custom channels default to off; native consent and production approval are separate requirements. This preview does not promise that downloaded production channels can use the development path or that all Claude Code interactions can move into Cleetus.