Skip to content

adapters-acp.md

Latest commit

 

History

History
417 lines (337 loc) · 13.4 KB

adapters-acp.md

File metadata and controls

417 lines (337 loc) · 13.4 KB
description Learn how to configure ACP adapters like Claude Code, Gemini CLI and Codex

Configuring ACP Adapters

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.

Configuring Adapter Settings

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,
    },
  },
})

Setting a Default Adapter

You can select an ACP adapter to be the default for all chat interactions:

require("codecompanion").setup({
  interactions = {
    chat = {
      adapter = "gemini_cli",
    },
  },
}),

Setting Default Session Config Options

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.

Models

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,
    }
  },
}),

:::

Others

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.

Configuring MCP Servers

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.

Hiding Preset Adapters

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,
      },
    },
  },
})

Controlling Model Choices

When switching between adapters, the plugin typically displays all available model choices for the selected adapter. If you want to simplify the interface and have the default model automatically chosen (without showing any model selection UI), you can set the show_model_choices option to false:

require("codecompanion").setup({
  adapters = {
    acp = {
      opts = {
        show_model_choices = false,
      },
    },
  },
})

With show_model_choices = false, the default model (as reported by the ACP agent) will be automatically selected when changing adapters, and no model selection will be shown to the user.

Setup: Auggie CLI from Augment Code

To use Auggie CLI within CodeCompanion, you simply need to follow their Getting Started guide.

Setup: Cagent

To use Docker's Cagent within CodeCompanion, you need to follow these steps:

  1. Install Cagent as per their instructions
  2. Create an agent in the repository you're working from
  3. Test the agent by running cagent run your_agent.yaml in the CLI
  4. In your CodeCompanion config, extend the cagent 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.

Setup: Claude Code

To use Claude Code within CodeCompanion, you'll need to take the following steps:

  1. Install Claude Code
  2. Install the Zed ACP adapter for Claude Code

Using Claude Pro Subscription

  1. In your CLI, run claude setup-token. You'll be redirected to the Claude.ai website for authorization:
4. Back in your CLI, copy the OAuth token (in yellow): 5. In your CodeCompanion config, extend the `claude_code` adapter and include the OAuth token (see the section on [environment variables and setting API keys](/configuration/adapters-http#environment-variables-setting-an-api-key) for other ways to do this): ```lua require("codecompanion").setup({ adapters = { acp = { claude_code = function() return require("codecompanion.adapters").extend("claude_code", { env = { CLAUDE_CODE_OAUTH_TOKEN = "my-oauth-token", }, }) end, }, }, }) ```

Using an API Key

  1. Create an API key in your Anthropic console.
  2. In your CodeCompanion config, extend the 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,
    },
  },
})

Setup: Cline CLI

To use Cline CLI within CodeCompanion, you'll need to take the following steps:

  1. Install Cline CLI.
  2. Authenticate by running cline auth.
  3. Select the cline_cli adapter in your chat buffer

Setup: Codex

To 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,
    },
  },
})

Setup: Copilot CLI

Install Copilot CLI as per the instructions and then in the terminal run copilot and ensure that you're authenticated.

Setup: Cursor CLI

To use Cursor within CodeCompanion, you'll need to take the following steps:

  1. Install agent as per the Cursor CLI documentation
  2. Authenticate by running agent login in your terminal
  3. Select the cursor_cli adapter in your chat buffer

Setup: Gemini CLI

  1. Install Gemini CLI
  2. Update your CodeCompanion config and select which authentication methods you'd like to use. Currently there are:
    • oauth-personal which uses your Google login
    • gemini-api-key
    • vertex-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,
    },
  },
})

Setup: Goose CLI

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.

Setup: Kimi CLI

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.

Setup: Kiro CLI

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.

Setup: Mistral Vibe

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.

Setup: OpenCode

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",
}