Projects & sidebar

The Ghostex sidebar organizes every terminal, agent, browser, and editor pane into project groups. One group per repository (or worktree), plus Quick for projectless chats and Remote for SSH-attached machines.

Workspace & sessionsNavigation

What it is

Ghostex uses a Codex-style sidebar: collapsible project groups contain session cards for agents, terminals, browser panes, and embedded editors. The active project drives titlebar modes (Agents, Source, GitHub, Kanban), command pane actions, and git diff stats in the header.

The sidebar is native AppKit chrome on macOS (not a floating web panel). It shares state with gxserver so CLI, TUI, Android, and iOS see the same project order and session inventory.

Project groups

One project group per repository path or Git worktree.
Project headers expose agent launch, new terminal, browser pane, project editor, git diff stats, theme color, and context-menu filesystem actions.
Worktrees share their parent project's Actions list but have a compact header menu focused on worktree operations.
Empty project groups auto-collapse while empty and expand when sessions appear.
Drag project groups to reorder; order persists locally and syncs to mobile via gxserver.
Use Show more / Show less when a project exceeds the collapsed session limit (default: 10 visible rows).

Quick sessions

The Quick section (internally the Chats collection) holds projectless agent and terminal sessions. The Quick header can launch the selected agent directly with the same picker used by project headers, creating chats that are not tied to a code project.

GitHub and Kanban titlebar modes are unavailable for Quick sessions. Remote attach carrier terminals stay hidden from Quick so focus remains on the owning remote machine row.

Session cards

Each row is a session card showing title, agent icon, working / attention / idle status, tags, last-active time, persistence provider badge, and optional pin or favorite state.

Double-click a card to rename when renameSessionOnDoubleClick is enabled (off by default).
Double-click empty sidebar space to create a session when createSessionOnSidebarDoubleClick is enabled (off by default).
Right-click for Sleep, Wake, Rename, Generate Name, Tag as, Copy resume, Sleep Below, Close Below, and pop-out actions.
Clicking a session while Code, Git, or Project companion panes are hidden switches back to Agents view and focuses that session.
Sleeping rows show a faded card; sleeping pane tabs display Press Any Key to Wake when selected.

Sidebar settings

Option	What it does
`sidebarSide`	Left or right placement (default: left). Cmd+B collapses the sidebar; it does not move sides.
`sidebarDefaultWidthPx`	Reset width on handle double-click (default: 235px, range 150–520)
`projectSessionListCollapsedCount`	Sessions shown before Show more (default: 10, range 1–50)
`renameSessionOnDoubleClick`	Double-click a card to open rename (default: false)
`createSessionOnSidebarDoubleClick`	Double-click empty sidebar to create a session (default: false)
`hideSessionAgentIconUntilHover`	Hide agent icons until row hover
`hideLastActiveTimeOnSessionCards`	Hide last-active timestamps on cards
`showCloseButtonOnSessionCards`	Show inline close button on cards
`hideProjectHeaderDiffStats`	Hide git diff stats in project headers
`showProjectEditorDiffFileCount`	Show changed-file count on project editor rows

Keyboard shortcuts

Option	What it does
`Cmd+B`	Collapse or expand the entire sidebar
`Cmd+P`	Command palette in session-search mode
`Cmd+Shift+P`	Command palette in command mode (prefills >)
`Cmd+R`	Rename the focused session
`Alt+1 … Alt+4`	Switch workarea: Agents, Source, GitHub, Kanban
`Option+1 … Option+5`	Focus project group slots 1–5
`Ctrl+1 … Ctrl+9`	Focus session slots 1–9 in the active group

Project context menus

Right-click a project header for filesystem and lifecycle actions:

Open in Finder, Open in Terminal, Copy Path, Rename project
Sleep Inactive — sleep idle awake sessions (includes idle zmx-backed command terminals)
Wake — wake all sleeping sessions in the group
Reload — reload browser, editor, and terminal panes in the group
Theme — pick a workspace accent color from recent palette
For worktrees: Delete (remove Git worktree) vs Remove (drop Ghostex row only)

Sleep Inactive targets sessions that are awake with idle or unknown activity — not sessions already sleeping or actively working / needing attention.

CLI & automation

ghostex add-project /path/to/repo --name "My App"
ghostex switch-project --path /path/to/repo
ghostex switch-project --project-id <id>
ghostex move-project --project-id <id> --direction up
ghostex focus-group <groupId>
ghostex focus-session <sessionId>

Project-scoped Actions and automations are stored per project; worktrees inherit the parent project's action list. Use ghostex automation-state to inspect Beads-backed automations for a path.

Remote machines

Configure SSH machines in Settings → Remote. Remote groups list sessions discovered on another Mac via ghostex sessions --json. Clicking a remote session opens a local Ghostty terminal that SSH-attaches with:

ghostex attach --session-id <id> --project-id <id>

Copy Attach Command copies the same SSH command for use in an external terminal.

Tips

Use Cmd+P to fuzzy-search sessions by title, project label, tags, and prompt history.
Pin or tag frequently used sessions — filters appear in the sidebar tag bar when configured.
Previous Sessions lives at the bottom of the sidebar for restoring archived identity without losing history.
Sparse sidebars stay pinned instead of rubber-banding when collapsed project lists fit the viewport.
Titlebar collapse button beside the project name mirrors Cmd+B for users who prefer mouse control.

Related docs

Agent CLI support

Session tags & pinning

Previous sessions

Clone & add project