feat: add multi-session terminal support

Add ability to run multiple concurrent Claude Code terminal sessions with
session management, smart ESC handling, and session-aware selection tracking.

New commands:
- ClaudeCodeNew: Create a new terminal session
- ClaudeCodeSessions: Show session picker (supports fzf-lua)
- ClaudeCodeSwitch: Switch to session by number
- ClaudeCodeCloseSession: Close session by number or active session

New features:
- Smart ESC handling: double-tap ESC to exit terminal mode, single ESC
  sends to terminal (configurable via esc_timeout)
- Session-aware selection tracking and message routing
- OSC title handler for capturing terminal title changes
- Configurable terminal keymaps (terminal.keymaps.exit_terminal)

New modules:
- lua/claudecode/session.lua: Session lifecycle management
- lua/claudecode/terminal/osc_handler.lua: Terminal title detection

Author: Snir Turgeman

lua/claudecode/config.lua

@@ -79,6 +79,18 @@ function M.validate(config)
     end
   end
 
+  -- Validate terminal keymaps if present
+  if config.terminal.keymaps then
+    assert(type(config.terminal.keymaps) == "table", "terminal.keymaps must be a table")
+    if config.terminal.keymaps.exit_terminal ~= nil then
+      local exit_type = type(config.terminal.keymaps.exit_terminal)
+      assert(
+        exit_type == "string" or (exit_type == "boolean" and config.terminal.keymaps.exit_terminal == false),
+        "terminal.keymaps.exit_terminal must be a string or false"
+      )
+    end
+  end
+
   local valid_log_levels = { "trace", "debug", "info", "warn", "error" }
   local is_valid_log_level = false
   for _, level in ipairs(valid_log_levels) do

lua/claudecode/init.lua

@@ -1020,6 +1020,68 @@ function M._create_commands()
     end, {
       desc = "Close the Claude Code terminal window",
     })
+
+    -- Multi-session commands
+    vim.api.nvim_create_user_command("ClaudeCodeNew", function(opts)
+      local cmd_args = opts.args and opts.args ~= "" and opts.args or nil
+      local session_id = terminal.open_new_session({}, cmd_args)
+      logger.info("command", "Created new Claude Code session: " .. session_id)
+    end, {
+      nargs = "*",
+      desc = "Create a new Claude Code terminal session",
+    })
+
+    vim.api.nvim_create_user_command("ClaudeCodeSessions", function()
+      M.show_session_picker()
+    end, {
+      desc = "Show Claude Code session picker",
+    })
+
+    vim.api.nvim_create_user_command("ClaudeCodeSwitch", function(opts)
+      local session_index = opts.args and tonumber(opts.args)
+      if not session_index then
+        logger.error("command", "ClaudeCodeSwitch requires a session number")
+        return
+      end
+
+      local sessions = terminal.list_sessions()
+      if session_index < 1 or session_index > #sessions then
+        logger.error("command", "Invalid session number: " .. session_index .. " (have " .. #sessions .. " sessions)")
+        return
+      end
+
+      terminal.switch_to_session(sessions[session_index].id)
+      logger.info("command", "Switched to session " .. session_index)
+    end, {
+      nargs = 1,
+      desc = "Switch to Claude Code session by number",
+    })
+
+    vim.api.nvim_create_user_command("ClaudeCodeCloseSession", function(opts)
+      local session_index = opts.args and opts.args ~= "" and tonumber(opts.args)
+
+      if session_index then
+        local sessions = terminal.list_sessions()
+        if session_index < 1 or session_index > #sessions then
+          logger.error("command", "Invalid session number: " .. session_index .. " (have " .. #sessions .. " sessions)")
+          return
+        end
+        terminal.close_session(sessions[session_index].id)
+        logger.info("command", "Closed session " .. session_index)
+      else
+        -- Close active session
+        local active_id = terminal.get_active_session_id()
+        if active_id then
+          terminal.close_session(active_id)
+          logger.info("command", "Closed active session")
+        else
+          logger.warn("command", "No active session to close")
+        end
+      end
+    end, {
+      nargs = "?",
+      desc = "Close a Claude Code session by number (or active session if no number)",
+    })
   else
     logger.error(
       "init",
@@ -1080,6 +1142,95 @@ M.open_with_model = function(additional_args)
   end)
 end
 
+---Show session picker UI for selecting between active sessions
+function M.show_session_picker()
+  local terminal = require("claudecode.terminal")
+  local sessions = terminal.list_sessions()
+
+  if #sessions == 0 then
+    logger.warn("command", "No active Claude Code sessions")
+    return
+  end
+
+  local active_session_id = terminal.get_active_session_id()
+
+  -- Format session items for display
+  local items = {}
+  for i, session in ipairs(sessions) do
+    local age = math.floor((vim.loop.now() - session.created_at) / 1000 / 60)
+    local age_str
+    if age < 1 then
+      age_str = "just now"
+    elseif age == 1 then
+      age_str = "1 min ago"
+    else
+      age_str = age .. " mins ago"
+    end
+
+    local active_marker = session.id == active_session_id and " (active)" or ""
+    table.insert(items, {
+      index = i,
+      session = session,
+      display = string.format("[%d] %s - %s%s", i, session.name, age_str, active_marker),
+    })
+  end
+
+  -- Try to use available picker (Snacks, fzf-lua, or vim.ui.select)
+  local pick_ok = M._try_picker(items, function(item)
+    if item and item.session then
+      terminal.switch_to_session(item.session.id)
+    end
+  end)
+
+  if not pick_ok then
+    -- Fallback to vim.ui.select
+    vim.ui.select(items, {
+      prompt = "Select Claude Code session:",
+      format_item = function(item)
+        return item.display
+      end,
+    }, function(choice)
+      if choice and choice.session then
+        terminal.switch_to_session(choice.session.id)
+      end
+    end)
+  end
+end
+
+---Try to use an enhanced picker (fzf-lua)
+---@param items table[] Items to pick from
+---@param on_select function Callback when item is selected
+---@return boolean success Whether an enhanced picker was used
+function M._try_picker(items, on_select)
+  -- Try fzf-lua
+  local fzf_ok, fzf = pcall(require, "fzf-lua")
+  if fzf_ok and fzf then
+    local display_items = {}
+    local item_map = {}
+    for _, item in ipairs(items) do
+      table.insert(display_items, item.display)
+      item_map[item.display] = item
+    end
+
+    fzf.fzf_exec(display_items, {
+      prompt = "Claude Sessions> ",
+      actions = {
+        ["default"] = function(selected)
+          if selected and selected[1] then
+            local item = item_map[selected[1]]
+            if item then
+              on_select(item)
+            end
+          end
+        end,
+      },
+    })
+    return true
+  end
+
+  return false
+end
+
 ---Get version information
 ---@return { version: string, major: integer, minor: integer, patch: integer, prerelease: string|nil }
 function M.get_version()

lua/claudecode/selection.lua

@@ -1,8 +1,10 @@
 ---Manages selection tracking and communication with the Claude server.
+---Supports session-aware selection tracking for multi-session environments.
 ---@module 'claudecode.selection'
 local M = {}
 
 local logger = require("claudecode.logger")
+local session_manager = require("claudecode.session")
 local terminal = require("claudecode.terminal")
 
 M.state = {
@@ -236,6 +238,13 @@ function M.update_selection()
 
   if changed then
     M.state.latest_selection = current_selection
+
+    -- Also update the active session's selection state
+    local active_session_id = session_manager.get_active_session_id()
+    if active_session_id then
+      session_manager.update_selection(active_session_id, current_selection)
+    end
+
     if M.server then
       M.send_selection_update(current_selection)
     end
@@ -538,8 +547,18 @@ function M.has_selection_changed(new_selection)
 end
 
 ---Sends the selection update to the Claude server.
+---Uses session-aware sending if available, otherwise broadcasts to all.
 ---@param selection table The selection object to send.
 function M.send_selection_update(selection)
+  -- Try to send to active session first
+  if M.server.send_to_active_session then
+    local sent = M.server.send_to_active_session("selection_changed", selection)
+    if sent then
+      return
+    end
+  end
+
+  -- Fallback to broadcast
   M.server.broadcast("selection_changed", selection)
 end
 
@@ -549,6 +568,28 @@ function M.get_latest_selection()
   return M.state.latest_selection
 end
 
+---Gets the selection for a specific session.
+---@param session_id string The session ID
+---@return table|nil The selection object for the session, or nil if none recorded.
+function M.get_session_selection(session_id)
+  return session_manager.get_selection(session_id)
+end
+
+---Gets the selection for the active session.
+---Falls back to global latest_selection if no session-specific selection.
+---@return table|nil The selection object, or nil if none recorded.
+function M.get_active_session_selection()
+  local active_session_id = session_manager.get_active_session_id()
+  if active_session_id then
+    local session_selection = session_manager.get_selection(active_session_id)
+    if session_selection then
+      return session_selection
+    end
+  end
+  -- Fallback to global selection
+  return M.state.latest_selection
+end
+
 ---Sends the current selection to Claude.
 ---This function is typically invoked by a user command. It forces an immediate
 ---update and sends the latest selection.

lua/claudecode/server/init.lua

@@ -1,6 +1,7 @@
 ---@brief WebSocket server for Claude Code Neovim integration
 local claudecode_main = require("claudecode") -- Added for version access
 local logger = require("claudecode.logger")
+local session_manager = require("claudecode.session")
 local tcp_server = require("claudecode.server.tcp")
 local tools = require("claudecode.tools.init") -- Added: Require the tools module
 
@@ -62,6 +63,16 @@ function M.start(config, auth_token)
         logger.debug("server", "WebSocket client connected (no auth):", client.id)
       end
 
+      -- Try to bind client to an available session (active session or first unbound session)
+      local active_session_id = session_manager.get_active_session_id()
+      if active_session_id then
+        local active_session = session_manager.get_session(active_session_id)
+        if active_session and not active_session.client_id then
+          session_manager.bind_client(active_session_id, client.id)
+          logger.debug("server", "Bound client", client.id, "to active session", active_session_id)
+        end
+      end
+
       -- Notify main module about new connection for queue processing
       local main_module = require("claudecode")
       if main_module.process_mention_queue then
@@ -71,6 +82,9 @@ function M.start(config, auth_token)
       end
     end,
     on_disconnect = function(client, code, reason)
+      -- Unbind client from session before removing
+      session_manager.unbind_client(client.id)
+
       M.state.clients[client.id] = nil
       logger.debug(
         "server",
@@ -402,6 +416,65 @@ function M.broadcast(method, params)
   return true
 end
 
+---Send a message to a specific session's bound client
+---@param session_id string The session ID
+---@param method string The method name
+---@param params table|nil The parameters to send
+---@return boolean success Whether message was sent successfully
+function M.send_to_session(session_id, method, params)
+  if not M.state.server then
+    return false
+  end
+
+  local session = session_manager.get_session(session_id)
+  if not session or not session.client_id then
+    logger.debug("server", "Cannot send to session", session_id, "- no bound client")
+    return false
+  end
+
+  local client = M.state.clients[session.client_id]
+  if not client then
+    logger.debug("server", "Cannot send to session", session_id, "- client not found")
+    return false
+  end
+
+  return M.send(client, method, params)
+end
+
+---Send a message to the active session's bound client
+---@param method string The method name
+---@param params table|nil The parameters to send
+---@return boolean success Whether message was sent successfully
+function M.send_to_active_session(method, params)
+  local active_session_id = session_manager.get_active_session_id()
+  if not active_session_id then
+    -- Fallback to broadcast if no active session
+    logger.debug("server", "No active session, falling back to broadcast")
+    return M.broadcast(method, params)
+  end
+
+  return M.send_to_session(active_session_id, method, params)
+end
+
+---Get the session ID for a client
+---@param client_id string The client ID
+---@return string|nil session_id The session ID or nil
+function M.get_client_session(client_id)
+  local session = session_manager.find_session_by_client(client_id)
+  if session then
+    return session.id
+  end
+  return nil
+end
+
+---Bind a client to a session
+---@param client_id string The client ID
+---@param session_id string The session ID
+---@return boolean success Whether binding was successful
+function M.bind_client_to_session(client_id, session_id)
+  return session_manager.bind_client(session_id, client_id)
+end
+
 ---Get server status information
 ---@return table status Server status information
 function M.get_status()