Session tags & pinning
Session tags classify active sessions with a single marker from Priority, Progress, or Type sections. Pinning keeps important rows at the top of a project group. Tags and pins are independent — a session can be pinned without a tag, tagged without being pinned, or both.
What it is
Ghostex replaced the legacy Favorite toggle with a full session tag system. Each session carries at most one tag at a time. Tags appear as leading icons on session cards, drive sidebar filter checkboxes, and restore when you reopen a session from Previous Sessions.
Pinned sessions stay at the top of their project group and remain manually reorderable in both Last Active and Manual sort modes. Pinning controls sidebar order only — it does not replace classification tags.
Available tags
| Option | What it does |
|---|---|
favorite | Priority — replaces legacy Favorite star |
high-priority | Priority — urgent attention |
low-priority | Priority — deprioritized work |
todo | Progress — not started |
in-progress | Progress — actively being worked |
testing | Progress — under test |
blocked | Progress — waiting on dependency |
on-hold | Progress — paused intentionally |
done | Progress — finished |
research | Type — exploration or spike |
bug | Type — defect fix |
feature | Type — new capability |
design | Type — design or UX work |
Tags are mutually exclusive. Selecting a tag that is already applied removes it. Legacy rows with isFavorite: true but no tag are treated as favorite.
Applying tags and pins
- Right-click a session card → Pin or Unpin toggles pinned state.
- Right-click → Tag as opens a submenu grouped by Priority, Progress, and Type.
- Selecting the current tag again removes it (aria: Remove {label} tag).
- Browser sessions and Show more rows cannot be tagged.
- Pinned sessions can only be reordered within their own project — cross-project drags are rejected.
- Card icon precedence: Delayed Send timer → tag icon → pin icon (when untagged) → agent icon on hover.
Sidebar tag filters
Project and Quick section headers expose a filter button. When one or more tags are selected, only sessions with a matching tag appear — untagged sessions are hidden. Filter semantics are OR: any selected tag matches.
- Empty filter selection shows all sessions including untagged rows.
- Filter button aria: Filter sessions: {sort mode} or …, N tag filter(s).
- Sort menu also contains Last Active Sorting and Manual Sorting toggles.
- When a tag is hidden or disabled in Settings, it is automatically removed from active filters.
Settings → Sidebar Tags
Settings → Sidebar Tags → Tag filter list lets you reorder, hide, or disable sidebar tag filters and separators without changing stored session tag values.
| Option | What it does |
|---|---|
sidebarSessionTagListItems | Ordered list of tag and separator items with enabled and visible flags (default: all 13 tags plus two section separators) |
Enable switch | Disable a tag in the filter menu (grayed out, not clickable) |
Eye icon | Hide a tag or separator from the filter menu entirely |
Reset to Default | Restore the default tag order, separators, and visibility |
Default separators sit between Priority/Progress and Progress/Type. Settings search key: sidebarTags.
Pinned session ordering
- Drag pinned rows within a project to reorder; drop indicators appear between pinned cards.
- On drop, pinned IDs merge first, then unpinned IDs, and sync via syncSessionOrder.
- Sort key: sidebarOrder, then active rank, pin rank, lastActiveAt, sessionId.
- Pin rank 0 = pinned; rank 1 = favorite tag or legacy isFavorite; rank 2 = everything else.
- Manual sort mode persists sidebarOrder as (index + 1) × 1000 via gxserver.
Previous Sessions filters
The Previous Sessions modal includes its own tag filter button inside the search field. Unlike the active sidebar, it uses the full static tag list (not the Settings-customized filter list).
- Aria: Filter previous sessions by tag or …by N tags.
- Empty filter shows all tags plus untagged previous sessions.
- Restore preserves sessionTag, isPinned, sidebarOrder, and legacy favorite state.
CLI commands
gx pin-session <selector> [true|false]
gx favorite-session <selector> [true|false]
# Selectors: session id, numeric alias, provider name, quoted title, project:title
gx pin-session 3 true
gx favorite-session "Fix auth bug" false| Option | What it does |
|---|---|
pin-session | Set isPinned via gxserver /api/updateSession (default: true) |
favorite-session | Legacy bridge — sets isFavorite, which maps to sessionTag favorite when true |
There is no CLI for arbitrary tags (todo, bug, in-progress, etc.). Use the sidebar context menu or TUI Favorite/Unfavorite for non-pin tag changes.
Tips
- Use favorite for sessions you want both tagged and slightly boosted in sort order — use pin when you only care about top placement.
- Disable noisy tags in Settings if your filter menu is too long; hidden tags do not affect session cards.
- When filtering by tag, remember untagged sessions disappear — clear filters to see the full project.
- Command-pane sessions receive tag and pin updates on the commands panel snapshot, not the grouped workspace sidebar.
- TUI context menu supports Favorite/Unfavorite only — no pin or progress tags from the terminal UI.