734 lines · 38.8 KB · Markdown
RawDownload

Active Projects Architecture

Core Narrative

The sidebar is evolving from a window-level workspace switcher into a global command center for active projects. It is the primary interface for understanding "what am I working on right now?" — similar in spirit to the Codex app or Cursor's agents mode, but designed to work seamlessly across single and multi-window setups.

There are two intertwined narratives driving this:

  1. Active Projects — The sidebar shows everything you're currently thinking about and worrying about. It's not a file browser or a project history. It's a live, curated view of your in-flight work. Projects appear here because you're actively working on them, and they stay until you explicitly dismiss them.

  2. Window Management — The sidebar also serves as the way you navigate between projects across windows. It shows which projects are currently displayed in which windows, and lets you open, switch, and close them fluidly. But this is secondary to the "active projects" narrative — window management is a consequence of the active projects model, not the other way around.

The Key Insight: Active Projects ⊇ Open Windows

The set of active projects is a superset of currently open windows. If you have three windows open but five projects with threads, all five show in the sidebar. Three of them happen to have windows; two don't. When you click one of the un-windowed projects, it opens (or takes over a window). When you close a window, the project doesn't disappear — it stays in the active projects list, just without a window.

This is the fundamental shift from the current model where the sidebar shows "workspaces in this window" to showing "everything I'm working on, globally."

Three Data Sources

The sidebar merges three independent datasets:

1. Active Projects List (Persisted, Inert)

A flat, persisted list of PathList values — the folder sets the user is actively working on. This is just data: no live workspaces, no language servers, no file watchers. It's the durable record of "what do I care about right now?" Entries are added when the user creates a thread in a workspace, and removed only by explicit user action. Owned by the ActiveProjects entity in the sidebar crate.

2. Live Window State (Ephemeral)

Real-time state from WorkspaceStore — which windows are open and which live Entity<Workspace> each one is displaying. This is the source of truth for "is this project currently loaded" and "which window is showing it." Workspaces that are open in a window but not yet in the active projects list appear as ephemeral sidebar entries.

3. Thread History (Persisted)

Persistent data from the threads database via ThreadStore. This enriches each project with its thread history — titles, diff stats, timestamps, agent identifiers, run status. A project with zero threads is completely valid; it just shows the project header without any thread children.

The sidebar is the sole composition point. It observes all three sources, derives grouped project entries, and renders the merge. No source knows about the others.

Data Model

The Stored State Is Flat

The underlying data is two independent flat lists. No grouping, no hierarchy — just workspaces and threads.

Active Projects

A flat list of folder sets the user is currently working on. Each entry is a PathList — a sorted set of absolute paths. No live state, no entities. At startup, the list is loaded from the database as-is.

/// The active projects list. Just folder sets. Lives in crates/sidebar/src/active_projects.rs.
pub struct ActiveProjects {
    projects: Vec<PathList>,
}

When a project has a window open, the live Entity<Workspace> is the source of truth for its current folder paths. When a project has no window, the stored PathList is the last-known state — folder names can go stale if renamed while Zed isn't watching, but this is rare and acceptable.

Threads

A flat list of thread metadata from the thread database. Each thread knows which folder paths it was created against. This is the existing DbThreadMetadata infrastructure, potentially extended with diff stats and agent identity.

/// Already exists in crates/agent/src/db.rs — may need extension.
struct DbThreadMetadata {
    id: acp::SessionId,
    parent_session_id: Option<acp::SessionId>,
    title: SharedString,
    updated_at: DateTime<Utc>,
    worktree_branch: Option<String>,
    // Potential extensions for the new sidebar:
    // agent_name: Option<SharedString>,
    // lines_added: Option<i32>,
    // lines_removed: Option<i32>,
}

Project Groups Are Derived Data

Project groups are not stored. They are computed from the two flat lists every time the sidebar needs to render. This is a pure function:

fn derive_project_groups(
    active_projects: &[PathList],
    windowed_workspaces: &[(AnyWindowHandle, Entity<Workspace>)],
    threads: &[DbThreadMetadata],
    cx: &App,
) -> Vec<ProjectGroup>;

The derivation works as follows:

  1. Start with the persisted active projects list (inert PathList values).
  2. Add any windowed workspaces whose PathList isn't already in the active list (ephemeral entries).
  3. For each thread, look at which folder paths it was created against.
  4. Group everything that shares the same PathList.
  5. For each group, check if any live workspace matches (for window indicators and live path data).
  6. Produce ProjectGroup values for the sidebar to render.
/// Computed at render time. Never stored.
struct ProjectGroup {
    /// The PathList that defines this group. Computed from the workspaces
    /// within it — never stored as an identity.
    path_list: PathList,
    /// Display name derived from folder names (e.g., "zed" or "ex, zed").
    display_name: SharedString,
    /// The entries in this group, ready for rendering.
    entries: Vec<ThreadEntry>,
}

/// A single entry in a project group, ready for rendering.
struct ThreadEntry {
    path_list: PathList,
    workspace: Option<Entity<Workspace>>,
    thread_info: Option<SidebarThreadInfo>,
    /// The windows currently displaying a workspace for this project.
    windows: Vec<WindowId>,
    /// Git worktree annotation (e.g., "in olivetti") if applicable.
    worktree_annotation: Option<SharedString>,
}

Why Derived?

Because the underlying data mutates out from under us. A user renames a folder, adds a worktree, changes a project — and the grouping should just reflect reality. If project groups were stored, we'd have to detect every mutation and re-file things. With derivation, we just re-derive and the UI updates.

Concrete example: You have a git worktree "olivetti" of the "zed" repo, showing as its own workspace under the "zed" group. You click "Add Folder" and add "cloud" to that workspace. The workspace's PathList changes from {zed} to {cloud, zed}. Next derivation: the workspace moves to the "cloud, zed" group, with an annotation "zed is in olivetti." No bookkeeping, no re-filing — the derivation function just sees the new state.

PathList As Grouping Key

PathList (from crates/workspace/src/path_list.rs) is the derived grouping key. It's a sorted set of folder paths computed by asking a workspace for its current worktree paths. PathList already handles lexicographic sorting for comparison, preserves original order, and has serialization/deserialization support.

/// Already exists in crates/workspace/src/path_list.rs.
/// Stores paths in lexicographic order for equality comparison,
/// with original insertion order preserved separately.
#[derive(Default, PartialEq, Eq, Debug, Clone)]
pub struct PathList {
    paths: Arc<[PathBuf]>,
    order: Arc<[usize]>,
}

To compute a PathList from a workspace:

fn path_list_from_workspace(workspace: &Workspace, cx: &App) -> PathList {
    let paths: Vec<PathBuf> = workspace
        .worktrees(cx)
        .filter(|wt| wt.read(cx).is_visible())
        .map(|wt| wt.read(cx).abs_path().to_path_buf())
        .collect();
    PathList::new(&paths)
}

Progressive enhancement with git: Without git, the PathList is literally the set of folder paths. With git, worktrees at different physical locations can be recognized as the same logical project and grouped together. This is a refinement on top of the base concept, not a requirement.

Open question: The exact canonicalization logic for git worktrees. A worktree at /tmp/zed-worktree-fix-123 and the main repo at /home/user/zed need to resolve to the same PathList. This likely means "the path to the main git directory" is the canonical identity, with worktree paths as variants. There's existing infrastructure for this — AgentGitWorktreeInfo already tracks the worktree path and branch, and the thread DB stores worktree_branch for listing convenience.

SidebarThreadInfo (Display Data)

The metadata the sidebar displays for each thread. Assembled during derivation from thread database records and live thread state.

/// Assembled during project group derivation for display purposes.
struct SidebarThreadInfo {
    thread_id: acp::SessionId,
    title: SharedString,
    icon: IconName,
    agent_name: Option<SharedString>,
    status: AgentThreadStatus,
    lines_added: Option<i32>,
    lines_removed: Option<i32>,
    updated_at: DateTime<Utc>,
}

This is significantly richer than the current AgentThreadInfo which only has title, status, and icon. The additional fields (agent_name, lines_added, lines_removed, updated_at) come from the thread database and the live Thread entity.

Three Data Sources, One Sidebar

The sidebar composes three independent data sources into a grouped UI. They have separate responsibilities and separate persistence.

1. Active Projects List (Persisted, Inert)

An app-global, persisted list of projects the user is actively working on. This is its own data — not derived from recent projects, not derived from thread history. It has its own spot in the database.

/// App-global persisted list. Its own database table/file.
/// This is an append-mostly list — entries are added automatically
/// when a thread is created, and removed only by explicit user action.
/// No live state — just folder paths.
struct ActiveProjectsList {
    /// Each entry is just a set of folder paths. No live workspaces, no rehydration.
    projects: Vec<PathList>,
}

Entry condition: A project joins this list when the user creates a thread in it. Having an open workspace is not enough — the thread is the "save" trigger. This is the moment the project becomes durable.

Persistence: The list is serialized as folder paths. On startup, the list is loaded as-is — no rehydration, no workspace creation, no language servers. The PathList values are inert data. Live workspaces are only created on demand when the user clicks an entry or when a window opens.

The list is append-mostly: Once a project is in the list, it stays. No automatic removal based on time, inactivity, or window closing.

Manual removal only: The user explicitly clicks "Remove Project" to take something off the list. That is the only removal mechanism.

2. Live Window State (Ephemeral)

The set of currently open windows and which workspace each one is displaying. This is runtime state — not persisted to the active projects list.

/// Runtime-only. Tracks which windows exist and what they're showing.
struct WindowState {
    /// Which workspace each window is currently displaying.
    assignments: HashMap<WindowId, Entity<Workspace>>,
}

A workspace that is open in a window but has no threads appears in the sidebar while the window is open — it's live, ephemeral data. When the window closes, it disappears from the sidebar entirely because it was never persisted to the active projects list.

3. Thread Database (Thread History)

The existing ThreadStore / agent DB infrastructure. The source of truth for thread metadata — titles, timestamps, diff stats, which folder paths a thread was running against.

The sidebar queries this during derivation to enrich project entries with their thread lists. The thread database knows nothing about windows, active/inactive state, or project groups.

Key query the sidebar needs:

/// Query threads whose folder paths match. Returns thread metadata sorted by recency.
fn threads_for_paths(paths: &[PathBuf]) -> Vec<DbThreadMetadata>;

This builds on the existing DbThreadMetadata which already has id, title, updated_at, and worktree_branch. It may need to be extended with diff stats and agent identity.

4. How The Sidebar Composes All Three

The sidebar's visible list is the union of two sets:

  1. The persisted active projects list — durable entries, always shown regardless of window state.
  2. Currently open windows not yet in the active list — ephemeral entries that disappear on window close.

The sidebar observes all three data sources and derives the grouped view:

  1. Read the persisted active projects list.
  2. Read the live window state to find any workspaces not yet in the active list.
  3. Merge both sets into a single flat workspace list.
  4. Query the thread database for threads matching each workspace's folder paths.
  5. For loaded workspaces, also check live Entity<Thread> for real-time status.
  6. Call derive_project_groups() to group everything by folder set.
  7. Render the derived groups with window indicators showing which entries currently have a window looking at them.

The thread-creation trigger: When the user creates a thread in an ephemeral workspace (one that's only in the sidebar because its window is open), the sidebar persists that workspace to the active projects list. From that point on, it survives window close.

This keeps all three systems decoupled. The active projects list doesn't know about threads or windows. The thread database doesn't know about windows or active/inactive state. The window state doesn't know about persistence. The sidebar is the composition and derivation layer.

WorkspaceStore (Window Tracking Only)

The existing WorkspaceStore (in crates/workspace/src/workspace.rs) is already an app-global entity that tracks all workspaces with their window handles. It's currently used for collaboration/follow features. It continues to serve as the source of truth for "which windows are open and what workspace is each one showing." It does not own the active projects list — that belongs to ActiveProjects in the sidebar crate.

/// Already exists in workspace crate. Unchanged for active projects.
pub struct WorkspaceStore {
    /// Existing: all workspaces with their window handles (used for collab/follow).
    workspaces: HashSet<(AnyWindowHandle, WeakEntity<Workspace>)>,
    client: Arc<Client>,
    _subscriptions: Vec<client::Subscription>,
}

Key Queries

impl WorkspaceStore {
    /// Existing: all workspaces with their window handles.
    fn workspaces_with_windows(&self) -> impl Iterator<Item = (AnyWindowHandle, &WeakEntity<Workspace>)>;

    /// Which windows are currently showing a workspace with this PathList.
    fn windows_for_path_list(&self, path_list: &PathList, cx: &App) -> Vec<WindowId>;
}

Key Mutations

impl WorkspaceStore {
    /// A window closed. The project stays in the active list (owned by ActiveProjects)
    /// if persisted; disappears from the sidebar if it was only ephemeral.
    fn detach_window(&mut self, window_id: WindowId, cx: &mut App);
}

Note: window assignment tracking already exists via workspaces: HashSet<(AnyWindowHandle, WeakEntity<Workspace>)>. We don't need a separate window_assignments map — the existing set already associates windows with workspaces. The active projects list is owned by the ActiveProjects entity in the sidebar crate, not by WorkspaceStore.

What Happens To MultiWorkspace

MultiWorkspace doesn't get deleted. It gets hollowed out.

What It Keeps

  • Window layout — rendering the sidebar alongside the workspace, the resize handle, sidebar open/close state
  • Sidebar host — the SidebarHandle trait, sidebar registration, focus management
  • Action routing — keyboard shortcuts for toggling sidebar, focus switching
  • Window shell — client-side decorations, the top-level element composition

What It Lost (already done)

  • Vec<Entity<Workspace>> — the active projects list is now owned by ActiveProjects in the sidebar crate
  • active_workspace_index — WorkspaceStore tracks which project is in which window
  • create_workspace / remove_workspace — lifecycle is handled externally
  • activate_index / activate_next / activate_previous — navigation goes through the sidebar

What It Is Now

Essentially a WindowRoot — a thin component that holds one workspace, overlays the sidebar, and handles window-level layout.

WindowRoot (née MultiWorkspace)
  window_id: WindowId
  workspace: Entity<Workspace>         — the single currently-displayed workspace
  sidebar: Option<Box<dyn SidebarHandle>>
  sidebar_open: bool

The key conceptual shift: MultiWorkspace used to own workspaces. WindowRoot borrows whichever workspace WorkspaceStore tells it to display.

Sidebar Rendering (unchanged from original)

Visual Structure

┌─────────────────────────────┐
│ [Close]  Threads  [+ New]   │  ← Title bar with close button and new thread button
│ [Search...]                 │  ← Search/filter
├─────────────────────────────┤
│ ex                          │  ← ProjectGroup header (folder set display name)
│   ⚙ Block decoration hei…  │  ← Thread entry (icon, title)
│     ♦ olivetti · 7:46 PM   │  ←   (agent name, timestamp)
│   ⚙ Hit testing returns…   │
│     ♦ rosewood · +21 -12   │
│   ⚙ Add a new tool block…  │
│     ♦ rosewood · +8 -3     │
│   + View More               │  ← Collapsed overflow
├─────────────────────────────┤
│ ex, zed                     │  ← Another project group
│   ⚙ Add soft wrap suppor…  │
│   ⚙ Thread view needs to…  │
├─────────────────────────────┤
│ zed                    🖥   │  ← Window icon = this project has a window
│   ⚙ Implement subagents…   │
│   ⚙ Project search over…   │
│   + View More               │
└─────────────────────────────┘

Context Menu (on Project Group header)

  • Remove Project — removes from active projects list
  • Collapse Project — toggles collapsed state for the group
  • New Thread — starts a new thread in this project
  • New Thread in... submenu:
    • Current Project — new thread reusing an existing workspace
    • New Worktree — new thread in a new git worktree

Thread Entry Interactions

  • Click — activates this thread's workspace in the current window
  • Hover — shows full path tooltip
  • Running indicator — animated dot for actively generating threads
  • Notification dot — thread completed while you weren't looking

Lifecycle

What the sidebar shows

The sidebar shows the union of:

  • The persisted active projects list (projects that have had threads)
  • Any currently windowed workspaces not yet in that list (ephemeral)

Each entry has a window indicator showing whether a window is currently looking at it.

When does a project enter the active list?

A project is persisted to the active list when the user creates a thread in it. This is the durable "save" moment. Before that, the project only appears in the sidebar because it has an open window — it's ephemeral.

When does a project leave the active list?

Manual removal only. The user clicks "Remove Project" (the X). That's it. No automatic removal based on time, inactivity, or window closing. The list is append-mostly.

What happens when you open a window?

The workspace appears in the sidebar immediately (as an ephemeral entry if it has no threads, or it matches an existing active entry if it does). The window indicator lights up.

What happens when you close a window?

  • If the project is in the persisted active list → it stays in the sidebar, just without the window indicator. Still visible, still accessible.
  • If the project was only ephemeral (open window, no threads) → it disappears from the sidebar. Nothing was ever persisted.

What happens when you click an inactive project in the sidebar?

A workspace is created for it (using the stored folder paths), associated with the current window, and displayed. The window indicator lights up.

What happens with multiple windows?

Each window has its own WindowRoot. The sidebar in each window shows the same global active projects list. A project can be displayed in multiple windows simultaneously. The window indicator shows all windows currently viewing that project.

What The Six Weeks of MultiWorkspace Work Actually Bought

The critical achievement was breaking the window-workspace coupling. Before that work, Window == Workspace was a hard assumption baked throughout the codebase. That decoupling is the foundation this new architecture stands on. Without it, none of this would be possible.

What changes is where the multiplexing lives — it moves from inside the window to outside it, at the global level. The decoupling itself was the right work. The specific topology of "N workspaces inside one window" was an exploration that informed the better topology of "N projects globally, windows as viewports."

The sidebar infrastructure (SidebarHandle, resize, focus management), the serialization plumbing (workspace IDs, session bindings), and the deep understanding of workspace lifecycle — all of that carries forward directly.

Addendum: The Inert Model Eliminates The Lazy Loading Problem

The original architecture called for every active project to be a live Entity<Workspace>, eagerly rehydrated at startup (N workspaces = N sets of language servers, file watchers, worktrees). This created a scaling concern and a planned WorkspaceEntry::Loaded/Unloaded enum optimization.

The inert model eliminates this entirely. The active projects list is just Vec<PathList> — loading it is trivial regardless of size. Live workspaces are only created on demand when the user clicks an entry or when a window opens. There is no rehydration step, no startup cost beyond reading a small database table, and no need for a WorkspaceEntry enum.

Addendum: Path Staleness and Reconciliation

There are two staleness concerns with the inert model:

Active Projects List Staleness

Since the active projects list stores PathList values (not live workspaces), folder renames on disk won't be reflected until the project is opened in a window. If the user renames /home/user/zed to /home/user/zed2 while no window is showing that project, the stored PathList still says zed. This is acceptable — the sidebar shows the last-known name, and when the user opens the project, the live workspace detects the rename and the stored PathList can be updated.

When a project does have a window open, the live workspace detects renames through file watching. The sidebar should update the stored PathList in ActiveProjects to match the live workspace's current paths, keeping the persisted list consistent with reality.

Thread DB Staleness

The thread database stores folder paths at thread-creation time. If a folder is renamed, existing threads in the DB still reference the old path. This means:

  • The thread was created against {zed}, the folder gets renamed to {zed2}.
  • The live workspace sees {zed2} (file watcher caught it) — its PathList changes.
  • The thread DB still says {zed}.
  • The derivation sees the workspace under "zed2" and the thread under "zed" — their PathLists don't match, so they don't group together.

The fix is straightforward: when a workspace detects a path change, it updates the thread DB to reconcile old paths with new ones. The live workspace knows both the old and new paths, so it can issue the update.

Folder renames are an edge case, so this doesn't need to be in the very first implementation phase. But it should be part of the active projects work — not deferred indefinitely.

Lifecycle Scenarios

A comprehensive walkthrough of every interaction and what happens to the three data sources and the sidebar.

Legend:

  • Active List = the persisted active projects list
  • Window State = the live window assignments
  • Sidebar = what the user sees

Window Operations

Opening a new empty window

User launches Zed, or hits Cmd+N for a new window.

  • A new Workspace is created with no worktrees.
  • Window State: new entry WindowId → Entity<Workspace>.
  • Active List: unchanged. No thread exists, nothing to persist.
  • Sidebar: shows an ephemeral entry (e.g., "Empty Workspace") with a window indicator. If the user closes this window without ever creating a thread, the entry vanishes.

Opening a project from the file system (File > Open, CLI, drag-and-drop)

User opens /home/user/zed in a new or existing window.

  • A Workspace is created (or reused) with the folder as a worktree.
  • Window State: WindowId → Entity<Workspace> with the zed folder.
  • Active List: unchanged — no thread yet.
  • Sidebar: shows "zed" as an ephemeral entry with a window indicator. If "zed" already exists in the active list (from a previous thread), the existing entry lights up with a window indicator instead.

Opening a recent project from the sidebar

User clicks a persisted project "zed" in the sidebar that has no window.

  • A new Workspace is created from the stored folder paths, attached to the current window.
  • Window State: current window's assignment changes to the new workspace.
  • Active List: unchanged — the entry already exists.
  • Sidebar: the "zed" entry now shows a window indicator. If the window was previously showing another project, that project's window indicator goes away (but it stays in the sidebar if it's persisted).

Closing a window (persisted project)

User closes a window that's showing "zed," which has threads and is in the active list.

  • The workspace may be kept alive (if threads are still running) or dropped.
  • Window State: the WindowId entry is removed.
  • Active List: unchanged. "zed" stays in the list.
  • Sidebar: "zed" remains visible but loses its window indicator. The user can click it later to reopen it.

Closing a window (ephemeral project, no threads)

User closes a window that's showing "my-experiment," which has no threads.

  • The workspace is dropped.
  • Window State: the WindowId entry is removed.
  • Active List: unchanged — "my-experiment" was never in it.
  • Sidebar: "my-experiment" disappears entirely. It was only there because the window was open.

Closing the last window (app quit)

User closes the final window or quits the app.

Lines 1–500 of 734.

Keyboard shortcuts

General

Show keyboard shortcuts
?
Focus the current search
/

Issues and pull requests

Open filters
f

Issues, pull requests and Inbox

Select next item
j↓
Select previous item
k↑
Open selected item
Enter
Dismiss filters or clear selection
Esc

Repository code

Go to file
t