feat: add external terminal provider

Author: Gabor Kajtar

README.md

@@ -368,6 +368,7 @@ For most users, the default configuration is sufficient:
   - `"auto"`: Try snacks.nvim, fallback to native
   - `"snacks"`: Force snacks.nvim (requires folke/snacks.nvim)
   - `"native"`: Use built-in Neovim terminal
+  - `"external"`: Use external terminal (e.g., tmux, separate terminal window)
 - **`show_native_term_exit_tip`**: Show help text for exiting native terminal
 - **`auto_close`**: Automatically close terminal when commands finish
 
@@ -449,6 +450,42 @@ For most users, the default configuration is sufficient:
 }
 ```
 
+#### External Terminal Configuration
+
+If you prefer to run Claude Code in an external terminal (e.g., tmux, separate terminal window), configure the plugin to use the external provider and load on startup:
+
+```lua
+{
+  "coder/claudecode.nvim",
+  event = "VeryLazy",  -- Load on startup for auto-start behavior
+  opts = {
+    terminal = {
+      provider = "external",  -- Don't launch internal terminals
+    },
+  },
+  keys = {
+    { "<leader>a", nil, desc = "AI/Claude Code" },
+    -- Add any keymaps you want (but they're not required for loading)
+    { "<leader>as", "<cmd>ClaudeCodeSend<cr>", mode = "v", desc = "Send to Claude" },
+    {
+      "<leader>as",
+      "<cmd>ClaudeCodeTreeAdd<cr>",
+      desc = "Add file",
+      ft = { "NvimTree", "neo-tree", "oil" },
+    },
+    -- Diff management
+    { "<leader>aa", "<cmd>ClaudeCodeDiffAccept<cr>", desc = "Accept diff" },
+    { "<leader>ad", "<cmd>ClaudeCodeDiffDeny<cr>", desc = "Deny diff" },
+  },
+}
+```
+
+With this configuration:
+
+- The MCP server starts automatically when Neovim loads
+- Run `claude --ide` in your external terminal to connect
+- Use `:ClaudeCodeStatus` to check connection status and get guidance
+
 #### Custom Claude Installation
 
 ```lua
@@ -483,6 +520,7 @@ For most users, the default configuration is sufficient:
 - **Claude not connecting?** Check `:ClaudeCodeStatus` and verify lock file exists in `~/.claude/ide/`
 - **Need debug logs?** Set `log_level = "debug"` in setup
 - **Terminal issues?** Try `provider = "native"` if using snacks.nvim
+- **Auto-start not working?** If using external terminal provider, ensure you're using `event = "VeryLazy"` instead of `keys = {...}` only, as lazy loading prevents auto-start from running
 
 ## License
 

lua/claudecode/init.lua

@@ -84,7 +84,7 @@ M.state = {
 ---@alias ClaudeCode.TerminalOpts { \
 ---  split_side?: "left"|"right", \
 ---  split_width_percentage?: number, \
----  provider?: "auto"|"snacks"|"native", \
+---  provider?: "auto"|"snacks"|"native"|"external", \
 ---  show_native_term_exit_tip?: boolean }
 ---
 ---@alias ClaudeCode.SetupOpts { \
@@ -163,9 +163,11 @@ function M._process_queued_mentions()
       return
     end
 
-    -- Ensure terminal is visible when processing queued mentions
+    -- Ensure terminal is visible when processing queued mentions (unless using external terminal)
     local terminal = require("claudecode.terminal")
-    terminal.ensure_visible()
+    if not terminal.is_external_provider() then
+      terminal.ensure_visible()
+    end
 
     local success_count = 0
     local total_count = #mentions_to_send
@@ -256,15 +258,17 @@ function M.send_at_mention(file_path, start_line, end_line, context)
 
   -- Check if Claude Code is connected
   if M.is_claude_connected() then
-    -- Claude is connected, send immediately and ensure terminal is visible
+    -- Claude is connected, send immediately and ensure terminal is visible (unless using external terminal)
     local success, error_msg = M._broadcast_at_mention(file_path, start_line, end_line)
     if success then
       local terminal = require("claudecode.terminal")
-      terminal.ensure_visible()
+      if not terminal.is_external_provider() then
+        terminal.ensure_visible()
+      end
     end
     return success, error_msg
   else
-    -- Claude not connected, queue the mention and launch terminal
+    -- Claude not connected, queue the mention and optionally launch terminal
     local mention_data = {
       file_path = file_path,
       start_line = start_line,
@@ -274,11 +278,15 @@ function M.send_at_mention(file_path, start_line, end_line, context)
 
     queue_at_mention(mention_data)
 
-    -- Launch terminal with Claude Code
     local terminal = require("claudecode.terminal")
-    terminal.open()
-
-    logger.debug(context, "Queued @ mention and launched Claude Code: " .. file_path)
+    if terminal.is_external_provider() then
+      -- Don't launch internal terminal - assume external Claude Code instance exists
+      logger.debug(context, "Queued @ mention for external Claude Code instance: " .. file_path)
+    else
+      -- Launch terminal with Claude Code
+      terminal.open()
+      logger.debug(context, "Queued @ mention and launched Claude Code: " .. file_path)
+    end
 
     return true, nil
   end
@@ -449,6 +457,20 @@ function M._create_commands()
   vim.api.nvim_create_user_command("ClaudeCodeStatus", function()
     if M.state.server and M.state.port then
       logger.info("command", "Claude Code integration is running on port " .. tostring(M.state.port))
+
+      -- Check if using external terminal provider and provide guidance
+      local terminal_module_ok, terminal_module = pcall(require, "claudecode.terminal")
+      if terminal_module_ok and terminal_module then
+        if terminal_module.is_external_provider() then
+          local connection_count = M.state.server.get_connection_count and M.state.server.get_connection_count() or 0
+          if connection_count > 0 then
+            logger.info("command", "External Claude Code is connected (" .. connection_count .. " connection(s))")
+          else
+            logger.info("command", "MCP server ready for external Claude Code connections")
+            logger.info("command", "Run 'claude --ide' in your terminal to connect to this Neovim instance")
+          end
+        end
+      end
     else
       logger.info("command", "Claude Code integration is not running")
     end

lua/claudecode/terminal.lua

@@ -67,6 +67,14 @@ local function get_provider()
   elseif config.provider == "native" then
     -- noop, will use native provider as default below
     logger.debug("terminal", "Using native terminal provider")
+  elseif config.provider == "external" then
+    local external_provider = load_provider("external")
+    if external_provider then
+      logger.debug("terminal", "Using external terminal provider")
+      return external_provider
+    else
+      logger.error("terminal", "Failed to load external terminal provider. Falling back to 'native'.")
+    end
   else
     logger.warn("terminal", "Invalid provider configured: " .. tostring(config.provider) .. ". Defaulting to 'native'.")
   end
@@ -204,7 +212,7 @@ function M.setup(user_term_config, p_terminal_cmd)
         config[k] = v
       elseif k == "split_width_percentage" and type(v) == "number" and v > 0 and v < 1 then
         config[k] = v
-      elseif k == "provider" and (v == "snacks" or v == "native") then
+      elseif k == "provider" and (v == "snacks" or v == "native" or v == "external") then
         config[k] = v
       elseif k == "show_native_term_exit_tip" and type(v) == "boolean" then
         config[k] = v
@@ -286,6 +294,12 @@ function M.get_active_terminal_bufnr()
   return get_provider().get_active_bufnr()
 end
 
+--- Checks if the current terminal provider is external.
+-- @return boolean True if using external terminal provider, false otherwise.
+function M.is_external_provider()
+  return config.provider == "external"
+end
+
 --- Gets the managed terminal instance for testing purposes.
 -- NOTE: This function is intended for use in tests to inspect internal state.
 -- The underscore prefix indicates it's not part of the public API for regular use.

lua/claudecode/terminal/external.lua

@@ -0,0 +1,81 @@
+--- External terminal provider for Claude Code.
+-- This provider does nothing - it assumes Claude Code is running in an external terminal.
+-- @module claudecode.terminal.external
+
+--- @type TerminalProvider
+local M = {}
+
+local logger = require("claudecode.logger")
+
+--- Configures the external terminal provider (no-op).
+-- @param term_config table The terminal configuration (ignored).
+function M.setup(term_config)
+  logger.info(
+    "terminal",
+    "External terminal provider configured - Claude Code commands will not launch internal terminals"
+  )
+  logger.debug("terminal", "External provider setup complete - assuming external Claude Code instance will connect")
+end
+
+--- Opens the Claude terminal (no-op for external provider).
+-- @param cmd_string string The command to run (ignored).
+-- @param env_table table Environment variables (ignored).
+-- @param effective_config table Terminal configuration (ignored).
+-- @param focus boolean|nil Whether to focus the terminal (ignored).
+function M.open(cmd_string, env_table, effective_config, focus)
+  logger.debug(
+    "terminal",
+    "External terminal provider: open() called - no action taken (assuming external Claude Code)"
+  )
+end
+
+--- Closes the managed Claude terminal (no-op for external provider).
+function M.close()
+  logger.debug("terminal", "External terminal provider: close() called - no action taken")
+end
+
+--- Simple toggle: show/hide the Claude terminal (no-op for external provider).
+-- @param cmd_string string The command to run (ignored).
+-- @param env_table table Environment variables (ignored).
+-- @param effective_config table Terminal configuration (ignored).
+function M.simple_toggle(cmd_string, env_table, effective_config)
+  logger.debug("terminal", "External terminal provider: simple_toggle() called - no action taken")
+end
+
+--- Smart focus toggle: switches to terminal if not focused, hides if currently focused (no-op for external provider).
+-- @param cmd_string string The command to run (ignored).
+-- @param env_table table Environment variables (ignored).
+-- @param effective_config table Terminal configuration (ignored).
+function M.focus_toggle(cmd_string, env_table, effective_config)
+  logger.debug("terminal", "External terminal provider: focus_toggle() called - no action taken")
+end
+
+--- Toggles the Claude terminal open or closed (no-op for external provider).
+-- @param cmd_string string The command to run (ignored).
+-- @param env_table table Environment variables (ignored).
+-- @param effective_config table Terminal configuration (ignored).
+function M.toggle(cmd_string, env_table, effective_config)
+  logger.debug("terminal", "External terminal provider: toggle() called - no action taken")
+end
+
+--- Gets the buffer number of the currently active Claude Code terminal.
+-- For external provider, this always returns nil since there's no managed terminal.
+-- @return nil Always returns nil for external provider.
+function M.get_active_bufnr()
+  return nil
+end
+
+--- Checks if the external terminal provider is available.
+-- The external provider is always available.
+-- @return boolean Always returns true.
+function M.is_available()
+  return true
+end
+
+--- Gets the managed terminal instance for testing purposes (external provider has none).
+-- @return nil Always returns nil for external provider.
+function M._get_terminal_for_test()
+  return nil
+end
+
+return M

tests/unit/claudecode_add_command_spec.lua

@@ -90,6 +90,9 @@ describe("ClaudeCodeAdd command", function()
             return 1
           end,
           simple_toggle = spy.new(function() end),
+          is_external_provider = function()
+            return false -- Default to false for existing tests
+          end,
         }
       elseif mod == "claudecode.visual_commands" then
         return {

tests/unit/claudecode_send_command_spec.lua

@@ -72,6 +72,9 @@ describe("ClaudeCodeSend Command Range Functionality", function()
     mock_terminal = {
       open = spy.new(function() end),
       ensure_visible = spy.new(function() end),
+      is_external_provider = function()
+        return false -- Default to false for existing tests
+      end,
     }
 
     -- Mock server

tests/unit/external_terminal_provider_spec.lua

@@ -0,0 +1,86 @@
+-- luacheck: globals expect
+require("tests.busted_setup")
+
+describe("External Terminal Provider", function()
+  local external_provider
+  local mock_vim
+  local logger_debug_spy
+
+  local function setup_mocks()
+    -- Mock vim global
+    mock_vim = {
+      notify = spy.new(function() end),
+      log = { levels = { WARN = 2, ERROR = 1, INFO = 3, DEBUG = 4 } },
+    }
+    _G.vim = mock_vim
+
+    -- Mock logger with spy
+    logger_debug_spy = spy.new(function() end)
+    package.loaded["claudecode.logger"] = {
+      debug = logger_debug_spy,
+      warn = function() end,
+      error = function() end,
+      info = function() end,
+    }
+  end
+
+  before_each(function()
+    -- Clear module cache
+    package.loaded["claudecode.terminal.external"] = nil
+
+    setup_mocks()
+    external_provider = require("claudecode.terminal.external")
+  end)
+
+  describe("basic functionality", function()
+    it("should be available", function()
+      expect(external_provider.is_available()).to_be_true()
+    end)
+
+    it("should return nil for active buffer", function()
+      expect(external_provider.get_active_bufnr()).to_be_nil()
+    end)
+
+    it("should return nil for test terminal", function()
+      expect(external_provider._get_terminal_for_test()).to_be_nil()
+    end)
+  end)
+
+  describe("no-op functions", function()
+    it("should do nothing on setup", function()
+      external_provider.setup({ some_config = true })
+      -- Should not error and should log debug message
+      assert.spy(logger_debug_spy).was_called()
+    end)
+
+    it("should do nothing on open", function()
+      external_provider.open("claude --ide", { ENV = "test" }, { split_side = "right" }, true)
+      -- Should not error and should log debug message
+      assert.spy(logger_debug_spy).was_called()
+    end)
+
+    it("should do nothing on close", function()
+      external_provider.close()
+      -- Should not error and should log debug message
+      assert.spy(logger_debug_spy).was_called()
+    end)
+
+    it("should do nothing on simple_toggle", function()
+      external_provider.simple_toggle("claude", {}, {})
+      -- Should not error and should log debug message
+      assert.spy(logger_debug_spy).was_called()
+    end)
+
+    it("should do nothing on focus_toggle", function()
+      external_provider.focus_toggle("claude", {}, {})
+      -- Should not error and should log debug message
+      assert.spy(logger_debug_spy).was_called()
+    end)
+
+    it("should do nothing on toggle", function()
+      external_provider.toggle("claude", {}, {})
+      -- Should not error and should log debug message
+      assert.spy(logger_debug_spy).was_called()
+    end)
+  end)
+end)

tests/unit/init_spec.lua

@@ -298,6 +298,9 @@ describe("claudecode.init", function()
         close = spy.new(function() end),
         setup = spy.new(function() end),
         ensure_visible = spy.new(function() end),
+        is_external_provider = function()
+          return false -- Default to false for existing tests
+        end,
       }
 
       local original_require = _G.require