feat: external and TMUX Terminal Provider Support (coder#50)

Author: kenvunz

README.md

@@ -87,7 +87,27 @@ That's it! The plugin will auto-configure everything else.
    - Show diffs with proposed changes
    - Access diagnostics and workspace info
 
-## Key Commands
+## Commands
+
+- `:ClaudeCode [arguments]` - Toggle the Claude Code terminal window (simple show/hide behavior)
+- `:ClaudeCodeFocus [arguments]` - Smart focus/toggle Claude terminal (switches to terminal if not focused, hides if focused)
+- `:ClaudeCodeTmux [arguments]` - Open Claude Code in a tmux pane (works regardless of terminal provider setting)
+- `:ClaudeCode --resume` - Resume a previous Claude conversation
+- `:ClaudeCode --continue` - Continue Claude conversation
+- `:ClaudeCodeSend` - Send current visual selection to Claude, or add files from tree explorer
+- `:ClaudeCodeTreeAdd` - Add selected file(s) from tree explorer to Claude context (also available via ClaudeCodeSend)
+- `:ClaudeCodeAdd <file-path> [start-line] [end-line]` - Add a specific file or directory to Claude context by path with optional line range
+- `:ClaudeCodeDiffAccept` - Accept the current diff changes (equivalent to `<leader>aa`)
+- `:ClaudeCodeDiffDeny` - Deny/reject the current diff changes (equivalent to `<leader>ad`)
+
+### Toggle Behavior
+
+- **`:ClaudeCode`** - Simple toggle: Always show/hide terminal regardless of current focus
+- **`:ClaudeCodeFocus`** - Smart focus: Focus terminal if not active, hide if currently focused
+
+### Tree Integration
+
+The `<leader>as` keybinding has context-aware behavior:
 
 - `:ClaudeCode` - Toggle the Claude Code terminal window
 - `:ClaudeCodeFocus` - Smart focus/toggle Claude terminal
@@ -179,6 +199,7 @@ For deep technical details, see [ARCHITECTURE.md](./ARCHITECTURE.md).
 - **Claude not connecting?** Check `:ClaudeCodeStatus` and verify lock file exists in `~/.claude/ide/` (or `$CLAUDE_CONFIG_DIR/ide/` if `CLAUDE_CONFIG_DIR` is set)
 - **Need debug logs?** Set `log_level = "debug"` in opts
 - **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
 
 ## Contributing
 

lua/claudecode/init.lua

@@ -86,7 +86,7 @@ M.state = {
 ---@alias ClaudeCode.TerminalOpts { \
 ---  split_side?: "left"|"right", \
 ---  split_width_percentage?: number, \
----  provider?: "auto"|"snacks"|"native", \
+---  provider?: "auto"|"snacks"|"native"|"external"|"tmux", \
 ---  show_native_term_exit_tip?: boolean }
 ---
 ---@alias ClaudeCode.SetupOpts { \
@@ -165,9 +165,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
@@ -258,15 +260,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,
@@ -276,11 +280,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
@@ -496,6 +504,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
@@ -921,6 +943,26 @@ function M._create_commands()
     end, {
       desc = "Close the Claude Code terminal window",
     })
+
+    vim.api.nvim_create_user_command("ClaudeCodeTmux", function(opts)
+      local tmux_provider = require("claudecode.terminal.tmux")
+      if not tmux_provider.is_available() then
+        logger.error("command", "ClaudeCodeTmux: Not running in tmux session")
+        return
+      end
+
+      -- Use the normal terminal flow but force tmux provider by calling it directly
+      local cmd_args = opts.args and opts.args ~= "" and opts.args or nil
+
+      local effective_config = { split_side = "right", split_width_percentage = 0.5 }
+      local cmd_string, claude_env_table = terminal.get_claude_command_and_env(cmd_args)
+
+      tmux_provider.setup({})
+      tmux_provider.open(cmd_string, claude_env_table, effective_config, true)
+    end, {
+      nargs = "*",
+      desc = "Open Claude Code in new tmux pane (requires tmux session)",
+    })
   else
     logger.error(
       "init",

lua/claudecode/terminal.lua

@@ -51,7 +51,13 @@ local function get_provider()
   local logger = require("claudecode.logger")
 
   if config.provider == "auto" then
-    -- Try snacks first, then fallback to native silently
+    -- Try tmux first if in tmux session, then snacks, then fallback to native silently
+    local tmux_provider = load_provider("tmux")
+    if tmux_provider and tmux_provider.is_available() then
+      logger.debug("terminal", "Auto-detected tmux session, using tmux provider")
+      return tmux_provider
+    end
+
     local snacks_provider = load_provider("snacks")
     if snacks_provider and snacks_provider.is_available() then
       return snacks_provider
@@ -67,6 +73,22 @@ 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 == "tmux" then
+    local tmux_provider = load_provider("tmux")
+    if tmux_provider and tmux_provider.is_available() then
+      logger.debug("terminal", "Using tmux terminal provider")
+      return tmux_provider
+    else
+      logger.warn("terminal", "'tmux' provider configured, but not in tmux session. Falling back to 'native'.")
+    end
+  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 +226,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" or v == "tmux") then
         config[k] = v
       elseif k == "show_native_term_exit_tip" and type(v) == "boolean" then
         config[k] = v
@@ -286,6 +308,26 @@ 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
+
+--- Checks if the current terminal provider is tmux.
+-- @return boolean True if using tmux terminal provider, false otherwise.
+function M.is_tmux_provider()
+  return config.provider == "tmux"
+end
+
+--- Gets the claude command and environment variables for external use.
+-- @param cmd_args string|nil Optional arguments to append to the command
+-- @return string cmd_string The command string
+-- @return table env_table The environment variables table
+function M.get_claude_command_and_env(cmd_args)
+  return get_claude_command_and_env(cmd_args)
+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.

tests/unit/claudecode_add_command_spec.lua

@@ -90,6 +90,12 @@ 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,
+          is_tmux_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,12 @@ 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,
+      is_tmux_provider = function()
+        return false -- Default to false for existing tests
+      end,
     }
 
     -- Mock server

tests/unit/init_spec.lua

@@ -301,6 +301,12 @@ 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,
+        is_tmux_provider = function()
+          return false -- Default to false for existing tests
+        end,
       }
 
       local original_require = _G.require