feat(chat): add display.chat.window.pertab for tab-local chats

When enabled, chat buffers visible in another tab are not hidden when
opening or cycling chats in the current tab. Cycling via { / } is
scoped to chats that are either visible in the current tab or not
currently visible in any tab, so chats opened in other tabs are never
stolen.

The Toggle command jumps to the existing tab when the chat is open
elsewhere (with a notify) instead of moving the chat. The close keymap
prefers a chat that's already in or available to the current tab when
auto-opening a sibling chat after close. Chats survive tab closure and
fall back into the hidden pool, where they remain cycle-eligible from
any tab.

pertab is mutually exclusive with sticky; if both are enabled, the
sticky autocmd's callback no-ops (a warning is logged at setup) so
the chat does not follow tab switches under pertab semantics.

Includes the bufnr_available_to_current_tab helper to share the
hidden-or-current-tab availability check between cycling and the
close keymap, and extends registry.move with an optional filter so
the chat keymaps can scope cycling to current-tab + hidden entries
without changing CLI cycling behaviour.

Adds tests for:
- chat in another tab survives opening a new chat in the current tab
- close_last_chat skips chats visible in other tabs
- sticky+pertab logs a warning and chat does not follow tab switch
- closing a tab leaves its chat in the hidden pool with registry intact

Author: georgeharker

doc/codecompanion.txt

@@ -1,4 +1,4 @@
-*codecompanion.txt*           For NVIM v0.11          Last change: 2026 May 04
+*codecompanion.txt*           For NVIM v0.11          Last change: 2026 May 05
 
 ==============================================================================
 Table of Contents                            *codecompanion-table-of-contents*
@@ -221,7 +221,7 @@ and blink.cmp <https://github.com/Saghen/blink.cmp>. For the latter, on version
     },
 <
 
-The plugin also supports |codecompanion-usage-chat-buffer-completion| and
+The plugin also supports |codecompanion-usage-chat-buffer--completion| and
 coc.nvim <https://github.com/neoclide/coc.nvim>.
 
 
@@ -314,10 +314,10 @@ SETUP                                    *codecompanion-getting-started-setup*
 CHAT AND INLINE ~
 
 
-  [!NOTE] The adapters that the plugin supports out of the box can be found here
+  [!NOTE] The adapters that the plugin supports out of the box can be found in
+  the built-in adapters directory
   <https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters>.
-  Or, see the user contributed adapters
-  |codecompanion-configuration-adapters-http-community-adapters|.
+  Or, see the |codecompanion-configuration-adapters-http-community-adapters|.
   |codecompanion-configuration-adapters-acp| are only supported for the chat
   interaction.
 The Chat Buffer is where you can converse with an LLM from within a Neovim
@@ -450,7 +450,7 @@ Commands` in the chat buffer.
 **Editor Context**
 
 `Editor Context`, accessed via `#` (by default), contain data about the present
-state of Neovim. You can find a list of available editor context,
+state of Neovim. You can find a
 |codecompanion-usage-chat-buffer-editor-context|. The buffer editor context
 will automatically link a buffer to the chat buffer, by default, updating the
 LLM when the buffer changes.
@@ -469,15 +469,13 @@ You can use them in your prompts like:
   `<C-_>` in insert mode when in the chat buffer. Note: Slash commands should
   also work with coc.nvim.
 `Slash commands`, accessed via `/` (by default), run commands to insert
-additional context into the chat buffer. You can find a list of available
-commands as well as how to use them,
+additional context into the chat buffer. You can find a
 |codecompanion-usage-chat-buffer-slash-commands|.
 
 **Tools**
 
 `Tools`, accessed via `@` (by default), allow the LLM to function as an agent
-and leverage external tools. You can find a list of available tools as well as
-how to use them,
+and leverage external tools. You can find a
 |codecompanion-usage-chat-buffer-agents-tools-available-tools|.
 
 You can use them in your prompts like:
@@ -621,8 +619,9 @@ IN THE CHAT BUFFER ~
   [!NOTE] CodeCompanion enables context management by default
 If you're using the `openai_responses` or `anthropic` adapters, then
 CodeCompanion will use their native server-side compaction capabilities. Please
-see their respective documentation here
-<https://developers.openai.com/api/docs/guides/compaction> and here
+see the OpenAI compaction documentation
+<https://developers.openai.com/api/docs/guides/compaction> and Anthropic
+compaction documentation
 <https://platform.claude.com/docs/en/build-with-claude/compaction> for more
 information.
 
@@ -1415,11 +1414,10 @@ The example below uses the `gemini-api-key` method, pulling the API key from
 
 SETUP: GOOSE CLI ~
 
-To use Goose <https://block.github.io/goose/> in CodeCompanion, ensure you've
-followed their documentation
-<https://block.github.io/goose/docs/getting-started/installation/> to setup and
-install Goose CLI. Then ensure that in your chat buffer you select the `goose`
-adapter.
+To use Goose <https://goose-docs.ai/> in CodeCompanion, ensure you've followed
+their documentation <https://goose-docs.ai/docs/getting-started/installation/>
+to setup and install Goose CLI. Then ensure that in your chat buffer you select
+the `goose` adapter.
 
 
 SETUP: KILO CODE ~
@@ -1600,7 +1598,7 @@ the adapter's URL, headers, parameters and other fields at runtime.
 
 
   [!NOTE] In this `command` example, we're using the 1Password CLI to extract the
-  Gemini API Key. You could also use gpg as outlined here
+  Gemini API Key. You could also use gpg as outlined in this community discussion
   <https://github.com/olimorris/codecompanion.nvim/discussions/601>
 Supported `env` value types: - **Plain environment variable name (string)**: if
 the value is the name of an environment variable that has already been set
@@ -1850,8 +1848,8 @@ Thanks to the community for building the following adapters:
 - Venice.ai <https://github.com/olimorris/codecompanion.nvim/discussions/972>
 - Vertex AI <https://github.com/viespejo/cc-adapter-vertex-ai.nvim>
 
-The section of the discussion forums which is dedicated to user created
-adapters can be found here
+The section of the discussion forums dedicated to user-created adapters can be
+found in the adapter discussions on GitHub
 <https://github.com/olimorris/codecompanion.nvim/discussions?discussions_q=is%3Aopen+label%3A%22tip%3A+adapter%22>.
 Use these individual threads as a place to raise issues and ask questions about
 your specific adapters.
@@ -3589,6 +3587,14 @@ buffer.
 When in a chat buffer, you can cycle between other chat buffers with `{` or
 `}`.
 
+By default, opening or cycling to a chat hides whichever chat is currently
+visible. If you'd rather keep chats per tab — so a chat opened in tab A is
+never closed or stolen by activity in tab B — set `display.chat.window.pertab
+= true` in your config. With that enabled, `{` / `}` only cycles through chats
+that are visible in the current tab or not currently visible anywhere, and
+`:CodeCompanionChat Toggle` jumps to the existing tab when the chat lives
+there.
+
 
 ACTION PALETTE                            *codecompanion-usage-action-palette*
 
@@ -3878,7 +3884,8 @@ HOW THEY WORK ~
 
 Tools make use of an LLM's function calling
 <https://platform.openai.com/docs/guides/function-calling> ability. All tools
-in CodeCompanion follow OpenAI's function calling specification, here
+in CodeCompanion follow OpenAI's function calling specification for defining
+functions
 <https://platform.openai.com/docs/guides/function-calling#defining-functions>.
 
 When a tool is added to the chat buffer, the LLM is instructured by the plugin
@@ -3889,8 +3896,8 @@ which sees tool's added to a queue and sequentially worked with their output
 being shared back to the LLM via the chat buffer. Depending on the tool, flags
 may be inserted on the chat buffer for later processing.
 
-An outline of the architecture can be seen
-|codecompanion-extending-tools-architecture|.
+An outline of the |codecompanion-extending-tools-architecture| is available in
+the extending section.
 
 
 AGENTS / TOOL GROUPS ~
@@ -4283,7 +4290,7 @@ receive up to date information:
 
 Currently, the tool uses tavily <https://www.tavily.com> and you'll need to
 ensure that an API key has been set accordingly, as per the adapter
-<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/adapters/tavily.lua>.
+<https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/adapters/http/tavily.lua>.
 
 
 ADAPTER TOOLS ~
@@ -4874,7 +4881,8 @@ file to share with the LLM. This can be a useful way to minimize token
 consumption whilst sharing the basic outline of a file. The plugin utilizes the
 amazing work from **aerial.nvim** by using their Tree-sitter symbol queries as
 the basis. The list of filetypes that the plugin currently supports can be
-found here <https://github.com/olimorris/codecompanion.nvim/tree/main/queries>.
+found in the Tree-sitter queries directory
+<https://github.com/olimorris/codecompanion.nvim/tree/main/queries>.
 
 The command has native, `Telescope`, `mini.pick`, `fzf.lua` and `snacks.nvim`
 providers available. Also, multiple symbols can be selected and added to the
@@ -5519,7 +5527,7 @@ This guide is intended to serve as a reference for anyone who wishes to
 contribute an adapter to the plugin or understand the inner workings of
 existing adapters.
 
-The plugin's in-built adapters can be found here
+The plugin's in-built adapters can be found in the adapters source directory
 <https://github.com/olimorris/codecompanion.nvim/tree/main/lua/codecompanion/adapters>.
 
 
@@ -6872,7 +6880,7 @@ response from the LLM, identifying the tool and duly executing it.
 There are two types of tools that CodeCompanion can leverage:
 
 1. **Command-based**: These tools can execute a series of commands in the background using `vim.system`. They're non-blocking, meaning you can carry out other activities in Neovim whilst they run. Useful for heavy/time-consuming tasks.
-2. **Function-based**: These tools, like insert_edit_into_file <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/interactions/chat/tools/builtin/insert_edit_into_file.lua>, execute Lua functions directly in Neovim within the main process, one after another. They can also be executed asynchronously.
+2. **Function-based**: These tools, like insert_edit_into_file <https://github.com/olimorris/codecompanion.nvim/blob/main/lua/codecompanion/interactions/chat/tools/builtin/insert_edit_into_file/init.lua>, execute Lua functions directly in Neovim within the main process, one after another. They can also be executed asynchronously.
 
 For the purposes of this section of the guide, we'll be building a simple
 function-based calculator tool that an LLM can use to do basic maths.

doc/configuration/chat-buffer.md

@@ -867,7 +867,8 @@ require("codecompanion").setup({
     chat = {
       window = {
         buflisted = false, -- List the chat buffer in the buffer list?
-        sticky = false, -- Chat window follows when switching tabs
+        sticky = false, -- Chat window follows when switching tabs (ignored when `pertab` is true)
+        pertab = false, -- Each tab has its own chat window? (mutually exclusive with `sticky`)
 
         layout = "vertical", -- float|vertical|horizontal|tab|buffer
         full_height = true, -- for vertical layout

doc/usage/introduction.md

@@ -28,3 +28,5 @@ The `:CodeCompanionChat Toggle` command will automatically create a chat buffer
 
 When in a chat buffer, you can cycle between other chat buffers with `{` or `}`.
 
+By default, opening or cycling to a chat hides whichever chat is currently visible. If you'd rather keep chats per tab — so a chat opened in tab A is never closed or stolen by activity in tab B — set `display.chat.window.pertab = true` in your config. With that enabled, `{` / `}` only cycles through chats that are visible in the current tab or not currently visible anywhere, and `:CodeCompanionChat Toggle` jumps to the existing tab when the chat lives there.
+

lua/codecompanion/config.lua

@@ -1095,7 +1095,11 @@ The user is working on a %s machine. Please respond with system specific command
       -- Window options for the chat buffer
       window = {
         buflisted = false, -- List the chat buffer in the buffer list?
-        sticky = false, -- Chat window follows when switching tabs
+        sticky = false, -- Chat window follows when switching tabs (ignored when `pertab` is true)
+        pertab = false, -- Treat each tab as having its own chat window? Chats opened in
+        -- another tab won't be hidden when opening/cycling chats in the current tab,
+        -- and `{`/`}` cycling is scoped to chats that are either visible in the current
+        -- tab or not currently visible in any tab. Mutually exclusive with `sticky`.
 
         layout = "vertical", -- float|vertical|horizontal|tab|buffer
         full_height = true, -- for vertical layout

lua/codecompanion/init.lua

@@ -524,10 +524,20 @@ CodeCompanion.setup = function(opts)
   end
 
   local window_config = config.display.chat.window
-  if window_config.sticky and window_config.layout ~= "buffer" and window_config.layout ~= "tab" then
+  if window_config.sticky and window_config.pertab then
+    log:warn(
+      "[CodeCompanion] `display.chat.window.sticky` and `display.chat.window.pertab` are mutually exclusive. "
+        .. "Disabling `sticky` because `pertab` makes chats tab-local by design."
+    )
+  elseif window_config.sticky and window_config.layout ~= "buffer" and window_config.layout ~= "tab" then
     api.nvim_create_autocmd("TabEnter", {
       group = api.nvim_create_augroup("codecompanion.sticky_buffer", { clear = true }),
       callback = function(args)
+        -- No-op if pertab has been enabled by a subsequent setup() call.
+        -- pertab and sticky are mutually exclusive; pertab wins.
+        if config.display.chat.window.pertab then
+          return
+        end
         local chat = CodeCompanion.last_chat()
         if chat and chat.ui:is_visible_non_curtab() then
           chat.buffer_context = get_context(args.buf)

lua/codecompanion/interactions/chat/init.lua

@@ -2015,10 +2015,18 @@ function Chat.last_chat()
 end
 
 ---Close the last chat buffer
+---
+---When `display.chat.window.pertab` is enabled, the last chat is left alone if
+---it is currently visible in a tab other than the current one. This prevents
+---opening or cycling a chat in tab A from hiding a chat that the user has
+---explicitly placed in tab B.
 ---@return nil
 function Chat.close_last_chat()
   if last_chat and not vim.tbl_isempty(last_chat) then
     if last_chat.ui:is_visible() then
+      if config.display.chat.window.pertab and last_chat.ui:is_visible_non_curtab() then
+        return
+      end
       last_chat.ui:hide()
     end
   end
@@ -2064,9 +2072,17 @@ function Chat.toggle(args)
 
   -- If the chat is visible in a different tab ...
   if chat.ui:is_visible_non_curtab() then
-    if config.display.chat.window.layout == "tab" then
-      -- ... open it (go there) if chat opens in tabs
-      chat.ui:open()
+    if config.display.chat.window.layout == "tab" or config.display.chat.window.pertab then
+      -- ... jump to it (go there) if chat opens in tabs, or if pertab is enabled
+      -- (in pertab mode we never steal a chat from another tab).
+      local target_tab = api.nvim_win_get_tabpage(chat.ui.winnr)
+      if config.display.chat.window.pertab then
+        utils.notify(
+          fmt("Chat is open in tab %d. Switching tab.", api.nvim_tabpage_get_number(target_tab)),
+          vim.log.levels.INFO
+        )
+      end
+      api.nvim_set_current_tabpage(target_tab)
       return
     else
       -- ... or close it so we can open it below

lua/codecompanion/interactions/chat/keymaps/init.lua

@@ -299,6 +299,48 @@ M.regenerate = {
   end,
 }
 
+---Whether the given buffer is "available" to the current tab \u2014 i.e. either
+---it is not currently displayed in any window, or it is displayed in a window
+---in the current tab. A buffer that is only visible in another tab is NOT
+---available to the current tab. Used in pertab mode to avoid stealing chats
+---from other tabs.
+---@param bufnr number
+---@return boolean
+local function bufnr_available_to_current_tab(bufnr)
+  local wins = vim.fn.win_findbuf(bufnr)
+  if #wins == 0 then
+    return true
+  end
+
+  local current_tab = api.nvim_get_current_tabpage()
+  for _, w in ipairs(wins) do
+    if api.nvim_win_get_tabpage(w) == current_tab then
+      return true
+    end
+  end
+
+  return false
+end
+
+---Build a registry filter for chat cycling.
+---When `display.chat.window.pertab` is enabled, only cycle through chats that
+---are either visible in the current tab or not currently visible in any tab.
+---Chats which are visible in another tab are skipped (and not stolen). Non-
+---chat entries (e.g. CLI buffers) are always allowed.
+---@return fun(entry: CodeCompanion.Registry.Entry): boolean | nil
+local function chat_cycle_filter()
+  if not config.display.chat.window.pertab then
+    return nil
+  end
+
+  return function(entry)
+    if entry.interaction ~= "chat" then
+      return true
+    end
+    return bufnr_available_to_current_tab(entry.bufnr)
+  end
+end
+
 M.close = {
   callback = function(chat)
     chat:close()
@@ -309,7 +351,21 @@ M.close = {
     end
 
     local window_opts = chat.ui.window_opts or { default = true }
-    chats[1].chat.ui:open({ window_opts = window_opts })
+
+    local target = chats[1]
+
+    -- In pertab mode, prefer a chat that isn't already visible in another tab
+    -- so closing one chat doesn't steal a sibling chat from another tab.
+    if config.display.chat.window.pertab then
+      for _, c in ipairs(chats) do
+        if bufnr_available_to_current_tab(c.chat.bufnr) then
+          target = c
+          break
+        end
+      end
+    end
+
+    target.chat.ui:open({ window_opts = window_opts })
   end,
 }
 
@@ -475,14 +531,14 @@ M.buffer_sync_diff = {
 M.next_chat = {
   desc = "Move to the next chat",
   callback = function(chat)
-    require("codecompanion.interactions.shared.registry").move(chat.bufnr, 1)
+    require("codecompanion.interactions.shared.registry").move(chat.bufnr, 1, { filter = chat_cycle_filter() })
   end,
 }
 
 M.previous_chat = {
   desc = "Move to the previous chat",
   callback = function(chat)
-    require("codecompanion.interactions.shared.registry").move(chat.bufnr, -1)
+    require("codecompanion.interactions.shared.registry").move(chat.bufnr, -1, { filter = chat_cycle_filter() })
   end,
 }