Core Concepts

The Project, Workspace, and CodeTarget model behind Cordy Desktop.

Cordy Desktop is built on a small object model. Three objects — Project, Workspace, and CodeTarget — explain most of how the app behaves: why views follow the workspace you are in, which files your agents share, and what survives a restart.

The model at a glance

ObjectWhat it isOwns
ProjectAn imported local Git repositoryRepository identity, Files tooling, Git tooling
WorkspaceA persistent, personal work context inside a projectIts CodeTarget, terminal tabs, note, agent runs, layout
CodeTargetThe copy of the code a workspace operates onThe project root

The relationship is strictly hierarchical: a Project contains many Workspaces, and every Workspace binds exactly one CodeTarget.

Project

A Project is the repository-level root object. You create one by importing an existing local Git repository (see Workspaces for the import flow). A Project:

  • represents one imported local codebase,
  • defines the Git repository boundary,
  • owns many workspaces, and
  • owns the project-level tools — the Files panel and the Git panel.

A Project records where the repository lives on disk and its Git root. The branch you work on is whatever that checkout has checked out.

Workspace

A Workspace is the execution context inside a project — the thing you actually work in, day to day. Each workspace:

  • is a personal, user-controlled work context,
  • binds exactly one CodeTarget (below),
  • organizes its own terminal tabs, note, and CLI agent runs,
  • remembers its layout (open panels, split panes, the active center surface), and
  • persists across sessions until you close or delete it.

Workspace lifecycle

A workspace has a status of active, closed, or archived. Closing a workspace is not the same as deleting it — closing keeps the record so you can return later. Deleting is a separate, confirmed action that removes the workspace's note and chat history from Cordy. Neither action touches files in the repository.

CodeTarget

A CodeTarget defines which directory a workspace operates on. It has one shape:

  • project-root — the workspace works directly in the project's own checkout.

Everything that is "about the code" resolves through it: the terminal cwd, the file tree, the Git status, and each agent's working directory.

All workspaces of a project therefore work on the same files. Two agents in two workspaces of the same project edit one checkout, and a branch switch in one workspace changes the files for all of them.

Separate checkouts

Cordy no longer creates or manages Git worktrees (since 0.5.4). For a separate checkout:

  1. Run git worktree add <folder> <branch> yourself.
  2. Add that folder to Cordy as its own project with Add repository.

Worktree workspaces from an earlier version are converted on first launch of 0.5.4 or later. They switch to the project's own checkout, the worktree folder on disk is left untouched, and the previous data file is kept as a backup next to the new one. To keep working in such a worktree, add its folder as a project.

Ownership and view scope

Two rules explain why the interface shows what it shows:

  • Files and Git are project-level tools. They belong to the Project, not to any single workspace.
  • Their view follows the active workspace. When you switch to a workspace in another project, the file tree and Git panel re-point at that project's checkout.

What persists, and what is live

Cordy separates state into layers. Knowing which is which explains what survives a restart:

LayerExamplesDurability
Persistent truthProjects, workspaces, notes, layout, custom agent presets, custom themesStored on disk under your user-data directory; survives restarts
Runtime resourcesLive PTYs, running agents, Git/file observations, metricsReattached while the runtime survives; a full quit ends processes
Terminal history snapshotSerialized terminal screen/scrollback without alternate-screen modesStored in local renderer storage for cold restore above a fresh shell
Derived viewsSidebar tree, status badges, the current diff viewComputed from the layers above; never a source of truth

The important consequence: your terminals and running agents are runtime resources owned by a background Rust runtime, so they survive window reloads and (on Windows) closing to the tray — while your projects, workspaces, and notes are persistent truth on disk. See Runtime for how durability works, and Privacy for exactly what is stored where.

  • Workspaces — the day-to-day shell: sidebar, header, and panes.
  • Notes — the workspace note.
  • Agents — launching CLI agents into workspaces.
  • Runtime — why terminals and agents are durable.