feat: external and TMUX Terminal Provider Support

[gaborkajtar]

External and TMUX Terminal Provider Support

This PR introduces two new terminal providers, expanding claudecode.nvim's flexibility for different development environments.

🚀 New Features

1. External Terminal Provider

What: Added a no-op terminal provider for users who prefer running Claude Code in external terminals.

Key capabilities:

• Zero terminal management: All terminal operations are no-ops that log debug messages
• Always available: No dependency checks, works in any environment
• Server-only mode: Focuses purely on MCP server functionality
• Auto-start support: When configured with event = "VeryLazy", starts MCP server automatically

Use cases:

• Users with custom terminal setups (tmux, kitty, separate windows)
• Server-only deployments where terminal management isn't needed
• Complex workflows requiring external terminal control

Configuration:

{
  "coder/claudecode.nvim", 
  event = "VeryLazy",  -- Auto-start the MCP server
  opts = {
    terminal = {
      provider = "external",  -- No internal terminal management
    },
  },
}

2. Tmux Terminal Provider

What: Added native tmux integration that creates and manages tmux panes for Claude Code sessions.

Key capabilities:

• Smart pane creation: Creates tmux panes with configurable positioning and sizing
• Width calculation: Dynamically calculates split sizes based on current window width
• Environment isolation: Properly sets environment variables for Claude discovery
• Session persistence: Tmux panes survive across Neovim restarts
• Flexible configuration: Supports left/right positioning and percentage-based sizing

Technical details:

• Uses tmux split-window with calculated dimensions
• Supports split_side ("left"/"right") and split_width_percentage (0.0-1.0)
• Implements full terminal provider interface with proper cleanup
• Includes comprehensive error handling and logging

Configuration:

opts = {
  terminal = {
    provider = "tmux",               -- Use tmux panes
    split_side = "right",            -- Position panes to the right  
    split_width_percentage = 0.4,    -- 40% of window width
  },
}

🔧 Technical Implementation

Provider Architecture

Both providers implement the standardized TerminalProvider interface:

• setup(), open(), close(), toggle() functions
• is_available() capability detection
• get_active_bufnr() for buffer management

Integration Changes

• Main logic (init.lua): Enhanced @mention handling to skip terminal visibility checks for external provider
• Terminal module (terminal.lua): Added provider validation and selection logic
• Status command: Updated to provide specific guidance for external connections

Testing

• Added comprehensive unit tests for tmux provider (tmux_terminal_provider_spec.lua)
• Enhanced existing test suites with new provider support
• All tests maintain 100% coverage requirements

🎯 Provider Selection Logic

The provider = "auto" setting now follows this priority:

1. tmux - If running in tmux session
2. snacks - If folke/snacks.nvim is available
3. native - Neovim's built-in terminal
4. external - Must be explicitly configured

💡 Use Case Examples

Tmux Users:

# Auto-detected when in tmux
:ClaudeCode  # Creates tmux pane automatically

# Manual tmux command (works regardless of provider setting)
:ClaudeCodeTmux

External Terminal Workflows:

1. Configure with event = "VeryLazy" and provider = "external"
2. Neovim auto-starts MCP server on startup
3. Run claude in your preferred external terminal
4. Use :ClaudeCodeStatus for connection guidance

🧪 Testing Coverage

• Unit tests: Complete coverage for tmux provider functionality
• Component tests: Integration with terminal selection logic
• Mock testing: Tmux command execution and environment handling
• Error scenarios: Network failures, tmux unavailability, invalid configurations

[eware-godaddy]

This looks an awesome and useful feature. I personally would prefer using a tmux terminal over the neovim terminal. Do you know what's required for this to be merged in?

[fxrlv]

Thanks for your PR! I tried to use the feature directly from your branch and have one suggestion.
Why have you decided to log "External terminal provider configured - Claude Code commands will not launch internal terminals" at startup? It doesn't seem to be very helpful rather noisy, what do you think?

[AVGVSTVS96]

This looks great, hoping for it to merge soon!

[gaborkajtar]

Thanks for your PR! I tried to use the feature directly from your branch and have one suggestion. Why have you decided to log "External terminal provider configured - Claude Code commands will not launch internal terminals" at startup? It doesn't seem to be very helpful rather noisy, what do you think?

Good catch! I have removed the noisy logs. Thanks!

[ThomasK33]

Hey @gaborkajtar, thanks for opening this PR.

Observing this and other PRs and issues, adding a terminal provider that results in noops makes sense. I prefer to name such a provider none, since external implies that something outside provides terminals, which is not the case.

Regarding the tmux provider, while I am personally a tmux user, I prefer not to incorporate this provider into the main codebase. There are several reasons for this.

1. It seems strange that a Neovim extension would start opening and closing my panes, potentially closing the wrong one and closing my Neovim session with unsaved changes in buffers.
2. If we were to merge tmux, someone would likely want integrations for zellij, kitty, Ghostty, etc., which would add many new code paths and make it more challenging to validate new releases and debug issues that arise.

Though I see the advantage of using "real" terminals and panes instead of neovim terminal buffers, I prefer not to completely dismiss this provider. Instead, please refactor it into a custom terminal provider, so we can update the readme to include this tmux provider as a custom option in a collapsible. This would be easy to copy and paste, and anyone using the tmux provider would understand that A) this provider comes with no guarantees regarding maintenance, and B) any interactions performed by the custom tmux provider are transparent to the user.