Configuring ACP Adapters

ACP adapters connect CodeCompanion to an agent, such as Claude Code or Codex, over the Agent Client Protocol. CodeCompanion starts the agent as a separate process, and the agent brings its own tools, approvals and context management. ACP adapters sit under adapters.acp and share most of their configuration with HTTP adapters, so read the two pages together.

Built-in Adapters

Adapter	Agent	Command
auggie_cli	Auggie CLI	auggie --acp
cagent	Cagent	cagent acp basic_agent.yaml
claude_code	Claude Code	claude-agent-acp
cline_cli	Cline CLI	cline --acp
codex	Codex	codex-acp
copilot_acp	Copilot CLI	copilot --acp --stdio
cursor_cli	Cursor CLI	agent acp
gemini_cli	Gemini CLI	gemini --experimental-acp
goose	Goose	goose acp
kilocode	Kilo Code	kilo acp
kimi_cli	Kimi CLI	kimi acp
kiro	Kiro CLI	kiro-cli acp
mistral_vibe	Mistral Vibe	vibe-acp
opencode	OpenCode	opencode acp

The command must be on your PATH.

Customising an Adapter

There are two ways to customise a built-in adapter, and this page uses both:

• Function - For full or computed setups, such as custom commands or defaults, or values resolved when the adapter loads
• extend table - For static overrides, such as credentials or a default value

Function

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, -- milliseconds
          },
          env = { GEMINI_API_KEY = "cmd:op read op://personal/Gemini/credential --no-newline" },
        })
      end,
    },
  },
})

Extend Table

require("codecompanion").setup({
  adapters = {
    acp = {
      extend = {
        gemini_cli = {
          defaults = { auth_method = "gemini-api-key" },
          env = { GEMINI_API_KEY = "cmd:op read op://personal/Gemini/credential --no-newline" },
        },
      },
    },
  },
})

IMPORTANT

Each key in extend is the adapter's key under adapters.acp, not the adapter's name

Values in env are resolved in the same way as for HTTP adapters, then passed to the agent's process as environment variables.

The auth_method must match an ID the agent advertises. If it doesn't, the log lists the ones that are available.

Setting a Default Adapter

To use an agent for every chat:

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

Commands

An adapter starts its agent with the default entry in its commands table. claude_code and gemini_cli also have a yolo command, which starts the agent with --yolo. To add your own:

require("codecompanion").setup({
  adapters = {
    acp = {
      extend = {
        cagent = {
          commands = {
            reviewer = { "cagent", "acp", "reviewer.yaml" },
          },
        },
      },
    },
  },
})

To start a chat with a command other than default:

:CodeCompanionChat adapter=cagent command=reviewer

From inside a chat buffer, use the /command slash command.

Setting Default Session Config Options

Session config options are settings an agent shares at the start of a session, such as its models, modes and reasoning levels. Set their defaults in defaults.session_config_options, keyed by the option's category.

Models

Set the model on the interaction, or on the adapter so it applies everywhere:

Interactions

require("codecompanion").setup({
  interactions = {
    chat = {
      adapter = {
        name = "codex",
        model = "gpt-5.4",
      },
    },
  },
})

Adapter String

require("codecompanion").setup({
  adapters = {
    acp = {
      codex = function()
        return require("codecompanion.adapters").extend("codex", {
          defaults = {
            session_config_options = {
              model = "gpt-5.4",
            },
          },
        })
      end,
    },
  },
})

Adapter Function

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

Any other option goes in the same 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,
    },
  },
})

A value matches either the option's value or its name, ignoring case. The model is set first, as it can change which other options are available. To see an agent's options and their values, open the debug window.

Configuring MCP Servers

Some agents support connecting to Model Context Protocol (MCP) servers. To pass on the servers in your MCP configuration:

require("codecompanion").setup({
  adapters = {
    acp = {
      claude_code = function()
        return require("codecompanion.adapters").extend("claude_code", {
          defaults = {
            mcpServers = "inherit_from_config",
          },
        })
      end,
    },
  },
})

Only the servers in mcp.opts.default_servers are passed, and setting mcp.opts.acp_enabled = false stops them being passed at all. The agent starts and runs the servers itself, so they don't appear in the chat buffer's context.

To set the servers on the adapter instead, such as Claude Code with the sequential-thinking server over 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,
    },
  },
})

Hiding Preset Adapters

To list only the adapters in your own config, leaving out the built-in ones:

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

To hide individual adapters, see Hiding Adapters.

Setup: Auggie CLI from Augment Code

Follow the Getting Started guide for Auggie CLI, then select the auggie_cli adapter.

Setup: Cagent

To use Docker's Cagent:

1. Install Cagent
2. Create an agent in your repository
3. Test it with cagent run your_agent.yaml
4. Point the cagent adapter at your agent:

require("codecompanion").setup({
  adapters = {
    acp = {
      cagent = function()
        return require("codecompanion.adapters").extend("cagent", {
          commands = {
            default = {
              "cagent",
              "acp",
              "your_agent.yaml",
            },
          },
        })
      end,
    },
  },
})

For more than one agent, add a command for each.

Setup: Claude Code

To use Claude Code:

1. Install Claude Code
2. Install Zed's ACP adapter for Claude Code
3. Authenticate with a Claude Pro subscription or an API key, as below

Using Claude Pro Subscription

1. Run claude setup-token and authorise in the browser:
2. Copy the OAuth token, shown in yellow:
3. Set it on the claude_code adapter:

require("codecompanion").setup({
  adapters = {
    acp = {
      claude_code = function()
        return require("codecompanion.adapters").extend("claude_code", {
          env = {
            CLAUDE_CODE_OAUTH_TOKEN = "my-oauth-token",
          },
        })
      end,
    },
  },
})

If CLAUDE_CODE_OAUTH_TOKEN is already exported in your shell, skip step 3. See environment variables for other ways to supply the token.

Using an API Key

1. Create an API key in the Anthropic console
2. Set it on the claude_code adapter:

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:

1. Install Cline CLI
2. Run cline auth
3. Select the cline_cli adapter

Setup: Codex

To use OpenAI's Codex, install codex-acp.

The adapter authenticates with OPENAI_API_KEY from your shell by default. To set the key on the adapter, or to sign in with ChatGPT instead:

require("codecompanion").setup({
  adapters = {
    acp = {
      codex = function()
        return require("codecompanion.adapters").extend("codex", {
          defaults = {
            auth_method = "api-key", -- Can be "api-key" or "chat-gpt"
          },
          env = {
            OPENAI_API_KEY = "my-api-key",
          },
        })
      end,
    },
  },
})

Setup: Copilot CLI

Install Copilot CLI, run copilot to sign in, then select the copilot_acp adapter.

Setup: Cursor CLI

To use Cursor:

1. Install agent from the Cursor CLI documentation
2. Run agent login
3. Select the cursor_cli adapter

Setup: Gemini CLI

Install Gemini CLI, then choose an auth_method:

Method	Description
oauth-personal	Sign in with your Google account (default)
gemini-api-key	Use GEMINI_API_KEY
vertex-ai	Use Vertex AI

To use an API key from the 1Password CLI:

require("codecompanion").setup({
  adapters = {
    acp = {
      gemini_cli = function()
        return require("codecompanion.adapters").extend("gemini_cli", {
          defaults = {
            auth_method = "gemini-api-key",
          },
          env = {
            GEMINI_API_KEY = "cmd:op read op://personal/Gemini_API/credential --no-newline",
          },
        })
      end,
    },
  },
})

Setup: Goose CLI

Install and set up Goose CLI, then select the goose adapter.

Setup: Kilo Code

Install and configure Kilo Code, then select the kilocode adapter.

To set the model, edit ~/.config/kilo/kilo.json:

{
  "$schema": "https://kilo.ai/config.json",
  "model": "kilo/kilo-auto/free"
}

Setup: Kimi CLI

Install Kimi CLI, run kimi and then /login to set your API key, then select the kimi_cli adapter.

Setup: Kiro CLI

Install Kiro CLI and sign in, then select the kiro adapter.

Setup: Mistral Vibe

Install Mistral Vibe, run vibe --setup to set your API key, then select the mistral_vibe adapter.

Setup: OpenCode

Install and configure OpenCode, then select the opencode adapter.

To set the model, edit ~/.config/opencode/opencode.jsonc or ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "github-copilot/claude-sonnet-4.5"
}

OpenCode doesn't send diffs for code review by default. To turn them on, set its permissions to ask:

{
  "$schema": "https://opencode.ai/config.json",
  "model": "opencode-go/mimo-v2.5-pro",
  "permission": {
    "*": "ask"
  }
}

Creating Custom ACP Adapters

For an agent without a built-in adapter, define your own. This example uses a hypothetical myagent CLI, and the built-in ACP adapters make a good reference:

require("codecompanion").setup({
  adapters = {
    acp = {
      my_agent = function()
        local helpers = require("codecompanion.adapters.acp.helpers")
        return {
          name = "my_agent",
          formatted_name = "MyAgent",
          type = "acp",
          roles = {
            llm = "assistant",
            user = "user",
          },
          commands = {
            default = {
              "myagent",
              "--acp",
            },
          },
          defaults = {
            mcpServers = {},
            timeout = 20000, -- milliseconds
          },
          parameters = {
            protocolVersion = 1,
            clientCapabilities = {
              fs = { readTextFile = true, writeTextFile = true },
            },
            clientInfo = {
              name = "CodeCompanion.nvim",
              version = "1.0.0",
            },
          },
          handlers = {
            lifecycle = {
              setup = function(self)
                return true
              end,
              auth = function(self)
                return true
              end,
            },
            request = {
              build_messages = helpers.build_messages,
            },
          },
        }
      end,
    },
  },
})

Raise issues and questions about user-created adapters in the adapter discussions.