doc/configuration/adapters-acp.md
This section contains configuration which is specific to Agent Client Protocol (ACP) adapters only. There is a lot of shared functionality between ACP and http adapters. Therefore it's recommended you read the two pages together.
To change any of the default settings for an ACP adapter, you can extend it in your CodeCompanion setup. For example, to change the timeout and authentication method for the Gemini CLI adapter, you can do the following:
require("codecompanion").setup({
adapters = {
acp = {
gemini_cli = function()
return require("codecompanion.adapters").extend("gemini_cli", {
commands = {
default = {
"some-other-gemini"
"--experimental-acp",
},
},
defaults = {
auth_method = "gemini-api-key",
timeout = 20000, -- 20 seconds
},
env = {
GEMINI_API_KEY = "GEMINI_API_KEY",
},
})
end,
},
},
})
You can select an ACP adapter to be the default for all chat interactions:
require("codecompanion").setup({
interactions = {
chat = {
adapter = "gemini_cli",
},
},
}),
The ACP specification has recently added support for session config options. These are lists of configuration options that agents can share with CodeCompanion at the start of a session such as models, reasoning levels, and more.
There are numerous was you can set a model in your config and it differs significantly from other session config options because of how CodeCompanion integrates adapters and models into the chat interaction.
::: code-group
require("codecompanion").setup({
interactions = {
chat = {
adapter = {
name = "codex",
model = "gpt-5.4",
},
},
},
}),
require("codecompanion").setup({
adapters = {
acp = {
codex = function()
return require("codecompanion.adapters").extend("codex", {
defaults = {
session_config_options = {
model = "gpt-5.4"
},
},
})
end,
}
},
}),
require("codecompanion").setup({
adapters = {
acp = {
codex = function()
return require("codecompanion.adapters").extend("codex", {
defaults = {
session_config_options = {
---@param self CodeCompanion.ACPAdapter
---@return string
model = function(self)
return "gpt-5.4"
end,
},
},
})
end,
}
},
}),
:::
To set any other session config option, you can pass them in the defaults.session_config_options table:
require("codecompanion").setup({
adapters = {
acp = {
codex = function()
return require("codecompanion.adapters").extend("codex", {
defaults = {
session_config_options = {
mode = "Full Access",
thought_level = "Xhigh",
},
},
})
end,
}
},
}),
To find out what the available session config options are for a specific adapter you can open the debug window in the chat buffer.
Some ACP adapters support connecting to Model Client Protocol (MCP) servers. If you've defined MCP servers in your configuration, then CodeCompanion can automatically connect to those servers when initializing the adapter.
To enable this, set inherit_from_config in the ACP adapter's defaults.mcpServers field:
require("codecompanion").setup({
adapters = {
acp = {
claude_code = function()
return require("codecompanion.adapters").extend("claude_code", {
defaults = {
mcpServers = "inherit_from_config",
},
})
end,
},
},
})
[!NOTE] CodeCompanion does not display the MCP servers in the chat buffer's context when used with an ACP adapter.
Alternatively, you can configure MCP servers manually. In the below example, we're configuring Claude Code to connect to the sequential-thinking server via stdio:
require("codecompanion").setup({
adapters = {
acp = {
claude_code = function()
return require("codecompanion.adapters").extend("claude_code", {
defaults = {
mcpServers = {
{
name = "sequential-thinking",
command = "npx",
args = { "-y", "@modelcontextprotocol/server-sequential-thinking" },
env = {},
},
},
},
})
end,
},
},
})
You can also disable this by setting mcp.opts.acp_enabled = false in your configuration.
By default, the plugin shows all available adapters, including the presets. If you prefer to only display the adapters defined in your user configuration, you can set the show_presets option to false:
require("codecompanion").setup({
adapters = {
acp = {
opts = {
show_presets = false,
},
},
},
})
To use Auggie CLI within CodeCompanion, you simply need to follow their Getting Started guide.
To use Docker's Cagent within CodeCompanion, you need to follow these steps:
cagent run your_agent.yaml in the CLIcagent adapter to include the agent:require("codecompanion").setup({
adapters = {
acp = {
cagent = function()
return require("codecompanion.adapters").extend("cagent", {
commands = {
default = {
"cagent",
"acp",
"your_agent.yaml",
},
},
})
end,
},
},
})
If you have multiple agent files that you like to run separately, you can create multiple commands for each agent.
To use Claude Code within CodeCompanion, you'll need to take the following steps:
In your CLI, run claude setup-token. You'll be redirected to the Claude.ai website for authorization:
Back in your CLI, copy the OAuth token (in yellow):
In your CodeCompanion config, extend the claude_code adapter and include the OAuth token (see the section on environment variables and setting API keys for other ways to do this):
require("codecompanion").setup({
adapters = {
acp = {
claude_code = function()
return require("codecompanion.adapters").extend("claude_code", {
env = {
CLAUDE_CODE_OAUTH_TOKEN = "my-oauth-token",
},
})
end,
},
},
})
claude_code adapter and set the ANTHROPIC_API_KEY:require("codecompanion").setup({
adapters = {
acp = {
claude_code = function()
return require("codecompanion.adapters").extend("claude_code", {
env = {
ANTHROPIC_API_KEY = "my-api-key",
},
})
end,
},
},
})
To use Cline CLI within CodeCompanion, you'll need to take the following steps:
cline auth.cline_cli adapter in your chat bufferTo use OpenAI's Codex, install an ACP-compatible adapter like this one from Zed.
By default, the adapter will look for an OPENAI_API_KEY in your shell, however you can also authenticate via ChatGPT. This can be customized in the plugin configuration:
require("codecompanion").setup({
adapters = {
acp = {
codex = function()
return require("codecompanion.adapters").extend("codex", {
defaults = {
auth_method = "openai-api-key", -- "openai-api-key"|"codex-api-key"|"chatgpt"
},
env = {
OPENAI_API_KEY = "my-api-key",
},
})
end,
},
},
})
Install Copilot CLI as per the instructions and then in the terminal run copilot and ensure that you're authenticated.
To use Cursor within CodeCompanion, you'll need to take the following steps:
agent as per the Cursor CLI documentationagent login in your terminalcursor_cli adapter in your chat bufferoauth-personal which uses your Google logingemini-api-keyvertex-ai)The example below uses the gemini-api-key method, pulling the API key from 1Password CLI:
require("codecompanion").setup({
adapters = {
acp = {
gemini_cli = function()
return require("codecompanion.adapters").extend("gemini_cli", {
defaults = {
auth_method = "gemini-api-key", -- "oauth-personal"|"gemini-api-key"|"vertex-ai"
},
env = {
GEMINI_API_KEY = "cmd:op read op://personal/Gemini_API/credential --no-newline",
},
})
end,
},
},
})
To use Goose in CodeCompanion, ensure you've followed their documentation to setup and install Goose CLI. Then ensure that in your chat buffer you select the goose adapter.
To use Kilo Code in CodeCompanion, ensure you've followed their documentation to install and configure it. Then ensure that in your chat buffer you select the kilocode adapter.
You can specify a custom model in your ~/.config/kilo/kilo.json file:
{
"$schema": "https://kilo.ai/config.json",
"model": "kilo/kilo-auto/free",
}
Install Kimi CLI as per their instructions. Then in the CLI, run kimi followed by /login to configure your API key. Then ensure that in your chat buffer you select the kimi_cli adapter.
Install Kiro cli as per their instructions. Then open it and login (if installation doesn't already prompt you to login). the codecompanion adapter will execute kiro-cli acp, make sure to have it available on your PATH.
To use Mistral Vibe in CodeCompanion, ensure you've followed their documentation to install. Then run vibe --setup in your CLI in order to setup your API key. Then ensure that in your chat buffer you select the mistral_vibe adapter.
To use OpenCode in CodeCompanion, ensure you've followed their documentation to install and configure it. Then ensure that in your chat buffer you select the opencode adapter.
You can specify a custom model in your ~/.config/opencode/config.json file:
{
"$schema": "https://opencode.ai/config.json",
"model": "github-copilot/claude-sonnet-4.5",
}