Feature Request: Multi-Session Terminal Support

[jsulopzs]

Feature Request: Multi-Session Terminal Support

Problem

Currently, claudecode.nvim manages a single terminal instance. When working on multiple tasks simultaneously (e.g., one Claude session for refactoring while another handles tests), users must close and reopen sessions or manually manage separate terminals outside the plugin.

This is a common workflow for power users who context-switch between tasks — having multiple Claude Code instances open, each with its own conversation history, and being able to cycle between them without losing state.

Proposed Solution

Support multiple Claude Code terminal sessions that share the same WebSocket server for IDE integration. Each session is an independent Claude CLI process connected via CLAUDE_CODE_SSE_PORT, so diffs, @ mentions, and selection tracking all continue to work.

Core API

-- Session manager tracks ordered list of sessions
M.create(cmd_args?)    -- Create new session, make it active, show float
M.toggle()             -- Hide if visible, show if hidden, create if none
M.show()               -- Show active session's float
M.hide()               -- Hide active session's float
M.next()               -- Cycle to next session
M.prev()               -- Cycle to previous session
M.close_active()       -- Close active session, adjust index
M.is_session_buf(buf)  -- Check if buffer belongs to any session
M.get_count()          -- Number of active sessions

Suggested Keybindings

Key	Action
(existing toggle)	Toggle active session (same UX, backed by session manager)
<leader>ao	Create new Claude session
<leader>ax	Close active session
User-defined	Cycle next/prev session

Window Title Indicator

When multiple sessions exist, the floating window title shows position:

Claude Code [2/3]

Single session shows just Claude Code (no indicator).

Implementation Notes

I've built a working proof-of-concept as an external utility module. Here are the key findings:

Terminal Creation

Each session uses a unique count offset (e.g., 1000 + session_id) to avoid collision with the plugin's singleton terminal:

Snacks.terminal.open(cmd, {
  env = {
    ENABLE_IDE_INTEGRATION = "true",
    FORCE_CODE_TERMINAL = "true",
    CLAUDE_CODE_SSE_PORT = tostring(port),
  },
  count = 1000 + session_id,
  -- ... win opts
})

All sessions share the same WebSocket port from claudecode.server.init.state.port, so IDE integration (diffs, selection tracking, @ mentions) works for all instances.

Critical: bufhidden Must Be "hide"

After creating a session terminal, bufhidden must be set to "hide":

vim.bo[term.buf].bufhidden = "hide"

Without this, closing the floating window (e.g., when cycling to another session) destroys the buffer entirely, killing the Claude CLI process.

Critical: Only Listen for BufWipeout, Not BufDelete

The cleanup autocmd that removes dead sessions must only listen for BufWipeout:

vim.api.nvim_create_autocmd("BufWipeout", { ... })

Do not include BufDelete. Neovim fires BufDelete when buflisted is set to false — which happens routinely for terminal buffers (e.g., via terminal settings autocmds). Listening for BufDelete causes sessions to be incorrectly removed while their buffers are still alive.

Cycling Logic

Cycling hides the current session's float, updates the active index (wrapping at boundaries), syncs any global state, and shows the new session's float:

function M.next()
  if #sessions <= 1 then return end
  M.hide()
  active_index = active_index % #sessions + 1
  sync_globals()
  M.show()
end

Cleanup

Three autocmds handle session cleanup:

• TermClose — process exited (user typed /exit, etc.)
• BufWipeout — buffer destroyed (:bwipeout)
• WinClosed — clear global window reference

When the last session is removed, the next toggle creates a fresh session.

Compatibility

• WebSocket server: Starts independently via auto_start. All Claude CLI instances connect to the same server. Diffs and @ mentions work across all sessions.
• Snacks.terminal: Each session gets a unique count so Snacks tracks them independently.
• Existing autocmds: Auto-hide on WinLeave and BufWinEnter should check is_session_buf() to avoid interfering with session-managed buffers.

Reference Implementation

Working proof-of-concept as a standalone utility module (~200 lines):
https://gist.github.com/jsulopzs/4648f88ad6819258e7f8afa03cacc709

Alternatives Considered

• Tabs with separate terminals: Works but loses the floating window UX and requires manual environment setup for IDE integration.
• tmux/terminal multiplexing: External to Neovim, no integration with the plugin's WebSocket server.

[RasmusN]

Coding limited to only one CC instance is like playing an RTS while only being able to control one unit. We need this.