Workspace model

Desk’s workspace model is intentionally small. A manifest contains projects; projects contain groups; groups contain sessions.

​

Projects

A project represents a working tree or root directory. It gives Desk a stable scope for sessions, editor roots, Git discovery, and group organization. Use one project per repository when your agents work in different repos. Use one project with multiple groups when several agents work in the same repo.

​

Groups

A group is a cell-grid workspace inside a project — each cell holds a session rendered as a native agent chat or a terminal. Groups are useful for:

• separating roles such as frontend, backend, reviewer, and release
• keeping noisy commands away from agent sessions
• switching between related session grids
• preserving layout and selected sessions per workstream

Each group has a layout such as one cell, a grid, or custom split sizes. Desk persists layout changes to the manifest.

​

Sessions

A session describes one Moor-backed process. It can be:

• a managed Codex session
• a managed Claude session
• a managed OpenCode session
• a Bash shell
• a custom command

Managed agent sessions get Desk launch flags, permission handling, resume capture, attention hooks, and optional LSP MCP wiring. Custom commands run as the command you provide.

​

Session ids

Every session has a durable sessionId. Desk preserves an existing id or mints one from the session name when you add or migrate a session. The id is the shared key for:

• the Moor control socket
• terminal generation and snapshot state
• channels membership and delivery queues
• attention, resume capture, and agent event routing

​

Resume ids

Resume ids belong to the agent CLI, not to Moor. Desk stores known resume ids in the manifest and can also harvest them after a first turn for managed agents. Use resume ids when you want a restarted agent CLI to reconnect to the same conversation. Bash and custom command sessions do not use agent resume ids.

​

Startup behavior

desk up reads the manifest, checks the configured Moor control sockets, and starts only the missing sessions. It does not replace running sessions. Use desk up --dry-run before changing a large fleet.

​

Browser state

The browser stores selected views, open editor tabs, panel sizes, and UI preferences separately from Moor process lifetime. If you reload the browser, Desk reconnects to the running sessions through the binary terminal transport.

​

Next steps

• Build a real manifest in Create an agent fleet.
• Read Configuration for every manifest field.
• Read Operations for session controls and health checks.