feat(desktop): add Workbench/Review mode + group tabs + workspace navigation sidebar
Happy Path Demo
Summary
This PR bundles several related features for the desktop app:
-
Workbench/Review Mode - A workspace-level view mode toggle:
- Workbench mode: Mosaic panes layout with terminals + file viewers side-by-side
- Review mode: Dedicated Changes page for focused code review
-
Configurable Workspace Navigation - A setting to choose between:
- Top bar: Horizontal tabs (current behavior)
- Sidebar: Vertical list grouped by project (Linear/GitHub Desktop style)
-
Configurable Group Tabs Position - A setting to control where terminal group tabs appear:
- Sidebar (default): Full-featured ModeCarousel with TabsView (rename, reorder, presets)
- Content header: Compact horizontal GroupStrip
Also includes:
- "Mark as Unread" / "Mark as Read" context menu for workspaces with auto-clear and undo
- Configurable terminal file link behavior (open in file viewer vs external editor)
- Inline file editing in FileViewerPane with ⌘+S save
- Improved sidebar mode layout: "Open In" and "Workbench/Review" controls moved to content header
Design decisions & future direction:
- Terminal group tabs position and workspace navigation are independently configurable for backward compatibility. The recommended UX pairs the workspace sidebar with sidebar group tabs—we can unify these as the default once we're confident in the pattern and deprecate the separate toggles.
- The only visual "breaking" change is relocating the "Open In" control. The branch name it displayed is already visible in two other places in the app shell, so no information is lost.
- The Workbench/Review mode split is transitional. As we improve inline diff viewing in the workbench, we expect to merge these modes—making workbench the single default with integrated review capabilities.
Part 1: Workbench/Review Mode
Why
Users need to view code, diffs, and docs while keeping terminals visible in the same window. The existing Changes page is great for focused review, but doesn't support in-flow work where you want terminals and file viewers side-by-side.
What / How
Introduces a workspace-level Workbench | Review view mode toggle:
- Workbench mode: Mosaic panes layout with terminals + file viewers for in-flow work. Clicking a file in the sidebar opens a FileViewer pane next to your terminals.
- Review mode: Dedicated Changes page for focused code review (existing behavior preserved).
Key implementation details:
- ViewModeToggle - Prominent segmented control in workspace header for switching modes
- FileViewerPane - New pane type with Raw/Rendered/Diff view modes, lock/unlock (prevents file replacement), and split support
- GroupStrip - Group switching strip above Mosaic content (when group tabs position is "content-header")
- Unified sidebar - Full ChangesView in both modes; in Workbench, file clicks trigger
onFileOpencallback to open FileViewer panes - workspace-view-mode store - Per-workspace persistence via Zustand + localStorage
- readWorkingFile tRPC - Safe file reads with size cap (2MB) and binary detection
- MRU pane reuse - File clicks reuse most-recently-used unlocked FileViewer pane; locked panes are preserved
- ⌘+T behavior - In Review mode, switches to Workbench first, then creates terminal
Inline Editing Support
FileViewerPane supports full editing in both Raw and Diff modes:
- Raw mode - Monaco Editor with syntax highlighting
- Diff mode - Editing enabled on the modified side of the diff viewer
- ⌘+S to save - Standard keyboard shortcut saves changes to disk
- Dirty state tracking - Orange dot (●) indicator before filename when unsaved changes exist
- Editable badge - Shows "⌘S" hint (changes to "Saving..." during save operation)
- Auto-refresh - Queries invalidated after save to keep UI in sync
- Unsaved changes protection - Switching between Raw/Diff modes with unsaved changes shows a dialog with options to Cancel, Discard & Switch, or Save & Switch (with loading state during save)
Security Hardening
File Viewer file operations include robust symlink escape protection:
- Centralized security module: New
security/folder with path validation, secure fs, and git command wrappers - Centralized read security:
secureFs.readFile()andreadFileBuffer()enforce symlink-escape checks internally - ENOENT handling: Writes through non-existent paths validate parent directory chain (detects dangling symlinks pointing outside worktree)
- Distinct error codes:
symlink-escapereason returned separately fromoutside-worktreefor precise error handling - Fail-closed behavior: All validation errors default to blocking the operation
- SafeImage for markdown: Only renders embedded
data:URLs in markdown images; blocks http/https (tracking pixels), file:// (local file access), and relative paths (traversal attacks)
Configurable Terminal File Link Behavior
Added a global setting to control how Cmd+clicking file paths in the terminal behaves:
- Setting location: Settings → Behavior → "Terminal file links"
- Options:
- "External editor" (default) - Opens file in configured external editor
- "File viewer" - Opens file in the in-app FileViewerPane
- Uses ref pattern to avoid terminal recreation when setting changes
- Setting changes apply immediately without terminal restart
- Line/column support - Terminal links with
file:line:colformat navigate to the correct position in File Viewer
Part 2: Workspace Navigation Sidebar
Architecture
- Persisted setting: Navigation style stored in SQLite via
settings.navigationStylecolumn - Shared hook pattern:
useWorkspaceShortcutsextracts keyboard shortcuts (⌘1-9) and auto-create logic shared between both modes - Zustand state: Sidebar width, collapsed projects, and open state persisted with
zustand/persist - Lazy data loading: GitHub PR status loaded on hover to avoid N+1 queries
How it works
- User selects "Top bar" or "Sidebar" in Settings → Behavior
- MainScreen queries the setting and conditionally renders:
- Top bar mode: WorkspacesTabs in the header (current behavior)
- Sidebar mode: ResizableWorkspaceSidebar on the left + simplified TopBar
- Both modes share the same keyboard shortcuts via
useWorkspaceShortcutshook
Sidebar Mode Layout Improvements
In sidebar navigation mode, the "Open In" button and "Workbench/Review" toggle have been moved from the TopBar down to the ContentHeader:
Before:
TopBar: [◧] │ Project / workspace-name │ [Open ▾] [Workbench│Review] [👤]
ContentHeader: [☰] │ [Group1 ×] [Group2 ×] [+]
After:
TopBar: [◧] │ Project / workspace-name │ [👤]
ContentHeader: [☰] │ [Group1 ×] [Group2 ×] [+] │ [Open ▾] [Workbench│Review]
This keeps the profile dropdown at the top while placing workspace controls closer to the content they affect. The controls are visible in both:
- Workbench mode: With group tabs (when position is "content-header")
- Review mode: Without group tabs (just the controls)
Top-bar navigation mode is unchanged.
Key decisions
| Decision | Choice | Rationale |
|---|---|---|
| Sidebar type | New dedicated sidebar | Avoids complexity of reusing ModeCarousel |
| State storage | Zustand + localStorage | Matches existing sidebar patterns |
| Collapsed projects | string[] not Set<string> | JSON serialization for persist middleware |
| Diff stats source | getGitHubStatus on hover | Avoids N+1 queries, lazy load pattern |
| TopBar in sidebar mode | Show project/workspace name | Maintains context without tabs |
| Controls placement (sidebar mode) | ContentHeader | Keeps controls near content, profile at top |
New Components
WorkspaceSidebar
WorkspaceSidebar.tsx- Main sidebar componentWorkspaceSidebarHeader.tsx- "Workspaces" title headerWorkspaceSidebarFooter.tsx- "Add project" buttonResizableWorkspaceSidebar.tsx- Wrapper with resize handle
ProjectSection
ProjectSection.tsx- Collapsible project group with workspacesProjectHeader.tsx- Project name, color dot, collapse toggle
WorkspaceListItem
WorkspaceListItem.tsx- Individual workspace row with lazy-loaded PR dataWorkspaceStatusBadge.tsx- PR status badge (open/merged/closed/draft)WorkspaceDiffStats.tsx- Additions/deletions display
Shared
useWorkspaceShortcuts.ts- Shared hook for ⌘1-9 shortcuts and auto-create logicworkspace-sidebar-state.ts- Zustand store for sidebar UI state
Part 3: Mark as Unread/Read for Workspaces
Right-click any workspace (in top bar tabs or sidebar) to toggle its "unread" state. This is a workspace-level feature, separate from pane-level agent notifications.
How it works
- "Mark as Unread" - Sets
workspace.isUnread = truein SQLite database - Red pulsing indicator - Shows on the workspace tab/list item when unread
- Auto-clear on switch - When you click to switch to an unread workspace:
- The unread state is automatically cleared
- An undo toast appears for 5 seconds: "Marked as read" with Undo button
- Clicking Undo restores the unread state
- "Mark as Read" - Explicitly clear the unread state via context menu
Why workspace-level instead of pane-level?
Previously, "Mark as Unread" set needsAttention: true on all panes in the workspace, causing:
- ❌ Every tab and pane showing attention indicators (visual clutter)
- ❌ Semantic confusion (manual reminder ≠ agent output needing attention)
- ❌ Tedious to clear (had to visit every pane)
The new approach:
- ✅ Single indicator on the workspace only
- ✅ Clean semantic separation:
workspace.isUnread(manual reminder) vspane.needsAttention(agent notifications) - ✅ Indicator shows if either workspace is manually unread OR any pane has agent attention
Why SQLite instead of Zustand/localStorage?
We store isUnread in SQLite rather than in-memory state for two key reasons:
-
Persistence across app restarts - Users expect "mark as unread" to survive closing and reopening the app, similar to email clients and Slack. SQLite data persists to disk automatically.
-
Workspace is a database entity - The
workspacestable already exists in SQLite with other workspace metadata. AddingisUnreadas a column keeps related data together and avoids split-brain between SQLite and localStorage.
Implementation details
- New
isUnreadcolumn inworkspacestable (migration:0007_add_workspace_is_unread.sql) - New
workspaces.setUnreadtRPC mutation setActivemutation now returnswasUnreadand auto-clears + invalidates queries- Context menu shows "Mark as Read" or "Mark as Unread" based on current state
Part 4: Configurable Group Tabs Position
Why
The initial implementation of this PR moved group tabs from the sidebar (via ModeCarousel + TabsView) to the content header (GroupStrip). This was unintended—the original sidebar behavior should be the default to match the main branch.
What
A new setting allows users to choose where terminal group tabs appear:
- Sidebar (default): Full ModeCarousel with swipeable Tabs/Changes modes
- TabsView has rename, drag-and-drop reorder, and terminal presets
- Matches original behavior on
mainbranch
- Content header: Compact horizontal GroupStrip
- Simpler UI, fewer features
- Good for users who want more sidebar space for changes
How it works
- User selects position in Settings → Behavior → "Group tabs position"
- Setting stored in SQLite via
settings.groupTabsPositioncolumn - Sidebar and ContentView query the setting and render conditionally:
- Sidebar: Shows ModeCarousel (sidebar position) or just ChangesView (content-header position)
- ContentView: Shows GroupStrip only when position is "content-header"
- Review mode always shows ChangesView regardless of setting (never shows tabs)
Key decisions
| Decision | Choice | Rationale |
|---|---|---|
| Default value | "sidebar" | Matches main branch behavior, minimizes breaking change |
| Feature parity | NOT required | TabsView and GroupStrip serve different UX needs |
| Review mode | Always ChangesView | Review mode requires file list to function |
| Storage | SQLite setting | Follows existing navigationStyle pattern |
Keyboard Shortcuts
| Shortcut | Action |
|---|---|
| ⌘⇧B | Toggle workspace sidebar (sidebar mode only) |
| ⌘B | Toggle files sidebar |
| ⌘1-9 | Switch to workspace N (works in both modes) |
| ⌘← / ⌘→ | Previous/next workspace (works in both modes) |
Manual Test Checklist
Workbench/Review Mode
- Toggle between Workbench/Review modes
- File clicks open FileViewer panes in Workbench
- ⌘+T switches to Workbench from Review mode
- FileViewer Raw/Rendered/Diff modes work
- Lock/unlock and split pane work
- GroupStrip switches between groups (when position is "content-header")
- Edit files in Raw mode and save with ⌘+S
- Edit files in Diff mode and save with ⌘+S
- Dirty indicator appears when changes are unsaved
- Switching modes with unsaved changes shows confirmation dialog
- "Save & Switch" saves then switches (dirty indicator clears)
- "Discard & Switch" discards changes and switches
- "Cancel" stays in current mode
Terminal Link Behavior
- Settings → Behavior shows "Terminal file links" dropdown
- Default is "External editor" (existing behavior preserved)
- With "External editor": Cmd+click file path → opens in external editor
- With "File viewer": Cmd+click file path → opens FileViewerPane
- With "File viewer": Cmd+click file:line:col → opens at correct line/column (Known issue - see below)
- Changing setting applies immediately (no terminal restart needed)
- Setting persists after app restart
Security (Symlink Escape Protection)
(Skipped - requires manual symlink setup)
Navigation Style Setting
- Setting persists across app restarts
- Changing setting immediately switches layout
- Default is "Top bar" for new installs
Group Tabs Position Setting
- Settings → Behavior shows "Group tabs position" dropdown
- Default is "Sidebar" for new installs
- "Sidebar" position: ModeCarousel with Tabs/Changes modes appears in sidebar
- "Sidebar" position: Can swipe between Tabs and Changes views
- "Sidebar" position: TabsView features work (rename, reorder, presets)
- "Sidebar" position: No GroupStrip in content header
- "Content header" position: GroupStrip appears in content header
- "Content header" position: Sidebar shows only ChangesView
- Changing setting immediately updates UI (no restart needed)
- Setting persists after app restart
- In Review mode, groups are NEVER shown (regardless of setting)
- Works correctly with both "Top bar" and "Sidebar" navigation styles
Sidebar Mode
- Sidebar renders with correct width (default 280px)
- Sidebar is resizable between 220-400px
- Resize persists across restarts
- ⌘⇧B toggles sidebar visibility
- Projects are collapsible
- Collapsed state persists
- Active workspace has left border indicator
- Hover shows keyboard shortcut (⌘1-9)
- PR status/diff stats load on hover (worktree workspaces)
- "Add project" button works
Sidebar Mode Layout
- In sidebar mode, "Open In" and "Workbench/Review" controls appear in ContentHeader (not TopBar)
- Profile dropdown remains in TopBar
- Controls visible in Workbench mode (with group tabs when position is "content-header")
- Controls visible in Review mode (without group tabs)
- Changes sidebar toggle (☰) works in both Workbench and Review modes
- Top-bar navigation mode is unchanged (controls remain in TopBar)
Top Bar Mode
- Existing tab behavior unchanged
- No workspace sidebar visible
- ⌘⇧B does nothing (correct)
Keyboard Shortcuts (Both Modes)
- ⌘1-9 switches to correct workspace
- ⌘← / ⌘→ navigates workspaces
- Auto-create main workspace still works
Mark as Unread/Read Feature
- Right-click workspace in top bar shows context menu
- Right-click workspace in sidebar shows context menu
- "Mark as Unread" shows red pulsing indicator on workspace only (not on every tab)
- "Mark as Read" clears the indicator
- Switching to unread workspace shows "Marked as read" toast with Undo button
- Clicking Undo in toast restores the unread state
- Unread state persists after app restart
- Works for both worktree and branch workspaces
- Works in both top bar and sidebar navigation modes
- Pane-level agent attention indicators still work independently
Known Issues
-
Unsaved changes lost on group/workspace switch - Switching between groups or workspaces while a FileViewer has unsaved changes will discard those changes without warning. The unsaved changes dialog currently only protects Raw↔Diff mode switches within the same pane. Follow-up needed to add protection for group and workspace navigation.
-
Terminal file links don't navigate to line/column - Cmd+clicking a file path with line:column format (e.g.,
src/file.ts:42:10) opens the file but doesn't navigate to the specified line/column. Will fix in follow-up PR.
Future Work
- Keyboard shortcut for mode toggle - Add
⌘+\or similar to toggle between Workbench/Review - Migrate to
workspaceId-based APIs - AcceptworkspaceIdinstead ofworktreePathin renderer calls - Reconsider FileViewer lock/unlock UX - The current lock mechanism (to prevent MRU pane reuse) works but may not be discoverable. Consider alternatives like VS Code's preview mode (single-click = preview, double-click = pin), or auto-locking on edit, or a more prominent visual distinction between locked/unlocked states.
Files Changed
New Files (Workbench/Review)
GroupStrip/GroupStrip.tsx- Group switching strip componentFileViewerPane/FileViewerPane.tsx- File viewer with Raw/Rendered/Diff modes + inline editingFileViewerPane/UnsavedChangesDialog.tsx- Confirmation dialog for unsaved changes on mode switchChangesView/components/ViewModeToggle/ViewModeToggle.tsx- Segmented control for mode toggleTopBar/WorkspaceControls/ViewModeToggleCompact.tsx- Compact version for content headerworkspace-view-mode.ts- Per-workspace view mode store0004_add_terminal_link_behavior_setting.sql- Migration for terminal link behavior setting
New Files (Security)
security/index.ts- Security module exportssecurity/path-validation.ts- Path validation utilities with symlink escape detectionsecurity/secure-fs.ts- Secure filesystem operationssecurity/git-commands.ts- Secure git command wrappersSafeImage/SafeImage.tsx- Secure image component for markdown (only allows data: URLs)
New Files (Workspace Sidebar)
apps/desktop/src/renderer/hooks/useWorkspaceShortcuts.tsapps/desktop/src/renderer/stores/workspace-sidebar-state.tsapps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceSidebarControl.tsxapps/desktop/src/renderer/screens/main/components/TopBar/WorkspaceControls/- New folder with OpenInMenuButton and WorkspaceControlsapps/desktop/src/renderer/screens/main/components/WorkspaceSidebar/*(10 files)packages/local-db/drizzle/0005_add_navigation_style.sql
New Files (Mark as Unread)
packages/local-db/drizzle/0007_add_workspace_is_unread.sql- Migration for isUnread column
New Files (Group Tabs Position)
packages/local-db/drizzle/0008_add_group_tabs_position.sql- Migration for groupTabsPosition columnapps/desktop/plans/20260104-1916-restore-group-tabs-sidebar.md- Implementation plan
New Files (Database)
packages/local-db/drizzle/0006_add_unique_branch_workspace_index.sql- Migration to dedupe existing branch workspaces and add unique index (one branch workspace per project)
New Files (Hooks)
useWorkspaceDeleteHandler.ts- Shared hook for workspace delete/close dialog state
Deleted Files
WorkspaceActionBar/WorkspaceActionBar.tsx- Removed (controls moved to TopBar/ContentHeader)WorkspaceActionBar/components/WorkspaceActionBarLeft/- RemovedWorkspaceActionBar/components/WorkspaceActionBarRight/- Renamed toTopBar/WorkspaceControls/OpenInMenuButton.tsx
Modified Files
file-contents.ts- AddedreadWorkingFileprocedureContentView/index.tsx- Routes to TabsContent or ChangesContent based on mode; conditional GroupStrip based on position settingContentHeader/ContentHeader.tsx- AddedtrailingActionprop for right-side controlsChangesView.tsx- AddedonFileOpencallback propSidebar/index.tsx- Conditional ModeCarousel vs ChangesView based on position settingWorkspaceView/index.tsx- View mode reactivity and ⌘+T behaviortabs/store.ts- Removed oldmarkWorkspaceAsUnread(now uses tRPC)tabs/types.ts- RemovedmarkWorkspaceAsUnreadfrom interfaceshared/tabs-types.ts- Addedfile-viewerpane typeTerminal/helpers.ts- Refactored to acceptonFileLinkClickcallbackTerminal/Terminal.tsx- Wired up terminal link behavior settingBehaviorSettings.tsx- Added terminal link behavior, navigation style, and group tabs position dropdownssettings/index.ts(tRPC) - Added getters/setters for all new settingsschema.ts/zod.ts(local-db) - AddedisUnreadcolumn to workspaces,groupTabsPositionto settingsworkspaces.ts(tRPC) - AddedsetUnreadmutation, updatedsetActiveto auto-clear and returnwasUnreaduseSetActiveWorkspace.ts- Added undo toast for auto-cleared unread stateWorkspaceItemContextMenu.tsx- Now uses tRPC mutation, shows Read/Unread toggleWorkspaceItem.tsx- Uses workspace-levelisUnreadfor indicatorWorkspaceGroup.tsx- PassesisUnreadto WorkspaceItemWorkspaceListItem.tsx- Uses workspace-levelisUnreadfor indicatorProjectSection.tsx- PassesisUnreadto WorkspaceListItemTopBar/index.tsx- Conditional rendering based on navigation style; WorkspaceControls only in top-bar modeTopBar/WorkspaceTabs/index.tsx- Refactored to use shared hookMainScreen/index.tsx- Wire up sidebar and navigation styleshared/constants.ts- AddedDEFAULT_NAVIGATION_STYLEandDEFAULT_GROUP_TABS_POSITIONshared/hotkeys.ts- AddedTOGGLE_WORKSPACE_SIDEBAR, renamedTOGGLE_SIDEBAR
Summary by CodeRabbit
-
New Features
- File viewer pane (raw/rendered/diff) with editing, save flow, unsaved-changes dialog; resizable Workspaces sidebar, workspace list items, group strip, and workspace controls.
- Terminal link behavior setting to open file links in external editor or in the file viewer.
- SafeImage for rendering Markdown images.
-
Security
- Stricter worktree/path validation and secure filesystem/git helpers to prevent traversal and symlink escapes.
-
Improvements
- Per‑workspace view modes (workbench/review), unread indicators, updated hotkeys, and refined top bar/controls for accessibility.
✏️ Tip: You can customize this high-level summary in your review settings.