Core Concepts

Cordy Desktop is built on a small, deliberate object model. Three objects — Project, Workspace, and CodeTarget — explain almost everything about how the app behaves: why views follow the workspace you are in, how several agents can work at once without colliding, and what survives a restart.

The model at a glance

Object	What it is	Owns
Project	An imported local Git repository	Repository identity, Files tooling, Git tooling
Workspace	A persistent, personal work context inside a project	Its CodeTarget, terminal tabs, notebooks, agent runs, layout
CodeTarget	The specific copy of the code a workspace operates on	A pointer to the project root, or to a Git worktree

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. It does not, by itself, decide which branch or worktree you are working in — that is the job of the active workspace's CodeTarget.

Workspace

A Workspace is the core 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, notebooks, and CLI agent runs,
• remembers its layout (open panels, split panes, the active center surface), and
• persists across sessions until you explicitly close it.

Workspace lifecycle

A workspace has a status of active, closed, or archived. Closing a workspace is not the same as deleting it — closing preserves local continuity so you can return later. Deletion is a separate, explicitly confirmed action. For worktree-backed workspaces there are three distinct levels:

• Close workspace — keep the record and its worktree; just stop showing it.
• Delete workspace — remove the workspace record but leave the Git worktree on disk.
• Delete workspace and worktree — remove both.

A workspace is not the same thing as a Git worktree. A worktree is one way a workspace can bind to code, not the workspace itself.

CodeTarget

A CodeTarget defines which physical copy of the code a workspace is actually operating on. It has two shapes:

• project-root — the workspace works directly in the repository root.
• worktree — the workspace works in a dedicated Git worktree: its own checked-out branch, in its own directory.

CodeTarget exists to decouple two ideas that are easy to conflate:

• the workspace — your durable, personal work context, and
• the code path — the actual directory used as the working tree for terminals, the Files and Git views, and every agent's working directory (cwd).

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

Parallel, worktree-backed workspaces

This is the payoff of the model. Git worktrees let one repository have several working trees checked out at once, each on its own branch. Cordy maps that directly onto workspaces. You can create a workspace on:

• the project root, for quick, in-place work;
• an existing worktree, to resume a branch already checked out elsewhere; or
• a new branch worktree, to start an isolated task from scratch.

Because each worktree-backed workspace has its own directory and branch, several tasks — and several CLI agents — can proceed at the same time without stepping on each other or colliding on your main branch. One agent can refactor in one worktree while another runs tests in a second, and neither touches the other's files. See Agents for launching agents into these workspaces.

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 current view follows the active workspace's CodeTarget. When you switch workspaces, the file tree and Git panel re-point at that workspace's code path — the project root, or a specific worktree.

So the right-hand Project Tools are, in product terms, project tools; but what you actually see in them reflects whether the active workspace is bound to the project root or to a worktree. This keeps a correct repository mental model while showing you the working context you are really in.

What persists, and what is live

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

Layer	Examples	Durability
Persistent truth	Projects, workspaces, notebooks, layout, custom agent presets, custom themes	Stored on disk under your user-data directory; survives restarts
Runtime resources	Terminal sessions (PTYs), running agents, Git and file snapshots, live metrics	Owned by the durable runtime; reattached or rebuilt, never written into the snapshot
Derived views	Sidebar tree, status badges, the current diff view	Computed from the two 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.

Related pages

• Workspaces — the day-to-day shell: Files, Git, and notebooks.
• Agents — launching CLI agents into workspaces.
• Runtime — why terminals and agents are durable.