Workspace & Project Navigation

Relevant source files

The following files were used as context for generating this wiki page:

• src/features/workspace/model/layout.test.ts
• src/features/workspace/ui/WorkspacePicker.tsx
• src/features/workspace/model/workspaceSnapshot.test.ts
• src/features/source-control/ui/Worktrees.test.ts
• src/shared/lib/paths.test.ts
• src/features/source-control/ui/GitChangesPanel.tsx

Workspace and project navigation in Rebase provides the interface and logic for managing coding sessions, file editors, and terminal instances across different project contexts. The system allows you to organize work into separate panes, switch between Git worktrees, and maintain project-specific states using a snapshot-based persistence model.

The workspace acts as a top-level container that manages a tree of splits and leaves. Each leaf represents a UI pane (such as a session, editor, or terminal), while splits organize these panes horizontally or vertically. Navigation extends beyond simple UI tabs to include project-level context switching via the Workspace Picker and Git worktree management.

Workspace Layout Model

The workspace layout utilizes a recursive tree structure to define how UI elements occupy space. The layout comprises splits (horizontal or vertical) and leaves, where each leaf maps to a specific pane identifier.

Pane Organization

Rebase distinguishes between several types of panes within the workspace:

• Editor Panes: Host file editors, diff views, and commit reviews.
• Terminal Panes: Manage shell instances and terminal-based tools.
• Session Panes: Represent active agent conversations or coding sessions.

The system uses specific helper functions like splitPane to divide existing space and openEditorTab or openTerminalTab to populate those spaces with content.

Tab Management

Panes within a workspace tab maintain their own internal tab strips. For example, an editor pane can hold multiple files, but only one is active at a time. The workspace tracks a focusedId to determine which pane currently receives user input.

Component	Description
WorkspaceTab	A top-level container for a specific layout tree and its associated panes.
EditorPane	A collection of file references and a pointer to the active file.
TerminalPane	A collection of terminal instances.
Leaf	A terminal node in the layout tree pointing to a pane ID.

Sources: src/features/workspace/model/layout.test.ts:80-120, src/features/workspace/model/workspaceSnapshot.test.ts:250-280

Project and Workspace Selection

The WorkspacePicker serves as the primary entry point for navigating between different project environments and working copies. It allows you to toggle between the "Current checkout" (main repository) and specialized Git worktrees.

Navigation Modes

The picker supports two primary modes:

1. Current checkout: Operates within the main project directory.
2. Worktree: Operates in an independent working copy, allowing parallel tasks without disturbing the main checkout.

Quick Git Navigation

For rapid context switching, the system provides a QuickGitPopupPicker. This component facilitates selecting base branches or existing worktrees during session initialization. It handles branch loading states and provides search capabilities for large repositories.
Sources: src/features/quick-composer/ui/QuickGitPopup.test.ts:90-130

Path Resolution and Remote Environments

Rebase handles path navigation across local and remote file systems. It normalizes paths to ensure consistency across different Operating Systems and remote environments.

Path Mapping

The system resolves paths based on the current working directory (CWD). It supports:

• Remote Paths: Prefixed with remote://, identifying files on external machines.
• Home Directory Expansion: Expands ~/ to the inferred or explicitly set home directory.
• UNC Paths: Supports Windows network shares.

Path Type	Example	Resolution Logic
Local Absolute	/repo/src/main.ts	Used directly as a local file reference.
Project Relative	src/main.ts:12	Resolved relative to the project CWD.
Remote	remote://env/repo/a.ts	Kept on the specific remote machine identifier.
Home Expansion	~/notes.md	Prepends the system home path to the reference.

Sources: src/shared/lib/paths.test.ts:10-80, src/features/workspace/model/workspaceSnapshot.test.ts:25-50

Persistence and Snapshots

To maintain continuity, Rebase captures the state of the workspace in a WorkspaceSnapshot. This snapshot stores the configuration of tabs, focused elements, and active sessions.

Snapshot Restoration

When you reopen a project, the system hydrates the workspace from the last saved snapshot. This process involves:

1. Validating References: Pruning stale sessions or worktrees that no longer exist.
2. Restoring Docks: Reopening project terminal docks at their last known positions (e.g., "bottom" or "right").
3. Path Migration: Converting absolute host paths in the snapshot to shared remote paths if the environment has changed.

Git Context Navigation

Navigation within the workspace is heavily integrated with Git state. The GitChangesPanel provides a specialized view for navigating uncommitted changes, staged files, and commit history.

Contextual Features

• Unified Changes: A single view showing all uncommitted work across the project.
• Session-Scoped Changes: Navigation limited to changes relevant only to the current active session.
• Commit Navigation: The ability to open specific commits from a history graph as permanent tabs in the workspace.

Sources: src/features/source-control/ui/GitChangesPanel.tsx:150-200, src/features/workspace/model/layout.test.ts:250-280