create-workspace

Create Workspace

This skill helps you create and configure .clave workspace files for the Clave desktop app — a multi-session terminal manager built on Electron.

What is a .clave file?

A .clave file is a JSON file that defines one or more groups. Each group contains sessions (terminal instances) and terminals (quick-action buttons with pre-configured commands). When dropped into Clave or loaded via the Workspaces settings, these groups become launchable templates.

Templates live in the group picker — a full-screen dialog opened from the grid icon beside the Sessions heading in the sidebar. Clicking a group stamps out a fresh one every time; it never links back to the running group. The picker shows one card per group, with a search field, and:

• Groups templates under their category as section headers. Uncategorized templates render first, then categories alphabetically. There is no manual ordering — if you need a specific order, name the categories so they sort that way.
• Hides groups marked "toolbar": true (those render as icon buttons in the top toolbar instead).
• Shows a search box once there are more than 5 templates.

(The old inline pinned-groups grid in the sidebar is now only a drop target for dragging groups and .clave files.)

Single-group vs multi-group

A .clave file can define either a single group or multiple groups:

Single-group (e.g. my-project.clave):

{
  "$schema": "clave/1.0",
  "name": "My Project",
  "cwd": ".",
  "color": "blue",
  "sessions": [...],
  "terminals": [...]
}

Multi-group / workspace (e.g. workspace.clave):

{
  "$schema": "clave/1.0",
  "groups": [
    { "name": "Group A", "cwd": ".", ... },
    { "name": "Group B", "cwd": "../other", ... }
  ]
}

The format is auto-detected: if the top level has a groups array, it's multi-group. Otherwise, it's single-group.

Path resolution

All cwd and logo paths in a .clave file are relative to a root directory, which is not always the file's own folder: