Workspaces
The three-region shell, creating worktree-backed workspaces, the Files editor, the Git panel, and notebooks.
Day to day, you work inside a workspace. This page covers the app shell, how to import a project and create and switch workspaces, and the project tools you'll use most — Files, Git, and notebooks. 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, or drag a repository folder onto the sidebar. Importing an existing repository gives you a guided first run and creates a project — the repository-level container that owns your workspaces and the Files and Git tools.
The three-region shell
Cordy's window is built from three stable regions that don't move around under you:
| Region | Name | What it holds |
|---|---|---|
| Left | Project / Workspace navigation | Your projects and their workspaces |
| Center | Workspace canvas | Terminals, agents, notebooks, and editor/diff tabs |
| Right | Project Tools | Files, Changes (Git), and Graph |
Left: navigation
The left sidebar lists your work:
- a Workspaces overview button that opens a grid of every workspace across all projects;
- one group per project, expanding to its workspaces — each workspace row carries a status badge, including the running state of any agent in it; 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 is where you actually work. It shows either the Workspaces overview grid or the active workspace surface. A workspace surface hosts:
- terminal and agent panes, which can be split;
- a notebook pane; and
- editor and diff tabs.
A handful of recently used workspaces stay resident (kept mounted) so switching between them is instant and their terminals never miss a beat.
Right: Project Tools
The right sidebar has three tabs — Files, Changes, and Graph. These belong to the project, but what they show follows the active workspace's CodeTarget: switch to a workspace bound to a worktree, and Files and Git re-point at that worktree.
Creating and switching workspaces
Create a workspace
The New workspace dialog offers three ways to bind a workspace to code:
- Project root — work directly in the repository root.
- Existing worktree — pick from the repository's existing Git worktrees.
- New worktree — type a branch name, and Cordy creates a fresh worktree for it.
The new-worktree option is the one that unlocks parallel agents: each task gets its own branch and directory. See Concepts for why this matters.
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 Workspaces overview lists every workspace across all projects with its name, status, target, and last-updated time, plus search. Keyboard-driven switching (jump-to-number, next/previous, first/last) is covered in Shortcuts.
The workspace you had active is remembered across restarts and tray restores, so you return to where you left off — not to whichever workspace was created most recently.
Close vs. delete
Closing a workspace keeps it (and its worktree) for later; deleting is a separate, confirmed, destructive action that also removes the workspace's notes. Worktree-backed workspaces additionally distinguish "delete the record" from "delete the record and its worktree." See Workspace lifecycle for the full model.
Files and the editor
The Files tab is a file tree for the active workspace's code path. Its toolbar has New file, New folder, Refresh, and Collapse all, and each row shows a live Git status indicator (modified, added, deleted, renamed, untracked, and so on).
Clicking a file opens it in a syntax-highlighting editor as a tab in the center canvas (not in the sidebar). The editor:
- picks a language from the file's extension;
- saves with
Cmd/Ctrl+S(see Shortcuts); - guards against lost updates — if a file changes on disk after you open it (an agent or a Git operation edited it), saving prompts you to Reload or Overwrite, so you never 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.
Git diffs open the same way — as tabs in the center canvas.
Git
The Changes and Graph tabs give you a complete commit loop without leaving Cordy.
Changes
The Changes panel groups your working tree into Staged Changes, Changes, and Untracked Files, with a running +/− total in the toolbar. For each file you can open its diff, stage or unstage it, or discard it. Opening a diff gives you finer control:
- hunk-level staging — stage, unstage, or discard individual hunks, not just whole files;
- an inline commit form; and
- whole-file actions alongside the per-hunk ones.
A dedicated commit form takes a summary and an optional description and shows how many files are staged. The toolbar also has fetch, pull, and push, with ahead/behind counts shown next to the current branch.
Graph
The Graph tab is a read-only commit history for the current branch — a linear list showing each commit's subject, hash, author, date, and any branch or tag labels. It is for reviewing history, not for branching operations.
Notebooks
Each workspace has its own notebook — a place for notes, plans, findings, and reusable context that belongs with the task. Notebooks are:
- per-workspace (titled "Notes" by default), edited in a rich-text pane in the workspace canvas;
- toggled with the notes action or the Focus notes shortcut (
Cmd/Ctrl+Right, see Shortcuts); and - autosaved and persisted with the workspace, so a note comes back — along with whether its pane was open — when you reopen the workspace, even after a restart.
Because a notebook travels with its workspace, it is a natural home for the context around a long-running agent task. See Privacy for where notes are stored on disk.