Hacktoberfest 2026: the issues maintainers tagged for October, open and beginner-friendly. Browse Hacktoberfest issues

Feature Request: Multi-Session Terminal Support

Open
  • Is something wrong?
#187 1 comment 8 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Stale
Tech stack
lua, neovim
Domain
cli, devtools

Research direction

Start by reading the plugin's terminal integration, claudecode.server.init.state.port, auto_start, and existing WinLeave/BufWinEnter autocmds; compare them with the linked proof-of-concept. Confirm how independent sessions share the WebSocket server, cycle without losing buffers, and clean up on TermClose, BufWipeout, and WinClosed. Done means the proposed API, title indicators, keybinding behavior, and existing single-session UX work together.

Written by the indexing model from the issue text.

Description

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.
Dominant language
Lua
Stars
3.1k
Forks
219
No merged PRs in 30d

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

  • No Dockerfile or Docker Compose file
  • No pull request template
  • No contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from coder/claudecode.nvim

All issues in coder/claudecode.nvim

Similar issues

More Lua issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.