# Your first workspace Source: https://docs.ideharmony.com/getting-started/first-workspace **Outcome:** a workspace open on a real repository, with more than one pane, and an understanding of what each level of the model is for. ## Prerequisites - Harmony installed ([installation](/docs/getting-started/installation) · [Windows](/docs/getting-started/windows) · [macOS](/docs/getting-started/macos) · [Linux](/docs/getting-started/linux)) - A git repository on disk you actually work in ## The three-level model Everything in the desktop hangs off three levels: | Level | What it is | Scope | |---|---|---| | **Workspace** | A named context with its own pane tree, working directory, and status | One project | | **Surface** | A tab within a workspace — terminal, browser, editor, diff, file tree, or a Harmony panel | One kind of view | | **Pane** | A leaf in the split tree | One process or view | A workspace is not a window and a pane is not an agent. A pane can hold a plain shell forever and never involve a model. ## 1. Create the workspace ```powershell cd path/to/project harmony desktop ``` **Expected result:** a window with one terminal pane, the working directory set to your project, and the git branch shown in the status bar. ## 2. Split it | Action | Shortcut | |---|---| | Split horizontally | Ctrl D | | Split vertically | Ctrl Shift D | | Move focus | Ctrl ←↑↓→ | | Cycle panes | Ctrl Tab | | Maximize a pane | Ctrl B then Z | On macOS, `mod` shortcuts use ⌘. The Ctrl B prefix is literal Ctrl on every platform, matching tmux. > [!NOTE] > A workspace holds a maximum of 20 panes. That cap is deliberate: past it, > terminal rendering and process supervision stop being predictable. ## 3. Add a second workspace Ctrl N creates one. Switch between them with Alt ↑ / Alt ↓. Give each workspace one project. Workspaces are the unit that agents, tasks, and worktrees are scoped to, so mixing two projects in one workspace makes later orchestration harder to reason about. ## 4. Close the window Close the desktop entirely, then reopen it: ```powershell harmony desktop ``` **Expected result:** your workspaces, panes, and scrollback return. The daemon kept them; the window was only a view. **Verify:** ```powershell harmony sessions list ``` ## Common recovery | Symptom | Fix | |---|---| | Panes render blank | [Daemon problems](/docs/troubleshooting/daemon) | | Workspace opened in the wrong directory | Close it and relaunch from the intended directory | | Shortcuts do nothing | Check whether Ctrl B prefix mode is armed; press Esc | ## Next - [Connect a provider](/docs/getting-started/connect-a-provider) - [Workspaces and surfaces](/docs/concepts/workspaces-and-surfaces) - [Keyboard shortcuts](/docs/desktop/keyboard-shortcuts)