feat: add tmux terminal provider

Author: Gabor Kajtar

README.md

@@ -86,6 +86,7 @@ That's it! For more configuration options, see [Advanced Setup](#advanced-setup)
 
 - `: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
@@ -365,10 +366,11 @@ For most users, the default configuration is sufficient:
 - **`split_side`**: Which side to open the terminal split (`"left"` or `"right"`)
 - **`split_width_percentage`**: Terminal width as a fraction of screen width (0.1 = 10%, 0.5 = 50%)
 - **`provider`**: Terminal implementation to use:
-  - `"auto"`: Try snacks.nvim, fallback to native
+  - `"auto"`: Try tmux (if in tmux session), then 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)
+  - `"tmux"`: Use tmux panes (requires tmux session)
+  - `"external"`: Use external terminal (e.g., separate terminal window)
 - **`show_native_term_exit_tip`**: Show help text for exiting native terminal
 - **`auto_close`**: Automatically close terminal when commands finish
 
@@ -486,6 +488,45 @@ With this configuration:
 - Run `claude --ide` in your external terminal to connect
 - Use `:ClaudeCodeStatus` to check connection status and get guidance
 
+#### Tmux Integration
+
+If you work with tmux sessions, claudecode.nvim can create tmux panes automatically:
+
+```lua
+{
+  "coder/claudecode.nvim",
+  keys = {
+    { "<leader>a", nil, desc = "AI/Claude Code" },
+    { "<leader>ac", "<cmd>ClaudeCode<cr>", desc = "Toggle Claude" },
+    { "<leader>ct", "<cmd>ClaudeCodeTmux<cr>", desc = "Claude in tmux pane" },
+    { "<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" },
+  },
+  opts = {
+    terminal = {
+      provider = "tmux",      -- Use tmux panes when available
+      split_side = "right",   -- Create panes to the right
+      split_width_percentage = 0.4,  -- 40% of terminal width
+    },
+  },
+}
+```
+
+With tmux integration:
+
+- **Auto-detection**: `provider = "auto"` automatically uses tmux when in tmux sessions
+- **Manual command**: `:ClaudeCodeTmux` creates tmux panes regardless of provider setting
+- **Pane control**: Supports `split_side` ("left"/"right") and `split_width_percentage`
+- **Session persistence**: Tmux panes survive across Neovim restarts
+
 #### Custom Claude Installation
 
 ```lua

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"|"external", \
+---  provider?: "auto"|"snacks"|"native"|"external"|"tmux", \
 ---  show_native_term_exit_tip?: boolean }
 ---
 ---@alias ClaudeCode.SetupOpts { \
@@ -896,6 +896,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,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 == "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
@@ -212,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" or v == "external") 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
@@ -300,6 +314,20 @@ 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.

lua/claudecode/terminal/tmux.lua

@@ -0,0 +1,198 @@
+--- Tmux terminal provider for Claude Code.
+-- This provider creates tmux panes to run Claude Code in external tmux sessions.
+-- @module claudecode.terminal.tmux
+
+--- @type TerminalProvider
+local M = {}
+
+local logger = require("claudecode.logger")
+
+local active_pane_id = nil
+
+local function is_in_tmux()
+  return vim and vim.env and vim.env.TMUX ~= nil
+end
+
+local function get_tmux_pane_width()
+  local handle = io.popen("tmux display-message -p '#{window_width}'")
+  if not handle then
+    return 80
+  end
+  local result = handle:read("*a")
+  handle:close()
+  local cleaned = result and result:gsub("%s+", "") or ""
+  return tonumber(cleaned) or 80
+end
+
+local function calculate_split_size(percentage)
+  if not percentage or percentage <= 0 or percentage >= 1 then
+    return nil
+  end
+
+  local window_width = get_tmux_pane_width()
+  return math.floor(window_width * percentage)
+end
+
+local function build_split_command(cmd_string, env_table, effective_config)
+  local split_cmd = "tmux split-window"
+
+  if effective_config.split_side == "left" then
+    split_cmd = split_cmd .. " -bh"
+  else
+    split_cmd = split_cmd .. " -h"
+  end
+
+  local split_size = calculate_split_size(effective_config.split_width_percentage)
+  if split_size then
+    split_cmd = split_cmd .. " -l " .. split_size
+  end
+
+  -- Add environment variables
+  if env_table then
+    for key, value in pairs(env_table) do
+      split_cmd = split_cmd .. " -e '" .. key .. "=" .. value .. "'"
+    end
+  end
+
+  split_cmd = split_cmd .. " '" .. cmd_string .. "'"
+
+  return split_cmd
+end
+
+local function get_active_pane_id()
+  if not active_pane_id then
+    return nil
+  end
+
+  local handle = io.popen("tmux list-panes -F '#{pane_id}' | grep '" .. active_pane_id .. "'")
+  if not handle then
+    return nil
+  end
+
+  local result = handle:read("*a")
+  handle:close()
+
+  if result and result:gsub("%s+", "") == active_pane_id then
+    return active_pane_id
+  end
+
+  active_pane_id = nil
+  return nil
+end
+
+local function capture_new_pane_id(split_cmd)
+  local full_cmd = split_cmd .. " \\; display-message -p '#{pane_id}'"
+  local handle = io.popen(full_cmd)
+  if not handle then
+    return nil
+  end
+
+  local result = handle:read("*a")
+  handle:close()
+
+  local pane_id = result:gsub("%s+", ""):match("%%(%d+)")
+  return pane_id and ("%" .. pane_id) or nil
+end
+
+function M.setup(term_config)
+  if not is_in_tmux() then
+    logger.warn("terminal", "Tmux provider configured but not running in tmux session")
+    return
+  end
+
+  logger.debug("terminal", "Tmux terminal provider configured")
+end
+
+function M.open(cmd_string, env_table, effective_config, focus)
+  if not is_in_tmux() then
+    logger.error("terminal", "Cannot open tmux pane - not in tmux session")
+    return
+  end
+
+  if get_active_pane_id() then
+    logger.debug("terminal", "Claude tmux pane already exists, focusing existing pane")
+    if focus ~= false then
+      vim.fn.system("tmux select-pane -t " .. active_pane_id)
+    end
+    return
+  end
+
+  local split_cmd = build_split_command(cmd_string, env_table, effective_config)
+  logger.debug("terminal", "Opening tmux pane with command: " .. split_cmd)
+
+  local new_pane_id = capture_new_pane_id(split_cmd)
+  if new_pane_id then
+    active_pane_id = new_pane_id
+    logger.debug("terminal", "Created tmux pane with ID: " .. active_pane_id)
+
+    if focus == false then
+      vim.fn.system("tmux last-pane")
+    end
+  else
+    logger.error("terminal", "Failed to create tmux pane")
+  end
+end
+
+function M.close()
+  local pane_id = get_active_pane_id()
+  if not pane_id then
+    logger.debug("terminal", "No active Claude tmux pane to close")
+    return
+  end
+
+  vim.fn.system("tmux kill-pane -t " .. pane_id)
+  active_pane_id = nil
+  logger.debug("terminal", "Closed tmux pane: " .. pane_id)
+end
+
+function M.simple_toggle(cmd_string, env_table, effective_config)
+  local pane_id = get_active_pane_id()
+  if pane_id then
+    M.close()
+  else
+    M.open(cmd_string, env_table, effective_config, true)
+  end
+end
+
+function M.focus_toggle(cmd_string, env_table, effective_config)
+  local pane_id = get_active_pane_id()
+  if not pane_id then
+    M.open(cmd_string, env_table, effective_config, true)
+    return
+  end
+
+  local handle = io.popen("tmux display-message -p '#{pane_active}'")
+  if not handle then
+    return
+  end
+
+  local is_active = handle:read("*a"):gsub("%s+", "") == "1"
+  handle:close()
+
+  if is_active then
+    M.close()
+  else
+    vim.fn.system("tmux select-pane -t " .. pane_id)
+  end
+end
+
+function M.toggle(cmd_string, env_table, effective_config)
+  M.simple_toggle(cmd_string, env_table, effective_config)
+end
+
+function M.get_active_bufnr()
+  return nil
+end
+
+function M.is_available()
+  return is_in_tmux()
+end
+
+function M._get_terminal_for_test()
+  return {
+    pane_id = active_pane_id,
+    is_in_tmux = is_in_tmux(),
+  }
+end
+
+return M

tests/unit/claudecode_add_command_spec.lua

@@ -93,6 +93,9 @@ describe("ClaudeCodeAdd command", function()
           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

@@ -75,6 +75,9 @@ describe("ClaudeCodeSend Command Range Functionality", function()
       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,9 @@ describe("claudecode.init", function()
         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