Configuring the Command-Line Interface (CLI)

By default, CodeCompanion uses the terminal provider for CLI interactions, which runs agents in a Neovim terminal buffer. However, the CLI system is flexible and allows you to define custom agents and providers to suit your workflow.

Agents

To use the CLI interaction, you need to define at least one agent in your configuration:

require("codecompanion").setup({
  interactions = {
    cli = {
      agent = "claude_code",
      agents = {
        claude_code = {
          cmd = "claude",
          args = {},
          description = "Claude Code CLI",
          provider = "terminal",
        },
      },
    },
  },
})

The agent field sets the default agent. You can override it per-command with :CodeCompanionCLI agent=<name>.

Agent Options

Option	Type	Description
cmd	string	The command to run (e.g. "claude", "codex")
args	table	Arguments to pass to the command
description	string	Description shown in the action palette
provider	string	Which provider to use (defaults to "terminal")

Multiple Agents

You can define multiple agents and switch between them:

require("codecompanion").setup({
  interactions = {
    cli = {
      agent = "claude_code",
      agents = {
        claude_code = {
          cmd = "claude",
          args = {},
          description = "Claude Code CLI",
        },
        codex = {
          cmd = "codex",
          args = {},
          description = "OpenAI Codex CLI",
        },
      },
    },
  },
})

Then use :CodeCompanionCLI agent=codex <prompt> to use a specific agent.

Providers

Providers determine how the CLI agent is run. The built-in terminal provider uses a Neovim terminal buffer with jobstart():

require("codecompanion").setup({
  interactions = {
    cli = {
      providers = {
        terminal = {
          path = "interactions.cli.providers.terminal",
          description = "Terminal CLI provider",
        },
      },
    },
  },
})

Custom Providers

You can create custom providers and reference them by module path or file path:

require("codecompanion").setup({
  interactions = {
    cli = {
      providers = {
        my_provider = {
          -- Can be a codecompanion module, a Lua module, or a file path
          path = "my_custom.cli_provider",
          description = "My custom CLI provider",
        },
      },
      agents = {
        my_agent = {
          cmd = "my-cli",
          args = {},
          provider = "my_provider",
        },
      },
    },
  },
})

If an agent's provider field doesn't match any entry in the providers table, the terminal provider is used as a fallback.

Keymaps

The CLI buffer supports keymaps for navigating between interactions:

require("codecompanion").setup({
  interactions = {
    cli = {
      keymaps = {
        next_chat = {
          modes = { n = "}" },
          callback = "keymaps.next_chat",
          description = "[Nav] Next interaction",
        },
        previous_chat = {
          modes = { n = "{" },
          callback = "keymaps.previous_chat",
          description = "[Nav] Previous interaction",
        },
      },
    },
  },
})

Options

There are a number of options available for CLI interactions:

require("codecompanion").setup({
  interactions = {
    cli = {
      opts = {
        auto_insert = true, -- Enter insert mode when focusing the CLI terminal
        reload = true, -- Reload buffers when an agent modifies files on disk
      },
    },
  },
})

Option	Type	Default	Description
auto_insert	boolean	true	Automatically enter insert mode when the CLI terminal is focused
reload	boolean	true	Watches the cwd for file changes and runs :checktime to reload buffers

User Interface (UI)

The CLI window inherits its layout from display.chat.window by default. You can override specific options via display.cli.window:

require("codecompanion").setup({
  display = {
    cli = {
      window = {
        layout = "vertical",
        width = 0.4,
        height = 0.6,
        opts = {
          list = false,
        },
      },
    },
  },
})

Any options set in display.cli.window are merged on top of the chat window defaults. This means you only need to specify what you want to change.

You can also pass width and height overrides via the Lua API:

require("codecompanion").cli("fix the tests", {
  width = 0.5,
  height = 0.8,
})