OpenCode Configuration

Overview

OpenCode is the default AI assistant in Gentleman.Dots, featuring a custom Gentleman agent configuration. It’s installed automatically with the setup script and includes a custom theme, modern CLI tools integration, and MCP support.

OpenCode is enabled by default in ~/.config/nvim/lua/plugins/disabled.lua. All other AI plugins are disabled to avoid conflicts.

Installation

OpenCode is automatically installed by the Gentleman.Dots setup script:

# Installed automatically during setup
curl -fsSL https://opencode.ai/install | bash

The configuration is located at:

~/.config/opencode/opencode.json

Neovim Configuration

The OpenCode Neovim plugin is configured in ~/.config/nvim/lua/plugins/opencode.lua:

Keybindings

Primary Commands

Key	Mode	Description
`<leader>aa`	Normal	Toggle OpenCode sidebar
`<leader>as`	Normal, Visual	Submit selected code to OpenCode
`<leader>ai`	Normal, Visual	Ask OpenCode a question
`<leader>aI`	Normal, Visual	Ask with current buffer context (`@this:`)
`<leader>ab`	Normal, Visual	Ask about current file (`@file`)
`<leader>ap`	Normal, Visual	Send custom prompt with context

Built-in Prompts

Key	Prompt	Description
`<leader>ape`	explain	Explain selected code
`<leader>apf`	fix	Fix issues in selected code
`<leader>apd`	diagnose	Diagnose problems
`<leader>apr`	review	Review code for best practices
`<leader>apt`	test	Generate unit tests
`<leader>apo`	optimize	Optimize performance

Window Configuration

vim.g.opencode_opts = {
  provider = {
    snacks = {
      win = {
        position = "left",  -- Sidebar on left side
      },
    },
  },
}

The autoread option is automatically enabled to detect external file changes from OpenCode operations.

OpenCode Configuration File

The main configuration is stored in ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "theme": "gentleman",
  "autoupdate": true,
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  },
  "agent": {
    "gentleman": {
      "mode": "primary",
      "description": "Reviews code for best practices and potential issues as the Gentleman",
      "prompt": "You are a Senior Architect with 15+ years of experience...",
      "tools": {
        "write": true,
        "edit": true
      }
    }
  }
}

Configuration Options

Option	Description	Default
`theme`	OpenCode UI theme	`gentleman`
`autoupdate`	Automatically update OpenCode CLI	`true`
`mcp`	Model Context Protocol integrations	See below
`agent`	Custom agent configurations	See below
`model`	Default LLM model	OpenCode default

MCP Integration

Model Context Protocol (MCP) enhances OpenCode’s ability to fetch up-to-date documentation:

{
  "mcp": {
    "context7": {
      "type": "remote",
      "url": "https://mcp.context7.com/mcp",
      "enabled": true
    }
  }
}

Context7 MCP

Provides real-time access to documentation, allowing the Gentleman agent to verify claims with current information.

Gentleman Theme

The custom Gentleman theme features:

Dark background for comfortable long coding sessions
Kanagawa-inspired colors matching the Neovim theme
Clean typography optimized for code readability
Consistent visual language with the rest of the configuration

The theme is automatically applied when you run OpenCode. No additional configuration needed.

Model Configuration

You can specify a default model or per-agent model:

Global Model
Per-Agent Model

{
  "$schema": "https://opencode.ai/config.json",
  "model": "anthropic/claude-sonnet-4-20250514",
  "agent": {
    "gentleman": {
      ...
    }
  }
}

{
  "agent": {
    "gentleman": {
      "model": "anthropic/claude-sonnet-4-20250514",
      "mode": "primary",
      ...
    }
  }
}

Popular Model Options

Provider	Model ID	Best For
Anthropic	`anthropic/claude-sonnet-4-20250514`	General development, reasoning
Anthropic	`anthropic/claude-haiku-4-20250514`	Fast responses, simple tasks
OpenAI	`openai/gpt-4o`	General development
OpenAI	`openai/gpt-4o-mini`	Quick tasks, cost-effective
Google	`google/gemini-2.0-flash`	Fast inference
Google	`google/gemini-2.5-pro-preview-06-05`	Advanced reasoning

The Gentleman agent works best with Claude Sonnet 4 or GPT-4o for nuanced, collaborative interactions.

Using OpenCode

Launch OpenCode

Open your terminal and run:

opencode

Activate the Gentleman Agent

Type /agent and press Enter, then select gentleman from the list.

Start Coding

The Gentleman agent is now active. It will:

Challenge your assumptions
Propose alternatives with tradeoffs
Verify claims before agreeing
Use modern CLI tools (bat, rg, fd, sd, eza)

Neovim Integration Workflow

Open OpenCode Sidebar

Press <leader>aa in Normal mode to toggle the OpenCode sidebar.

Select Code

Visually select code you want to discuss or modify.

Send to OpenCode

Use <leader>as to submit the selection, or use built-in prompts:

<leader>ape - Explain
<leader>apf - Fix
<leader>apr - Review
<leader>apt - Generate tests

Iterate

The Gentleman agent will respond in the sidebar. Continue the conversation or apply changes.

Advanced Usage

Context Management

" Press <leader>aI in Normal or Visual mode
" Automatically includes @this: for current buffer context

Working with Modern CLI Tools

The Gentleman agent prefers modern tools. When asking questions, it will use:

# Instead of cat
bat file.ts

# Instead of grep
rg 'pattern' --type ts

# Instead of find
fd '*.tsx' src/

# Instead of sed
sd 'old' 'new' file.ts

# Instead of ls
eza -la

If a tool is missing, the agent will attempt to install it via Homebrew. Ensure Homebrew is properly configured.

Troubleshooting

OpenCode not found

The OpenCode CLI may not be installed or not in PATH:

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

# Verify installation
which opencode

# Add to PATH if needed (add to shell config)
export PATH="$HOME/.opencode/bin:$PATH"

Gentleman agent not available

The agent configuration may be missing:

# Check if config exists
cat ~/.config/opencode/opencode.json

# If missing, copy from Gentleman.Dots
cp GentlemanOpenCode/opencode.json ~/.config/opencode/

Sidebar doesn't open

Check Neovim configuration:

# Verify plugin is enabled
nvim ~/.config/nvim/lua/plugins/disabled.lua

# Should show:
# "NickvanDyke/opencode.nvim", enabled = true

Modern CLI tools not working

Install missing tools:

brew install bat ripgrep fd sd eza

# Verify installations
bat --version
rg --version
fd --version
sd --version
eza --version

Next Steps

Gentleman Agent

Learn about the agent’s philosophy, personality, and interaction style

Switch AI Plugins

Enable a different AI assistant like Avante or CopilotChat

AI Overview

Explore all available AI integration options

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

Overview

Installation

Neovim Configuration

Keybindings

Window Configuration

OpenCode Configuration File

Configuration Options

MCP Integration

Context7 MCP

Gentleman Theme

Model Configuration

Popular Model Options

Using OpenCode

Neovim Integration Workflow

Advanced Usage

Context Management

Working with Modern CLI Tools

Troubleshooting

Next Steps

Gentleman Agent

Switch AI Plugins

AI Overview

Build docs developers (and LLMs) love

Get Started

Terminal Emulators

Shells

Window Managers

Neovim Configuration

AI Integration

Platform-Specific Guides

Advanced

​Overview

​Installation

​Neovim Configuration

​Keybindings

​Window Configuration

​OpenCode Configuration File

​Configuration Options

​MCP Integration

Context7 MCP

​Gentleman Theme

​Model Configuration

​Popular Model Options

​Using OpenCode

​Neovim Integration Workflow

​Advanced Usage

​Context Management

​Working with Modern CLI Tools

​Troubleshooting

​Next Steps

Gentleman Agent

Switch AI Plugins

AI Overview

Build docs developers (and LLMs) love

Overview

Installation

Neovim Configuration

Keybindings

Window Configuration

OpenCode Configuration File

Configuration Options

MCP Integration

Gentleman Theme

Model Configuration

Popular Model Options

Using OpenCode

Neovim Integration Workflow

Advanced Usage

Context Management

Working with Modern CLI Tools

Troubleshooting

Next Steps