Previous sessions
Previous Sessions is Ghostex's agent-session restore surface. gxserver stores canonical history; the modal lets you search, filter by tag, restore with full provider identity, or delete rows you no longer need.
What it is
Previous Sessions is not a dump of every inactive gxserver row. It surfaces restorable agent sessions ranked by true last activity (lastInteractionAt / closedAt), not metadata refresh timestamps.
Restore recreates the terminal with the original provider, agent, resume command, session tags, pinned state, and manual sidebar order. Browser page history and command-pane runs are excluded from the modal.
Opening Previous Sessions
- Sidebar Search row → hover the Previous Sessions button (history icon).
- Command palette (Cmd+P) → Previous sessions group — up to 20 rows, debounced 200 ms.
- Selecting a previous session from Cmd+P restores it and closes the palette.
- No dedicated hotkey — use Cmd+P search or the sidebar hover button.
Cmd+Shift+P opens command mode (> prefix) for actions only; it does not list previous sessions.
Modal UI
| Option | What it does |
|---|---|
Previous Sessions | Full-window modal title |
Search sessions... | Search placeholder (Fuse.js fuzzy match on titles) |
Filter previous sessions by tag | Tag filter button aria inside the search field |
Restore {title} | Row action — recreates the session |
Delete {title} from previous sessions | Row action — removes the gxserver history row |
Results group by closed day (e.g. Sunday, June 14, 2026). The modal stays hidden until the first result arrives or a 2 s timeout passes, avoiding an empty flash on slow queries.
Search and tag filters
- Typing debounces 200 ms before each gxserver query (limit 80).
- Tag filter uses multi-select OR semantics — empty selection shows all tags plus untagged rows.
- With active tag filters, untagged previous sessions are hidden (same as active sidebar).
- Previous Sessions uses the full static tag list, not the Settings-customized sidebar filter list.
- Empty states: No previous sessions yet / No previous sessions match that search / No tagged previous sessions match that search.
Restore workflow
- Click a row → native resolves the archived sessionRecord and recreates the terminal.
- Ghostex switches to the original project, revives Recent Projects, or recreates the project if needed.
- Tags, pin state, sidebarOrder, and legacy favorite state restore via getRestoredPreviousSessionTag().
- The history row is removed after a successful restore.
- Remote rows: gxserver createSession on the owning machine — no local Ghostty pane on your Mac.
Delete workflow
Delete is local-first: the row disappears from the modal immediately while gxserver removeSession runs asynchronously. A toast appears if the server delete fails.
Delete removes the history entry only — it does not affect any currently running session with the same title.
What gets preserved
| Option | What it does |
|---|---|
historyId | Stable gxserver identifier for restore/delete |
sessionRecord | Full archived terminal record including provider metadata |
sessionTag / isFavorite | Classification restored on reopen |
isPinned / sidebarOrder | Pin and manual order when sidebarOrder > 0 |
projectId / projectPath | Original project association |
closedAt | Used for day grouping in the modal |
isRestorable | Whether gxserver considers the row restorable |
Cmd+P vs Previous Sessions modal
Both surfaces query gxserver previous-session data, but they serve different workflows:
- Cmd+P — fast switcher: current sessions, projects, then up to 20 previous sessions sorted by lastActive.
- Previous Sessions modal — browse-heavy: day groups, tag filters, delete, and full 80-row limit.
- Search by Text (gx f) is a separate system — it searches on-disk agent prompt history, not gxserver metadata.
As of Ghostex 4.11+, the footer buttons Prompt to Find Session and Find Previous Session were removed. Browse, filter, restore, and delete are the supported flows.
Tips
- Tag sessions before closing if you expect to filter Previous Sessions later — untagged rows hide when any tag filter is active.
- Use Cmd+P when you remember the session title; open the modal when you need day grouping or bulk browsing.
- Pinned or tagged inactive sessions may appear even without a trusted resume title.
- There is no CLI restore command — use the UI or gxserver APIs directly for automation.
- Remote previous sessions restore on the owning machine; attach remotely afterward if needed.