claude-code.txt

*claude-code.txt*             Seamless integration between Claude Code AI and Neovim

==============================================================================
CONTENTS                                                   *claude-code-contents*

  1. Introduction .......................... |claude-code-introduction|
  2. Installation .......................... |claude-code-installation|
  3. Usage ................................ |claude-code-usage|
  4. Configuration ........................ |claude-code-configuration|
  5. Commands ............................. |claude-code-commands|
  6. Mappings ............................. |claude-code-mappings|
  7. Contributing ......................... |claude-code-contributing|
  8. License .............................. |claude-code-license|

==============================================================================
1. INTRODUCTION                                        *claude-code-introduction*

Claude Code is a plugin that provides seamless integration between the Claude
Code AI assistant (command-line tool) and Neovim. It allows you to:

- Toggle Claude Code in a terminal window at the bottom of your Neovim screen
- Automatically detect and reload files modified by Claude Code
- Keep your Neovim buffers in sync with any changes made by Claude

NOTE: This plugin requires the official Claude Code CLI tool to be installed
and available in your system's PATH.

==============================================================================
2. INSTALLATION                                        *claude-code-installation*

Install using your favorite plugin manager:

Using lazy.nvim:
>lua
  return {
    "greggh/claude-code.nvim",
    dependencies = {
      "nvim-lua/plenary.nvim", -- Required for git operations
    },
    config = function()
      require("claude-code").setup()
    end
  }
<

Using vim-plug:
>vim
  Plug 'nvim-lua/plenary.nvim'
  Plug 'greggh/claude-code.nvim'
  " After installing, add this to your init.vim:
  " lua require('claude-code').setup()
<

Using packer.nvim:
>lua
  use {
    'greggh/claude-code.nvim',
    requires = {
      'nvim-lua/plenary.nvim', -- Required for git operations
    },
    config = function()
      require('claude-code').setup()
    end
  }
<

PREREQUISITES:
- Neovim 0.7.0 or later
- Claude Code CLI tool (https://github.com/anthropics/claude-code)
- plenary.nvim plugin (https://github.com/nvim-lua/plenary.nvim) for git operations

==============================================================================
3. USAGE                                                    *claude-code-usage*

- Use the `:ClaudeCode` command to toggle the Claude Code terminal window
- Press <leader>ac in normal mode to toggle Claude Code terminal window
- Press <C-o> in the terminal to close the Claude Code window
- When Claude Code modifies files that are open in Neovim, they'll be
  automatically reloaded
- When in a git repository, Claude Code will automatically use the git root
  directory as its working directory using pushd/popd commands (configurable)

==============================================================================
4. CONFIGURATION                                    *claude-code-configuration*

Configure the plugin by passing a table to the setup function. Below is the
default configuration:

>lua
  require("claude-code").setup({
    -- Terminal window settings
    window = {
      split_ratio = 0.3,      -- Percentage of screen for the terminal window (height or width)
      position = "botright",  -- Position of the window: "botright", "topleft", "vertical", "vsplit", etc.
      enter_insert = true,    -- Whether to enter insert mode when opening Claude Code
      start_in_normal_mode = false, -- Whether to start in normal mode instead of insert mode
      hide_numbers = true,    -- Hide line numbers in the terminal window
      hide_signcolumn = true, -- Hide the sign column in the terminal window
    },
    -- 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)
    },
    -- Command settings
    command = "claude",        -- Command used to launch Claude Code (do not include --cwd)
    -- 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
    keymaps = {
      toggle = {
        normal = "<leader>ac",  -- Normal mode keymap for toggling Claude Code
        terminal = "<C-o>",     -- Terminal mode keymap for toggling Claude Code
        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
        },
      }
    }
  })
<

==============================================================================
5. COMMANDS                                                *claude-code-commands*

:ClaudeCode                                                       *:ClaudeCode*
    Toggle the Claude Code terminal window.

Conversation Management Commands:
:ClaudeCodeContinue                                           *:ClaudeCodeContinue*
    Toggle Claude Code with the --continue flag to resume the most recent conversation.

:ClaudeCodeResume                                             *:ClaudeCodeResume*
    Toggle Claude Code with the --resume flag to display an interactive conversation picker.

Output Options Commands:
:ClaudeCodeVerbose                                           *:ClaudeCodeVerbose*
    Toggle Claude Code with the --verbose flag for full turn-by-turn output.

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

==============================================================================
6. MAPPINGS                                                *claude-code-mappings*

Default key mappings:

  <leader>ac   Toggle Claude Code terminal window (normal mode)
  <C-.>        Toggle Claude Code terminal window (both normal and terminal modes)
  
Variant mode mappings (if configured):

  <leader>cC   Toggle Claude Code with --continue flag
  <leader>cV   Toggle Claude Code with --verbose flag

Additionally, when in the Claude Code 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.

You can customize these mappings in the configuration.

==============================================================================
7. CONTRIBUTING                                          *claude-code-contributing*

Contributions to Claude Code are welcome! If you would like to contribute,
please check the CONTRIBUTING.md file in the repository for guidelines:
https://github.com/greggh/claude-code.nvim/blob/main/CONTRIBUTING.md

==============================================================================
8. LICENSE                                                  *claude-code-license*

MIT License

 vim:tw=78:ts=8:ft=help:norl: