Workspaces

Import repositories, create, rename, switch, close, and delete workspaces, and find your way around the app shell.

Day to day, you work inside a workspace. This page covers the app shell, how to import a project, and how to create, switch, and remove workspaces. For the model behind projects, workspaces, and code targets, see Concepts.

Importing a project

Cordy works on local Git repositories. Add one from the left sidebar's Add repository action, press Ctrl+Shift+O, or drag a repository folder onto the sidebar. Importing a repository creates a project — the repository-level container that owns your workspaces and the Files and Git tools.

To work on a second checkout of the same repository, create it with git worktree add and import that folder as its own project.

The three-region shell

RegionNameWhat it holds
LeftProject / Workspace navigationYour projects and their workspaces
CenterWorkspace canvasTerminals, agents, the note, the browser, and editor/diff/preview tabs
RightProject ToolsFiles, Changes, Graph, and Search

Left: navigation

The left sidebar lists your work:

  • a Workspaces button that opens an overview of every workspace across all projects, with search;
  • one group per project, expanding to its workspaces. Each workspace row carries a status badge, including the status of any agent in it; clicking an agent badge focuses that agent's tab; and
  • a footer with Add repository, Settings, the theme toggle, and About.

It collapses to a narrow rail when you want more room, and accepts dropped repository folders for import.

Center: the workspace canvas

The center shows either the Workspaces overview or the active workspace surface. A workspace surface hosts:

  • terminal and agent tabs, which can be split and arranged;
  • the workspace note pane;
  • an optional browser pane; and
  • editor, diff, and media preview tabs.

The workspace header shows the workspace name and the subtitle project root · <path>. Its actions are New (new workspace), Notes, Browser, Duplicate, Fullscreen row / Restore row, and Close.

A few recently used workspaces stay mounted, so switching between them is instant and their terminals keep receiving output.

Right: Project Tools

The right sidebar has four tabs — Files, Changes, Graph, and Search. They follow the active workspace. See Project Tools for complete workflows.

Creating and switching workspaces

Create a workspace

Choose New in the workspace header, the + that appears when you hover a project group in the sidebar, Cmd/Ctrl+Shift+↓, or New workspace in the command palette. Cordy creates a workspace in the project's own checkout immediately; there is no target picker.

Duplicate in the header (Cmd/Ctrl+D) duplicates the active workspace in the same project.

Rename a workspace

Double-click the workspace title, or use Rename workspace in the command palette.

Switch workspaces

Click a workspace in the sidebar to switch to it. For an already-open workspace this is instant; a closed one is reopened first. The command palette lists Switch to workspace: <name> for the other workspaces of the active project. Keyboard switching (jump-to-number, next/previous, first/last) is covered in Shortcuts.

The workspace you had active is remembered across restarts and tray restores.

Close vs. delete

  • Close (header action, Cmd/Ctrl+Shift+W, or Close workspace in the palette) keeps the workspace record so you can reopen it later.
  • Delete uses the trash icon that appears when you hover a workspace row. Cordy asks "Delete workspace <name>? This removes its notes and chat history from Cordy." Deleting does not touch files in the repository.

Files and the editor

Clicking a file in Files opens it as a tab in the center canvas. Images, SVG, video, and audio open in a preview tab instead of the text editor. The editor:

  • picks a language from the file's extension;
  • saves with Cmd/Ctrl+S and finds with Cmd/Ctrl+F;
  • guards against lost updates — if a file changed on disk after you opened it (an agent or a Git operation edited it), saving asks before it overwrites, so you do not silently clobber an agent's work; and
  • opens non-UTF-8 files read-only to avoid corrupting their bytes, and treats binary or very large files as non-editable.

See Project Tools for the file tree, Git, Graph, and Search.

Notes

Each workspace has one note, a block-editor document for plans, findings, and context that belong with the task. Open it with Notes in the workspace header or Focus notes (Cmd/Ctrl+→). See Notes.

When a pane fails

If one pane hits an error while drawing, only that pane shows the error, with a Reload pane (or Reload note) button. The rest of the window keeps working.

  • Concepts — projects, workspaces, and CodeTargets.
  • Agents — launching agents into workspaces.
  • Shortcuts — keyboard navigation and the command palette.