Add multiple instance per git root

Author: ahdzib-maya

CLAUDE.md

@@ -26,6 +26,25 @@ Claude Code Plugin provides seamless integration between the Claude Code AI assi
 - Implementing better context synchronization
 - Adding buffer-specific context management
 
+## Multi-Instance Support
+The plugin supports running multiple Claude Code instances, one per git repository root:
+
+- Each git repository maintains its own Claude instance
+- Works across multiple Neovim tabs with different projects
+- Allows working on multiple projects in parallel
+- Configurable via `git.multi_instance` option (defaults to `true`)
+- Instances remain in their own directory context when switching between tabs
+- Buffer names include the git root path for easy identification
+
+Example configuration to disable multi-instance mode:
+```lua
+require('claude-code').setup({
+  git = {
+    multi_instance = false  -- Use a single global Claude instance
+  }
+})
+```
+
 ## Documentation Links
 - Tasks: `/home/gregg/Projects/docs-projects/neovim-ecosystem-docs/tasks/claude-code-tasks.md`
 - Project Status: `/home/gregg/Projects/docs-projects/neovim-ecosystem-docs/project-status.md`

lua/claude-code/config.lua

@@ -25,6 +25,7 @@ local M = {}
 --- ClaudeCodeGit class for git integration configuration
 -- @table ClaudeCodeGit
 -- @field use_git_root boolean Set CWD to git root when opening Claude Code (if in git project)
+-- @field multi_instance boolean Use multiple Claude instances (one per git root)
 
 --- ClaudeCodeKeymapsToggle class for toggle keymap configuration
 -- @table ClaudeCodeKeymapsToggle
@@ -78,6 +79,7 @@ M.default_config = {
   -- Git integration settings
   git = {
     use_git_root = true, -- Set CWD to git root when opening Claude Code (if in git project)
+    multi_instance = true, -- Use multiple Claude instances (one per git root)
   },
   -- Command settings
   command = 'claude', -- Command used to launch Claude Code
@@ -172,6 +174,10 @@ local function validate_config(config)
   if type(config.git.use_git_root) ~= 'boolean' then
     return false, 'git.use_git_root must be a boolean'
   end
+  
+  if type(config.git.multi_instance) ~= 'boolean' then
+    return false, 'git.multi_instance must be a boolean'
+  end
 
   -- Validate command settings
   if type(config.command) ~= 'string' then

lua/claude-code/init.lua

@@ -44,13 +44,25 @@ function M.force_insert_mode()
   terminal.force_insert_mode(M, M.config)
 end
 
+--- Get the current active buffer number
+--- @return number|nil bufnr Current Claude instance buffer number or nil
+local function get_current_buffer_number()
+  -- Get current instance from the instances table
+  local current_instance = M.claude_code.current_instance
+  if current_instance then
+    return M.claude_code.instances[current_instance]
+  end
+  return nil
+end
+
 --- Toggle the Claude Code terminal window
 --- This is a public function used by commands
 function M.toggle()
   terminal.toggle(M, M.config, git)
 
   -- Set up terminal navigation keymaps after toggling
-  if M.claude_code.bufnr and vim.api.nvim_buf_is_valid(M.claude_code.bufnr) then
+  local bufnr = get_current_buffer_number()
+  if bufnr and vim.api.nvim_buf_is_valid(bufnr) then
     keymaps.setup_terminal_navigation(M, M.config)
   end
 end
@@ -73,7 +85,8 @@ function M.toggle_with_variant(variant_name)
   terminal.toggle(M, M.config, git)
 
   -- Set up terminal navigation keymaps after toggling
-  if M.claude_code.bufnr and vim.api.nvim_buf_is_valid(M.claude_code.bufnr) then
+  local bufnr = get_current_buffer_number()
+  if bufnr and vim.api.nvim_buf_is_valid(bufnr) then
     keymaps.setup_terminal_navigation(M, M.config)
   end
 

lua/claude-code/terminal.lua

@@ -8,13 +8,28 @@ local M = {}
 
 --- Terminal buffer and window management
 -- @table ClaudeCodeTerminal
--- @field bufnr number|nil Buffer number of the Claude Code terminal
+-- @field instances table Key-value store of git root to buffer number
 -- @field saved_updatetime number|nil Original updatetime before Claude Code was opened
+-- @field current_instance string|nil Current git root path for active instance
 M.terminal = {
-  bufnr = nil,
+  instances = {},
   saved_updatetime = nil,
+  current_instance = nil,
 }
 
+--- Get the current git root or a fallback identifier
+--- @param git table The git module
+--- @return string identifier Git root path or fallback identifier
+local function get_instance_identifier(git)
+  local git_root = git.get_git_root()
+  if git_root then
+    return git_root
+  else
+    -- Fallback to current working directory if not in a git repo
+    return vim.fn.getcwd()
+  end
+end
+
 --- Create a split window according to the specified position configuration
 --- @param position string Window position configuration
 --- @param config table Plugin configuration containing window settings
@@ -49,8 +64,18 @@ end
 --- @param claude_code table The main plugin module
 --- @param config table The plugin configuration
 function M.force_insert_mode(claude_code, config)
-  local bufnr = claude_code.claude_code.bufnr
-  if bufnr and vim.api.nvim_buf_is_valid(bufnr) and vim.fn.bufnr '%' == bufnr then
+  local current_bufnr = vim.fn.bufnr('%')
+  
+  -- Check if current buffer is any of our Claude instances
+  local is_claude_instance = false
+  for _, bufnr in pairs(claude_code.claude_code.instances) do
+    if bufnr == current_bufnr and vim.api.nvim_buf_is_valid(bufnr) then
+      is_claude_instance = true
+      break
+    end
+  end
+  
+  if is_claude_instance then
     -- Only enter insert mode if we're in the terminal buffer and not already in insert mode
     -- and not configured to stay in normal mode
     if config.window.start_in_normal_mode then
@@ -72,10 +97,22 @@ end
 --- @param config table The plugin configuration
 --- @param git table The git module
 function M.toggle(claude_code, config, git)
-  -- Check if Claude Code is already running
-  local bufnr = claude_code.claude_code.bufnr
+  -- Determine instance ID based on config
+  local instance_id
+  if config.git.multi_instance then
+    -- Use git root or current directory as instance identifier
+    instance_id = get_instance_identifier(git)
+  else
+    -- Use a fixed ID for single instance mode
+    instance_id = "global"
+  end
+  
+  claude_code.claude_code.current_instance = instance_id
+  
+  -- Check if this Claude Code instance is already running
+  local bufnr = claude_code.claude_code.instances[instance_id]
   if bufnr and vim.api.nvim_buf_is_valid(bufnr) then
-    -- Check if there's a window displaying Claude Code buffer
+    -- Check if there's a window displaying this Claude Code buffer
     local win_ids = vim.fn.win_findbuf(bufnr)
     if #win_ids > 0 then
       -- Claude Code is visible, close the window
@@ -93,7 +130,7 @@ function M.toggle(claude_code, config, git)
       end
     end
   else
-    -- Claude Code is not running, start it in a new split
+    -- This Claude Code instance is not running, start it in a new split
     create_split(config.window.position, config)
 
     -- Determine if we should use the git root directory
@@ -108,7 +145,15 @@ function M.toggle(claude_code, config, git)
 
     vim.cmd(cmd)
     vim.cmd 'setlocal bufhidden=hide'
-    vim.cmd 'file claude-code'
+    
+    -- Create a unique buffer name (or a standard one in single instance mode)
+    local buffer_name
+    if config.git.multi_instance then
+      buffer_name = 'claude-code-' .. instance_id:gsub('[/\\\\]', '-')
+    else
+      buffer_name = 'claude-code'
+    end
+    vim.cmd('file ' .. buffer_name)
 
     if config.window.hide_numbers then
       vim.cmd 'setlocal nonumber norelativenumber'
@@ -118,8 +163,8 @@ function M.toggle(claude_code, config, git)
       vim.cmd 'setlocal signcolumn=no'
     end
 
-    -- Store buffer number for future reference
-    claude_code.claude_code.bufnr = vim.fn.bufnr '%'
+    -- Store buffer number for this instance
+    claude_code.claude_code.instances[instance_id] = vim.fn.bufnr('%')
 
     -- Automatically enter insert mode in terminal unless configured to start in normal mode
     if config.window.enter_insert and not config.window.start_in_normal_mode then