Workspace Spec

Workspace as Code

Your entire development environment — terminals, commands, editor and agents — described by a single file you commit with your repo: .termpuzzle/workspace.yaml. The app writes it for you.

Why a file

A workspace that lives in git travels with your repo. New laptop, new branch, new teammate — the whole environment comes back with a clone. The UI is a convenience; the source of truth is a file you can read, diff and review.

Example

.termpuzzle/workspace.yaml

version: 1
name: my-app
layout: grid

terminals:
  - label: api
    cwd: ./services/api
    command: npm run dev
  - label: web
    cwd: ./apps/web
    command: vite
  - label: claude
    cwd: .
    command: claude
    role: ai-agent

editor:
  app: vscode   # or cursor, insiders
  position: right

Fields

name, layout — the workspace identity and how windows are arranged.
terminals[] — each terminal's label, working directory (cwd) and command. A terminal with role: ai-agent is treated as an agent window.
editor — which editor to open (vscode, cursor, …) and its position in the layout.

See Architecture for how the restore engine reads this, or the docs to get started.