openidea/docs/workspaces-and-window-groups.md

Workspaces and project window groups

A workspace opens several local project folders in one IDE session. A window group switches between independent IDE sessions; a member can itself contain a workspace.

Workspace

Use File → New Workspace…. Choose a name and a separate directory for the workspace, then add project folders. File → Open Workspace… opens that directory again. File → Manage Workspace… changes its name or linked projects. Removing a link leaves the project's files and open editor buffers intact.

When opening another local project, choose Attach to add it to this window. A plain project becomes a workspace automatically under the IDE app data directory's workspaces folder, named after the current project (with a unique directory suffix when needed). The existing editor session carries over after the unsaved-changes guard. Don't ask again remembers Attach; change it in Settings → System Settings → Project → Open project in. Already linked projects are revealed in Project view. Right-click a non-first linked root and choose Remove from Workspace to unlink it without deleting files.

The workspace stores its manifest in .openidea/workspace.json:

{
  "version": 1,
  "name": "Full stack",
  "projects": ["/work/frontend", "/work/backend"]
}

Paths in an existing manifest may be relative to the workspace directory. New and updated manifests use canonical absolute paths. Missing previously linked folders are retained so they can be reconnected or removed. Nested workspace manifests are rejected.

Linked folders appear as roots in Project view and participate in indexing, Find in Files, Git repository discovery and language-server root selection. Detected and saved run configurations have project-qualified names and use their member's working directory and launch settings. Build Project combines the linked projects' build plans; Compile File targets its owning project. Workspace editor/settings state belongs to its own directory. Each member retains its repository and project configuration.

The specialized Maven/Gradle tool-window model still describes the workspace directory itself; it does not yet aggregate independent member models. Workspace creation and management currently target local folders. To link independent Gradle builds in one Gradle tree, open their parent folder as an ordinary project instead of creating a Workspace manifest, then use Link Gradle Projects… in the Gradle toolbar or Find Action.

Linked Gradle builds in a project

In an ordinary project window, Link Gradle Projects… accepts one or more settings.gradle, settings.gradle.kts, build.gradle, or build.gradle.kts files. Each linked build has its own root in the Gradle tool window. Its tasks, dependencies, wrapper, working directory and sync cache stay separate, even when another build has the same :app project or task names. Included builds remain under the build that includes them.

Right-click a build root for Reload Gradle Project or Unlink Gradle Project. Unlinking only removes the IDE connection; it does not delete files or saved run configurations. The Link button remains available after the last build is unlinked. Linked builds may live outside the opened folder.

Links are saved in project settings as languages.java.gradle.linkedProjects. Until links are configured, existing automatic discovery is unchanged. An explicit empty list means that no Gradle builds are linked. Opening the project again restores its links. A folder first opened by an older version may need one fresh sync because independent builds now have separate caches.

Window group

Open two project windows, then use Window → Merge All Project Windows. The project tabs occupy their own row below the main toolbar. Click a tab or use Next/Previous Project Tab to switch; drag tabs to reorder them. The default shortcuts are ⌥⌘PageDown/PageUp on macOS and Ctrl+Alt+PageDown/PageUp on Windows/Linux.

Use the tab's close button to close that project, or Move Tab to New Window to detach the current tab. Right-click a tab for Close Other Tabs, Close Tabs to the Left and Close Tabs to the Right, which close the projects one at a time and keep the clicked tab; cancelling one project's unsaved-changes prompt leaves it and the rest open. The same commands are in the Command Palette and can be assigned shortcuts. Closing uses the existing unsaved-changes guard. Quit visits project windows in sequence so a hidden project's prompt is visible. Groups restore when Reopen last project is enabled.

The grouping model lives in ide-workspace, independently of project ownership. The desktop adapter keeps each member's WebView and backend services alive, presents the selected window at the group's position/size, and hides its peers. Hidden members are kept at the selected window's frame and display (and follow it after a move or resize), so switching projects only changes which window is visible. This is an application-drawn tab strip, not the macOS native tab strip. Its persistence is application-local in window-groups.json. Language servers, terminals, editor buffers and settings remain independent between group members.

Validation

Automated coverage includes workspace manifest validation and persistence, missing members, independent language-server initialization roots, cross-root search/repositories/run directories, document preservation after unlinking, window-group membership/order, dialog failures and tab keyboard controls.

Tauri MCP validation on macOS covered workspace creation and management, opening same-named files from both projects, cross-project search, running both projects, tab selection/reordering/detachment, unsaved close cancellation, full-screen switching and application restart restoration. Windows/Linux native-window behavior has not been visually tested.