feat(ui): persist_state window/buffer persistence

When ui.persist_state = true (default), toggle hides windows without
deleting buffers and restores them on next toggle, preserving input
draft content, scroll/cursor position, focused pane, and input_hidden
state.

Three-state window model:
closed → visible → hidden → visible
  ↑___________↓____________↑
   (teardown)   (restore)

Decision engine resolves (status, persist_state, has_display_route, in_tab) → action:

| # | status  | in_tab | persist_state | has_display_route | action         |
|---|---------|--------|---------------|-------------------|----------------|
| 1 | hidden  | any    | true          | any               | restore_hidden |
| 2 | hidden  | any    | false         | any               | close_hidden   |
| 3 | visible | false  | any           | any               | migrate        |
| 4 | visible | true   | any           | true              | close          |
| 5 | visible | true   | false         | any               | close          |
| 6 | visible | true   | true          | false             | hide           |
| 7 | closed  | any    | any           | any               | open           |

Note: Multiple opencode instances across tabs are not currently supported.

Author: jensenojs

README.md

@@ -209,6 +209,7 @@ require('opencode').setup({
     display_context_size = true, -- Display context size in the footer
     display_cost = true, -- Display cost in the footer
     window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder', -- Highlight group for the opencode window
+    persist_state = true, -- Keep buffers when toggling/closing UI so window state restores quickly
     icons = {
       preset = 'nerdfonts', -- 'nerdfonts' | 'text'. Choose UI icon style (default: 'nerdfonts')
       overrides = {}, -- Optional per-key overrides, see section below
@@ -441,6 +442,19 @@ Available icon keys (see implementation at lua/opencode/ui/icons.lua lines 7-29)
 - status_on, status_off
 - border, bullet
 
+### Window Persistence Behavior
+
+`ui.persist_state` controls how `toggle` behaves:
+
+- `persist_state = true` (default): `toggle()` hides/restores the UI and keeps buffers/session view in memory for fast restore.
+- `persist_state = false`: `toggle()` fully tears down UI buffers and recreates them on next open.
+
+Related APIs:
+
+- `require('opencode.api').toggle()` follows the `persist_state` behavior above.
+- `require('opencode.api').close()` always fully closes and clears hidden snapshot state.
+- `require('opencode.api').hide()` preserves buffers only when `persist_state = true`; otherwise it behaves like close.
+
 ### Picker Layout
 
 You can customize the layout of the picker used for history, session, references, and timeline

lua/opencode/api.lua

@@ -48,40 +48,96 @@ function M.close()
     return
   end
 
-  ui.close_windows(state.windows)
+  ui.teardown_visible_windows(state.windows)
+end
+
+function M.hide()
+  ui.hide_visible_windows(state.windows)
 end
 
 function M.paste_image()
   core.paste_image_from_clipboard()
 end
 
---- Check if opencode windows are in the current tab page
---- @return boolean
-local function are_windows_in_current_tab()
-  if not state.windows or not state.windows.output_win then
-    return false
+---@return {status: 'closed'|'hidden'|'visible', position: string, windows: OpencodeWindowState|nil, cursor_positions: {input: integer[]|nil, output: integer[]|nil}}
+function M.get_window_state()
+  return state.get_window_state()
+end
+
+---@param hidden OpencodeHiddenBuffers|nil
+---@return 'input'|'output'
+local function resolve_hidden_focus(hidden)
+  if hidden and (hidden.focused_window == 'input' or hidden.focused_window == 'output') then
+    return hidden.focused_window
   end
 
-  local current_tab = vim.api.nvim_get_current_tabpage()
-  local ok, win_tab = pcall(vim.api.nvim_win_get_tabpage, state.windows.output_win)
-  return ok and win_tab == current_tab
+  if hidden and hidden.input_hidden then
+    return 'output'
+  end
+
+  return 'input'
+end
+
+---@param restore_hidden boolean
+---@return {focus: 'input'|'output', open_action: 'reuse_visible'|'restore_hidden'|'create_fresh'}
+local function build_toggle_open_context(restore_hidden)
+  if restore_hidden then
+    local hidden = state.inspect_hidden_buffers()
+    return {
+      focus = resolve_hidden_focus(hidden),
+      open_action = 'restore_hidden',
+    }
+  end
+
+  local focus = config.ui.input.auto_hide and 'input'
+    or state.last_focused_opencode_window
+    or 'input'
+
+  return {
+    focus = focus,
+    open_action = 'create_fresh',
+  }
 end
 
 M.toggle = Promise.async(function(new_session)
-  -- When auto_hide input is enabled, always focus input; otherwise use last focused
-  local focus = 'input' ---@cast focus 'input' | 'output'
-  if not config.ui.input.auto_hide then
-    focus = state.last_focused_opencode_window or 'input'
+  local decision = state.resolve_toggle_decision(
+    config.ui.persist_state,
+    state.display_route ~= nil
+  )
+  local action = decision.action
+
+  local EARLY_RETURN_ACTIONS = {
+    close = M.close,
+    hide = M.hide,
+    close_hidden = ui.drop_hidden_snapshot,
+  }
+
+  local function open_windows(restore_hidden)
+    local ctx = build_toggle_open_context(restore_hidden == true)
+    return core.open({
+      new_session = new_session == true,
+      focus = ctx.focus,
+      start_insert = false,
+      open_action = ctx.open_action,
+    }):await()
+  end
+
+  local early_return = EARLY_RETURN_ACTIONS[action]
+  if early_return then
+    return early_return()
   end
 
-  if state.windows == nil or not are_windows_in_current_tab() then
+  if action == 'migrate' then
+    -- NOTE: We currently don't support preserving Opencode UI state across tabs.
+    -- If Opencode is visible in a different tab, we tear it down there and recreate it here.
     if state.windows then
-      M.close()
+      ui.teardown_visible_windows(state.windows)
     end
-    core.open({ new_session = new_session == true, focus = focus, start_insert = false }):await()
-  else
-    M.close()
+
+    return open_windows(false)
   end
+
+  return open_windows(action == 'restore_hidden')
 end)
 
 ---@param new_session boolean?
@@ -271,7 +327,7 @@ function M.set_review_breakpoint()
 end
 
 function M.prev_history()
-  if not state.windows then
+  if not state.is_visible() then
     return
   end
   local prev_prompt = history.prev()
@@ -282,7 +338,7 @@ function M.prev_history()
 end
 
 function M.next_history()
-  if not state.windows then
+  if not state.is_visible() then
     return
   end
   local next_prompt = history.next()
@@ -517,7 +573,7 @@ function M.help()
     '|--------------|-------------|',
   }, false)
 
-  if not state.windows or not state.windows.output_win then
+  if not state.is_visible() or not state.windows.output_win then
     return
   end
 
@@ -1051,6 +1107,13 @@ M.commands = {
     end,
   },
 
+  hide = {
+    desc = 'Hide opencode windows (preserve buffers for fast restore)',
+    fn = function(args)
+      M.hide()
+    end,
+  },
+
   cancel = {
     desc = 'Cancel running request',
     fn = M.cancel,

lua/opencode/config.lua

@@ -116,6 +116,7 @@ M.defaults = {
     display_context_size = true,
     display_cost = true,
     window_highlight = 'Normal:OpencodeBackground,FloatBorder:OpencodeBorder',
+    persist_state = true,
     icons = {
       preset = 'nerdfonts',
       overrides = {},

lua/opencode/core.lua

@@ -26,7 +26,7 @@ M.select_session = Promise.async(function(parent_id)
 
   ui.select_session(filtered_sessions, function(selected_session)
     if not selected_session then
-      if state.windows then
+      if state.is_visible() then
         ui.focus_input()
       end
       return
@@ -43,8 +43,8 @@ M.switch_session = Promise.async(function(session_id)
   M.ensure_current_mode():await()
 
   state.active_session = selected_session
-  if state.windows then
-    state.restore_points = {}
+  state.restore_points = {}
+  if state.is_visible() then
     ui.focus_input()
   else
     M.open()
@@ -53,7 +53,7 @@ end)
 
 ---@param opts? OpenOpts
 M.open_if_closed = Promise.async(function(opts)
-  if not state.windows then
+  if not state.is_visible() then
     M.open(opts):await()
   end
 end)
@@ -89,10 +89,28 @@ M.open = Promise.async(function(opts)
     require('opencode.context').load()
   end
 
-  local are_windows_closed = state.windows == nil
+  local open_windows_action = opts.open_action or state.resolve_open_windows_action()
+  local are_windows_closed = open_windows_action ~= 'reuse_visible'
+  local restoring_hidden = open_windows_action == 'restore_hidden'
+
   if are_windows_closed then
+    if not ui.is_opencode_focused() then
+      state.last_code_win_before_opencode = vim.api.nvim_get_current_win()
+      state.current_code_buf = vim.api.nvim_get_current_buf()
+    end
+
     M.is_prompting_allowed()
-    state.windows = ui.create_windows()
+
+    if restoring_hidden then
+      local restored = ui.restore_hidden_windows()
+      if not restored then
+        state.clear_hidden_window_state()
+        restoring_hidden = false
+        state.windows = ui.create_windows()
+      end
+    else
+      state.windows = ui.create_windows()
+    end
   end
 
   if opts.focus == 'input' then
@@ -122,13 +140,14 @@ M.open = Promise.async(function(opts)
       log.debug('Created new session on open', { session = state.active_session.id })
     else
       M.ensure_current_mode():await()
+
       if not state.active_session then
         state.active_session = session.get_last_workspace_session():await()
         if not state.active_session then
           state.active_session = M.create_new_session():await()
         end
       else
-        if not state.display_route and are_windows_closed then
+        if not state.display_route and are_windows_closed and not restoring_hidden then
           -- We're not displaying /help or something like that but we have an active session
           -- and the windows were closed so we need to do a full refresh. This mostly happens
           -- when opening the window after having closed it since we're not currently clearing
@@ -268,7 +287,7 @@ end
 function M.configure_provider()
   require('opencode.model_picker').select(function(selection)
     if not selection then
-      if state.windows then
+      if state.is_visible() then
         ui.focus_input()
       end
       return
@@ -282,7 +301,7 @@ function M.configure_provider()
       state.user_mode_model_map = mode_map
     end
 
-    if state.windows then
+    if state.is_visible() then
       ui.focus_input()
     else
       vim.notify('Changed provider to ' .. model_str, vim.log.levels.INFO)
@@ -293,15 +312,15 @@ end
 function M.configure_variant()
   require('opencode.variant_picker').select(function(selection)
     if not selection then
-      if state.windows then
+      if state.is_visible() then
         ui.focus_input()
       end
       return
     end
 
     state.current_variant = selection.name
 
-    if state.windows then
+    if state.is_visible() then
       ui.focus_input()
     else
       vim.notify('Changed variant to ' .. selection.name, vim.log.levels.INFO)
@@ -366,41 +385,42 @@ M.cycle_variant = Promise.async(function()
 end)
 
 M.cancel = Promise.async(function()
-  if state.windows and state.active_session then
-    if state.is_running() then
-      M._abort_count = M._abort_count + 1
-
-      local permissions = state.pending_permissions or {}
-      if #permissions and state.api_client then
-        for _, permission in ipairs(permissions) do
-          require('opencode.api').permission_deny(permission)
-        end
-      end
+  if state.active_session and state.is_running() then
+    M._abort_count = M._abort_count + 1
 
-      local ok, result = pcall(function()
-        return state.api_client:abort_session(state.active_session.id):wait()
-      end)
-
-      if not ok then
-        vim.notify('Abort error: ' .. vim.inspect(result))
+    local permissions = state.pending_permissions or {}
+    if #permissions and state.api_client then
+      for _, permission in ipairs(permissions) do
+        require('opencode.api').permission_deny(permission)
       end
+    end
 
-      if M._abort_count >= 3 then
-        vim.notify('Re-starting Opencode server')
-        M._abort_count = 0
-        -- close existing server
-        if state.opencode_server then
-          state.opencode_server:shutdown():await()
-        end
+    local ok, result = pcall(function()
+      return state.api_client:abort_session(state.active_session.id):wait()
+    end)
 
-        -- start a new one
-        state.opencode_server = nil
+    if not ok then
+      vim.notify('Abort error: ' .. vim.inspect(result))
+    end
 
-        -- NOTE: start a new server here to make sure we're subscribed
-        -- to server events before a user sends a message
-        state.opencode_server = server_job.ensure_server():await() --[[@as OpencodeServer]]
+    if M._abort_count >= 3 then
+      vim.notify('Re-starting Opencode server')
+      M._abort_count = 0
+      -- close existing server
+      if state.opencode_server then
+        state.opencode_server:shutdown():await()
       end
+
+      -- start a new one
+      state.opencode_server = nil
+
+      -- NOTE: start a new server here to make sure we're subscribed
+      -- to server events before a user sends a message
+      state.opencode_server = server_job.ensure_server():await() --[[@as OpencodeServer]]
     end
+  end
+
+  if state.is_visible() then
     require('opencode.ui.footer').clear()
     input_window.set_content('')
     require('opencode.history').index = nil