claude-multi.nvim

A multi-session Claude Code terminal manager for Neovim. Manage multiple Claude AI conversations in parallel with a clean, tab-based interface powered by snacks.nvim.

Demo

Features

• Multi-session management: Run multiple Claude Code instances simultaneously
• Tab-based interface: Navigate between sessions with a visual winbar
• Git worktree integration: Run Claude sessions in different worktrees with branch indicators
• Recall integration: Browse and resume previous conversations using the recall CLI
• Flexible layouts: Choose between floating window or sidebar modes
• Built-in commands: User commands like :ClaudeToggle, :ClaudeNew, etc.
• Sensible defaults: Works out of the box with zero configuration

Requirements

• Neovim 0.9+
• snacks.nvim: Terminal window management
• Claude Code CLI: The official Anthropic CLI tool
• recall CLI: (Optional but recommended) For browsing conversation history

Installation

Using lazy.nvim

{
  "mb6611/claude-multi.nvim",
  dependencies = { "folke/snacks.nvim" },
  event = "VeryLazy",
  opts = {},
}

That's it! The plugin includes sensible default keymaps and registers user commands automatically.

Commands

Command	Description
:ClaudeToggle	Toggle Claude panel (opens recall if no sessions)
:ClaudeRecall	Open recall TUI to browse conversation history
:ClaudeNew	Create a new fresh Claude session
:ClaudeNewWorktree	Create a new session in a git worktree
:ClaudeRecallWorktree	Open recall TUI in a git worktree
:ClaudeNext	Navigate to next session
:ClaudePrev	Navigate to previous session
:ClaudeClose	Close current tab/session

Default Keymaps

All keymaps work in both normal and terminal modes.

Key	Action
<leader>cc	Toggle Claude panel
<leader>cr	Open Recall TUI
<leader>cR	Open Recall TUI in worktree
<leader>cn	New session
<leader>cw	New session in worktree
<leader>ch	Previous session
<leader>cl	Next session
<leader>cx	Close tab

Configuration

Default Options

{
  "mb6611/claude-multi.nvim",
  dependencies = { "folke/snacks.nvim" },
  event = "VeryLazy",
  opts = {
    layout = "float",         -- "float" or "sidebar"
    float_width = 0.85,       -- Float mode width (0.0-1.0)
    float_height = 0.85,      -- Float mode height (0.0-1.0)
    sidebar_width = 0.4,      -- Sidebar mode width (0.0-1.0)
    keymaps = {
      toggle = "<leader>cc",
      recall = "<leader>cr",
      recall_worktree = "<leader>cR",
      new_session = "<leader>cn",
      new_worktree = "<leader>cw",
      prev_session = "<leader>ch",
      next_session = "<leader>cl",
      close_tab = "<leader>cx",
    },
  },
}

Customizing Keymaps

Override any keymap or disable it by setting to false:

opts = {
  keymaps = {
    -- Use Alt+h/l for faster navigation
    prev_session = "<M-h>",
    next_session = "<M-l>",
    -- Disable a keymap
    close_tab = false,
  },
}

Layout Modes

Float mode (default):

• Centered floating window
• Rounded borders
• Configurable size

Sidebar mode:

• Right-side vertical split
• Single border
• Full height

Usage

Basic Workflow

1. Open Claude: Press <leader>cc to toggle the Claude panel

   • If no sessions exist, it opens the recall TUI automatically
   • Select a conversation from history or start a new one

2. Create new sessions: Press <leader>cn to spawn a fresh Claude session

   • Each session runs independently
   • Sessions appear as tabs in the winbar

3. Navigate sessions: Use <leader>ch and <leader>cl to move between active sessions

   • Sessions wrap around (after last, goes to first)

4. Close sessions: Press <leader>cx to close the current session

   • Automatically switches to the previous session
   • Panel closes if no sessions remain

Session Indicators

The winbar displays all active sessions with these prefixes:

• [R]: Session resumed from recall history
• [N]: Fresh new session

When a session is running in a worktree, the branch name is shown: Chat 1 [feature-branch]

Active session is highlighted in blue with bold text.

Git Worktree Integration

Work on multiple branches simultaneously with dedicated Claude sessions for each worktree:

1. Create a worktree session: Press <leader>cw to open the worktree picker

   • Select an existing worktree from the list
   • Or type a new branch name to create a new worktree automatically

2. Worktree path convention: New worktrees are created as sibling directories:

   ~/code/my-project/                  # Main repo
   ~/code/my-project-worktrees/
   ├── feature-auth/                   # Worktree for feature/auth branch
   └── bugfix-login/                   # Worktree for bugfix/login branch
   

3. Branch context: Each worktree session runs Claude in that worktree's directory, so Claude has full context of that branch's code state

4. Recall in worktrees: Press <leader>cR to browse conversation history within a specific worktree context

Architecture

lua/claude-multi/
├── init.lua        # Public API, commands, keymaps
├── constants.lua   # Enum values
├── terminal.lua    # Snacks.nvim terminal integration
├── navigation.lua  # Session traversal
├── window.lua      # Window configuration
├── session.lua     # Session creation
├── state.lua       # State management
├── ui.lua          # Winbar rendering
├── picker.lua      # Quick-jump mode
├── git.lua         # Git worktree operations
└── worktree.lua    # Worktree picker and session creation

Why claude-multi.nvim?

When working with Claude Code, you often need to:

• Compare responses from different conversation contexts
• Maintain separate sessions for different tasks
• Resume previous conversations while starting new ones
• Keep your workflow organized without leaving Neovim

This plugin provides a seamless, keyboard-driven interface for managing multiple Claude sessions without the overhead of tmux panes or separate terminal windows.

Credits

Created by mb6611

Powered by:

• snacks.nvim by folke
• Claude Code by Anthropic
• recall by hrishioa

License

MIT License - see LICENSE for details