CLIAgents.nvim

Intergrate CLIAgents(e.g. claude-code,gemini-cli, codex into your Neovim, fork from claude-code.nvim

Features • Requirements • Installation • Configuration • Usage • Contributing • Discussions

This plugin was built entirely with Claude Code in a Neovim terminal, and then inside itself using Claude Code for everything!

Features

• 🚀 Toggle CLIAgents in a terminal window with a single key press
• 📱 Customizable window position and size (including floating windows)
• 🤖 Integration with which-key (if available)
• 📂 Automatically uses git project root as working directory (when available)
• 🧩 Modular and maintainable code structure
• 📋 Type annotations with LuaCATS for better IDE support
• ✅ Configuration validation to prevent errors
• 🧪 Testing framework for reliability

Requirements

• Neovim 0.7.0 or later
• Claude Code CLI tool installed and available in your PATH, or other programs likecodex
• plenary.nvim (dependency for git operations)

See CHANGELOG.md for version history and updates.

Installation

Using lazy.nvim

return {
  "Butterblock233/CLIAgents.nvim",
  dependencies = {
    "nvim-lua/plenary.nvim", -- Required for git operations
  },
  config = function()
    require("claude-code").setup()
  end
}

Using packer.nvim

use {
  'Butterblock233/CLIAgents.nvim',
  requires = {
    'nvim-lua/plenary.nvim', -- Required for git operations
  },
  config = function()
    require('claude-code').setup()
  end
}

Using vim-plug

Plug 'nvim-lua/plenary.nvim'
Plug 'Butterblock233/CLIAgents.nvim'
" After installing, add this to your init.vim:
" lua require('claude-code').setup()

Configuration

The plugin can be configured by passing a table to the setup function. Here's the default configuration:

require("claude-code").setup({
  -- Terminal window settings
  window = {
    split_ratio = 0.3,      -- Percentage of screen for the terminal window (height for horizontal, width for vertical splits)
    position = "botright",  -- Position of the window: "botright", "topleft", "vertical", "float", etc.
    enter_insert = true,    -- Whether to enter insert mode when opening Claude Code
    hide_numbers = true,    -- Hide line numbers in the terminal window
    hide_signcolumn = true, -- Hide the sign column in the terminal window
    
    -- Floating window configuration (only applies when position = "float")
    float = {
      width = "80%",        -- Width: number of columns or percentage string
      height = "80%",       -- Height: number of rows or percentage string
      row = "center",       -- Row position: number, "center", or percentage string
      col = "center",       -- Column position: number, "center", or percentage string
      relative = "editor",  -- Relative to: "editor" or "cursor"
      border = "rounded",   -- Border style: "none", "single", "double", "rounded", "solid", "shadow"
    },
  },
  -- File refresh settings
  refresh = {
    enable = true,           -- Enable file change detection
    updatetime = 100,        -- updatetime when Claude Code is active (milliseconds)
    timer_interval = 1000,   -- How often to check for file changes (milliseconds)
    show_notifications = true, -- Show notification when files are reloaded
  },
  -- Git project settings
  git = {
    use_git_root = true,     -- Set CWD to git root when opening Claude Code (if in git project)
  },
  -- Shell-specific settings
  shell = {
    separator = '&&',        -- Command separator used in shell commands
    pushd_cmd = 'pushd',     -- Command to push directory onto stack (e.g., 'pushd' for bash/zsh, 'enter' for nushell)
    popd_cmd = 'popd',       -- Command to pop directory from stack (e.g., 'popd' for bash/zsh, 'exit' for nushell)
  },
  -- Command settings
  command = "claude",        -- Command used to launch Claude Code
  -- Command variants
  command_variants = {
    -- Conversation management
    continue = "--continue", -- Resume the most recent conversation
    resume = "--resume",     -- Display an interactive conversation picker

    -- Output options
    verbose = "--verbose",   -- Enable verbose logging with full turn-by-turn output
  },
  -- Keymaps
  -- You can also use `vim.keymap.set()` to set keymap
  keymaps = {
    toggle = {
      normal = "<C-,>",       -- Normal mode keymap for toggling Claude Code, false to disable
      terminal = "<C-,>",     -- Terminal mode keymap for toggling Claude Code, false to disable
      variants = {
        continue = "<leader>cC", -- Normal mode keymap for Claude Code with continue flag
        verbose = "<leader>cV",  -- Normal mode keymap for Claude Code with verbose flag
      },
    },
    window_navigation = true, -- Enable window navigation keymaps (<C-h/j/k/l>)
    scrolling = true,         -- Enable scrolling keymaps (<C-f/b>) for page up/down
  }
})

Usage

Quick Start

" In your Vim/Neovim commands or init file:
:CLIAgents

-- Or from Lua:
vim.cmd[[CLIAgents]]

-- Or map to a key:
vim.keymap.set('n', '<leader>cc', '<cmd>CLIAgents<CR>', { desc = 'Toggle CLI Agents' })

Commands

Basic command:

• :CLIAgents - Toggle the CLI Agents terminal window

Conversation management commands:

• :CLIAgentsContinue - Resume the most recent conversation(experimental)
• :CLIAgentsResume - Display an interactive conversation picker

Output options command:

• :CLIAgentsVerbose - Enable verbose logging with full turn-by-turn output

Note: Commands are automatically generated for each entry in your command_variants configuration.

Key Mappings

Default key mappings:

• <leader>ac - Toggle CLI Agents terminal window (normal mode)
• <C-,> - Toggle CLI Agents terminal window (both normal and terminal modes)

Variant mode mappings (if configured):

• <leader>cC - Toggle CLI Agents with --continue flag
• <leader>cV - Toggle CLI Agents with --verbose flag

Additionally, when in the CLI Agents terminal:

• <C-h> - Move to the window on the left
• <C-j> - Move to the window below
• <C-k> - Move to the window above
• <C-l> - Move to the window on the right
• <C-f> - Scroll full-page down
• <C-b> - Scroll full-page up

Note: After scrolling with <C-f> or <C-b>, you'll need to press the i key to re-enter insert mode so you can continue typing to Claude Code.

When CLI Agents modifies files that are open in Neovim, they'll be automatically reloaded.

Floating Window Example

To use CLI Agents in a floating window:

require("claude-code").setup({
  window = {
    position = "float",
    float = {
      width = "90%",      -- Take up 90% of the editor width
      height = "90%",     -- Take up 90% of the editor height
      row = "center",     -- Center vertically
      col = "center",     -- Center horizontally
      relative = "editor",
      border = "double",  -- Use double border style
    },
  },
})

How it Works

This plugin:

1. Creates a terminal buffer running the CLI Agents
2. Sets up autocommands to detect file changes on disk
3. Automatically reloads files when they're modified by CLI Agents
4. Provides convenient keymaps and commands for toggling the terminal
5. Automatically detects git repositories and sets working directory to the git root

Contributing

Contributions are welcome! Please check out our contribution guidelines for details on how to get started.

License

MIT License - See LICENSE for more information.

Development

For a complete guide on setting up a development environment, installing all required tools, and understanding the project structure, please refer to DEVELOPMENT.md.

Development Setup

The project includes comprehensive setup for development:

• Complete installation instructions for all platforms in DEVELOPMENT.md
• Pre-commit hooks for code quality
• Testing framework with 44 comprehensive tests
• Linting and formatting tools
• Weekly dependency updates workflow for Claude CLI and actions

# Run tests
make test

# Check code quality
make lint

# Set up pre-commit hooks
scripts/setup-hooks.sh

# Format code
make format

Community

• GitHub Discussions - Get help, share ideas, and connect with other users
• GitHub Issues - Report bugs or suggest features
• GitHub Pull Requests - Contribute to the project

Acknowledgements

• Claude Code by Anthropic - This plugin was entirely built using Claude Code. Development cost: $5.42 with 17m 12.9s of API time
• Plenary.nvim - Core dependency for testing framework and Git operations
• Semantic Versioning - Versioning standard used in this project
• Contributor Covenant - Code of Conduct standard
• Keep a Changelog - Changelog format
• LuaCATS - Type annotations for better IDE support
• StyLua - Lua code formatter
• Luacheck - Lua static analyzer and linter

---

Made with ❤️ by Gregg Housh