Your first workspace
Open a real repository, split panes, and understand the workspace, surface, and pane model.
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 (install on Windows)
- 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
cd path/to/project
nala 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:
nala desktop
Expected result: your workspaces, panes, and scrollback return. The daemon kept them; the window was only a view.
Verify:
nala sessions list
Common recovery
| Symptom | Fix |
|---|---|
| Panes render blank | Daemon problems |
| 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 |