Switching AI Plugins - Gentleman.Dots

Overview

Gentleman.Dots includes six AI assistants, but only one should be enabled at a time to avoid keybinding conflicts and unexpected behavior. By default, OpenCode is enabled with the Gentleman agent.

Critical: Only enable ONE AI plugin at a time. Multiple AI plugins can cause:

Conflicting keybindings
Unexpected behavior
Performance issues
Difficulty troubleshooting

Plugin Status Management

All AI plugin states are managed in a single file:

~/.config/nvim/lua/plugins/disabled.lua

This file controls which plugins are loaded when Neovim starts.

Current Default State

The default configuration:

return {
  {
    "yetone/avante.nvim",
    enabled = false,  -- Disabled
  },
  {
    "CopilotC-Nvim/CopilotChat.nvim",
    enabled = false,  -- Disabled
  },
  {
    "NickvanDyke/opencode.nvim",
    enabled = true,   -- ✅ ENABLED
  },
  {
    "olimorris/codecompanion.nvim",
    enabled = false,  -- Disabled
  },
  {
    "coder/claudecode.nvim",
    enabled = false,  -- Disabled
  },
  -- Note: Gemini is not in disabled.lua - managed in its own config
}

OpenCode is the only AI plugin enabled by default. This provides the full Gentleman experience.

How to Switch Plugins

Open the Configuration File

Open the disabled plugins configuration:

nvim ~/.config/nvim/lua/plugins/disabled.lua

Disable Current Plugin

Find the currently enabled plugin (usually OpenCode) and set it to false:

{
  "NickvanDyke/opencode.nvim",
  enabled = false,  -- Changed from true
},

Enable New Plugin

Find the plugin you want to enable and set it to true:

{
  "yetone/avante.nvim",
  enabled = true,   -- Changed from false
},

Save and Restart Neovim

Save the file (:w) and restart Neovim completely:

# Exit Neovim
:qa

# Restart Neovim
nvim

Verify Plugin Loaded

Check that the new plugin loaded successfully:

:Lazy

Look for your enabled plugin in the list (should show as loaded).

Switching Examples

OpenCode → Avante
OpenCode → CopilotChat
OpenCode → Claude Code
OpenCode → CodeCompanion
OpenCode → Gemini

Use case: You want visual diff management and cursor planning mode.

Configuration Changes

{
  "NickvanDyke/opencode.nvim",
  enabled = false,  -- Disable OpenCode
},
{
  "yetone/avante.nvim",
  enabled = true,   -- Enable Avante
},

After Restart

OpenCode keybindings (<leader>a*) will be inactive
Avante sidebar will be available on the left side
Built-in Gentleman system prompt is included

Key Avante Features

Visual diff accept/reject
Cursor planning mode
Sidebar layout (30% width, left side)
Copilot integration with Claude Sonnet 4

Use case: You’re a GitHub Copilot subscriber and want chat capabilities.

Configuration Changes

{
  "NickvanDyke/opencode.nvim",
  enabled = false,  -- Disable OpenCode
},
{
  "CopilotC-Nvim/CopilotChat.nvim",
  enabled = false,  -- Remains disabled (not in disabled.lua)
},

CopilotChat is configured with enabled = false in its own plugin file. You must also edit:

nvim ~/.config/nvim/lua/plugins/copilot-chat.lua

Remove or comment out the entire enabled = false line in that file.

After Restart

CopilotChat commands available (:CopilotChat)
15+ built-in prompts (Explain, Review, Tests, etc.)
Gentleman system prompt included
Horizontal layout

Requirements

GitHub Copilot subscription
Copilot authentication configured

Use case: You want direct Claude integration via CLI.

Prerequisites

Install Claude Code CLI:

curl -fsSL https://claude.ai/install.sh | bash

Configuration Changes

{
  "NickvanDyke/opencode.nvim",
  enabled = false,  -- Disable OpenCode
},
{
  "coder/claudecode.nvim",
  enabled = true,   -- Enable Claude Code
},

After Restart

Claude Code terminal split (left side, 30%)
Keybindings: <leader>ac (toggle), <leader>ar (resume)
Diff accept/deny: <leader>aa, <leader>ad
Model selection: <leader>am

Key Features

Native Claude integration
Terminal-based interaction
Snacks provider for UI
Direct access to Claude models

Use case: You want flexibility across multiple AI providers.

Configuration Changes

{
  "NickvanDyke/opencode.nvim",
  enabled = false,  -- Disable OpenCode
},
{
  "olimorris/codecompanion.nvim",
  enabled = true,   -- Enable CodeCompanion
},

After Restart

:CodeCompanion commands available
Keybindings: <leader>ac (chat), <leader>aa (actions)
Multiple adapters: Copilot, GPT-4o, GPT-4.1, Gemini 2.5 Pro
Custom “gentleman” tool group included

Key Features

Multi-provider support
Inline diff mode
Custom slash commands (e.g., /git_files)
Tool-based agents (command runner, editor, files)
Gentleman system prompt included

Use case: You want to use Google Gemini models.

Prerequisites

Install Gemini CLI:

brew install gemini-cli

Configuration Changes

{
  "NickvanDyke/opencode.nvim",
  enabled = false,  -- Disable OpenCode
},

Then enable Gemini in its own config file:

nvim ~/.config/nvim/lua/plugins/gemini.lua

Gemini has minimal configuration and doesn’t conflict if enabled alongside others, but for consistency, disable all other AI plugins.

After Restart

Gemini commands available via gemini-cli
Simple integration
Direct access to Google Gemini models

Comparison Table

Plugin	Default	Keybind Prefix	Layout	Special Requirements
OpenCode	✅ Enabled	`<leader>a`	Left sidebar	OpenCode CLI
Avante	Disabled	Varies	Left sidebar (30%)	Build from source
CopilotChat	Disabled	Chat commands	Horizontal	GitHub Copilot subscription
CodeCompanion	Disabled	`<leader>a`	Left chat	None (multiple providers)
Claude Code	Disabled	`<leader>a`	Left terminal (30%)	Claude Code CLI
Gemini	Disabled	Via CLI	N/A	Gemini CLI

Keybinding Conflicts

Many plugins use similar keybinding prefixes. Here’s what to watch for:

<leader>a Prefix ConflictsOpenCode, CodeCompanion, and Claude Code all use <leader>a as their primary prefix. Enabling multiple will cause conflicts.

Keybinding Overview

Plugin	Toggle	Chat	Actions	Other
OpenCode	`<leader>aa`	`<leader>ai`	Built-in prompts	`<leader>as` (select)
Avante	Custom	Sidebar	Visual diffs	Auto-opens
CopilotChat	N/A	`:CopilotChat`	N/A	Various commands
CodeCompanion	N/A	`<leader>ac`	`<leader>aa`	`<leader>ae` (explain)
Claude Code	`<leader>ac`	N/A	`<leader>aa` (accept)	`<leader>ar` (resume)
Gemini	Via CLI	Via CLI	Via CLI	External tool

If you frequently switch between plugins, consider customizing keybindings in each plugin’s config file to avoid relearning shortcuts.

Verifying the Switch

Check Loaded Plugins

After restarting Neovim, verify with Lazy:

:Lazy

Look for your enabled plugin. It should show as loaded (not lazy-loaded or disabled).

Test Keybindings

Try a keybinding specific to the new plugin:

Avante: Visual select code, check for Avante sidebar
CopilotChat: Run :CopilotChat
CodeCompanion: Run :CodeCompanion
Claude Code: Press <leader>ac
Gemini: Run gemini-cli in terminal

Verify Old Plugin Disabled

Ensure the previous plugin isn’t loaded:

:Lazy

The disabled plugin should show as not loaded.

Switching Back to OpenCode

To return to the default Gentleman experience:

-- In ~/.config/nvim/lua/plugins/disabled.lua
return {
  {
    "yetone/avante.nvim",
    enabled = false,
  },
  {
    "CopilotC-Nvim/CopilotChat.nvim",
    enabled = false,
  },
  {
    "NickvanDyke/opencode.nvim",
    enabled = true,   -- ✅ Back to default
  },
  {
    "olimorris/codecompanion.nvim",
    enabled = false,
  },
  {
    "coder/claudecode.nvim",
    enabled = false,
  },
}

Restart Neovim. OpenCode will be available with the Gentleman agent.

CLI Tool Requirements

Some plugins require external CLI tools:

OpenCode

# Install OpenCode CLI
curl -fsSL https://opencode.ai/install | bash

# Verify installation
which opencode

# Modern CLI tools (used by Gentleman agent)
brew install bat ripgrep fd sd eza

Claude Code

# Install Claude Code CLI
curl -fsSL https://claude.ai/install.sh | bash

# Verify installation
which claudecode

Gemini

# Install Gemini CLI
brew install gemini-cli

# Verify installation
which gemini

CopilotChat

Requires GitHub Copilot subscription.No additional CLI tools needed, but you must have:

Active GitHub Copilot subscription
Authenticated Copilot in Neovim

Avante

No external CLI required, but may need to build from source:

# On Linux/Mac (automatic)
# The plugin builds automatically with `make`

# On Windows
# Uses PowerShell Build.ps1 script

CodeCompanion

No external CLI required. Uses built-in adapters for various providers:

Copilot (requires GitHub subscription)
GPT-4o/4.1 (requires OpenAI API key)
Gemini 2.5 Pro (requires Google API key)

Troubleshooting

Plugin not loading after switch

Symptoms: New plugin isn’t active after restart.Solutions:

Verify you set enabled = true in disabled.lua
Check plugin-specific config files (some have their own enabled flag)
Run :Lazy sync to ensure plugins are installed
Completely close and restart Neovim (not just :source)
Check for errors: :messages

Both plugins active simultaneously

Symptoms: Keybindings from multiple plugins responding.Solutions:

Verify only ONE plugin has enabled = true in disabled.lua
Check plugin-specific configs (some plugins aren’t in disabled.lua)
Restart Neovim completely
Use :Lazy to confirm only one AI plugin is loaded

Keybindings not working

Symptoms: New plugin’s keybindings don’t respond.Solutions:

Verify plugin is loaded: :Lazy
Check for conflicting mappings: :map <leader>a
Review plugin’s config file for keybinding definitions
Some plugins require triggering (e.g., :CopilotChat first)
Check :messages for errors

Missing CLI tool errors

Symptoms: Errors about missing opencode, claudecode, or gemini.Solutions:Install the required CLI tool:

# For OpenCode
curl -fsSL https://opencode.ai/install | bash

# For Claude Code
curl -fsSL https://claude.ai/install.sh | bash

# For Gemini
brew install gemini-cli

Then restart Neovim.

Build errors with Avante

Symptoms: Avante fails to build on installation.Solutions:

Ensure build tools are installed:

# Linux
sudo apt-get install build-essential

# Mac
xcode-select --install

Try manual build:

cd ~/.local/share/nvim/lazy/avante.nvim
make

Check Avante documentation for platform-specific requirements

Best Practices

Test Before Committing

When switching plugins, test thoroughly before relying on it for production work.

Document Your Choice

Keep a note of which plugin you’re using and why, especially if you switch frequently.

Learn One Deeply

Rather than switching often, pick one AI plugin and learn it deeply for maximum productivity.

Backup Configs

Keep a backup of disabled.lua with different combinations if you experiment frequently.

Recommended Plugin for Different Use Cases

Use Case	Recommended Plugin	Why
Full Gentleman experience	OpenCode	Custom agent, modern CLI tools, MCP integration
Visual diff management	Avante	Cursor planning, visual accept/reject
GitHub Copilot user	CopilotChat	Official integration, 15+ prompts
Multi-provider flexibility	CodeCompanion	Supports Copilot, OpenAI, Gemini
Direct Claude access	Claude Code	Native Claude CLI integration
Google Gemini user	Gemini	Simple Gemini CLI integration

Start with OpenCode (default) to experience the Gentleman approach. Switch to others if you have specific provider requirements or prefer different interaction styles.

Next Steps

AI Overview

Review all available AI integration options

OpenCode Setup

Deep dive into OpenCode configuration

Gentleman Agent

Learn about the Gentleman agent philosophy

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Overview

​Plugin Status Management

​Current Default State

​How to Switch Plugins

​Switching Examples

​Configuration Changes

​After Restart

​Key Avante Features

​Configuration Changes

​After Restart

​Requirements

​Prerequisites

​Configuration Changes

​After Restart

​Key Features

​Configuration Changes

​After Restart

​Key Features

​Prerequisites

​Configuration Changes

​After Restart

​Comparison Table

​Keybinding Conflicts

​Keybinding Overview

​Verifying the Switch

​Switching Back to OpenCode

​CLI Tool Requirements

​Troubleshooting

​Best Practices

Test Before Committing

Document Your Choice

Learn One Deeply

Backup Configs

​Recommended Plugin for Different Use Cases

​Next Steps

AI Overview

OpenCode Setup

Gentleman Agent

Build docs developers (and LLMs) love

Overview

Plugin Status Management

Current Default State

How to Switch Plugins

Switching Examples

Configuration Changes

After Restart

Key Avante Features

Configuration Changes

After Restart

Requirements

Prerequisites

Configuration Changes

After Restart

Key Features

Configuration Changes

After Restart

Key Features

Prerequisites

Configuration Changes

After Restart

Comparison Table

Keybinding Conflicts

Keybinding Overview

Verifying the Switch

Switching Back to OpenCode

CLI Tool Requirements

Troubleshooting

Best Practices

Recommended Plugin for Different Use Cases

Next Steps