Workspaces

A workspace binds a repository, monorepo, folder, or arbitrary unique key to a set of packages and rendering configuration.

What a workspace contains

workspaceId: wksp_platform_api_01
orgId: acme
name: Platform API
binding:
  type: git-repository
  gitRemote: git@github.com:acme/platform.git
targets:
  - id: root
    path: "."
    packages:
      - "@acme/base-guidance@^2.0.0"
    providers: [claude, codex]
  - id: frontend
    path: "apps/web"
    packages:
      - "@acme/react-skill-pack@^3.0.0"
    providers: [claude, codex, copilot]

Bindings

A binding links a local directory to a remote workspace. The binding file is committed to the repo:

# .loom/binding.toml
workspace_id = "wksp_platform_api_01"
registry_url = "https://loom.acme.com"
mode = "generated-local"

Binding types:

Type	Use case
Git repository	Standard repo, binding committed
Folder	Non-repo directory, arbitrary path
Unique key	CI, service, or non-filesystem target

Targets

Targets define sub-paths within a workspace for monorepo support. Each target has its own package selection and provider list.

The root target (.) applies to the repository root. Additional targets like apps/web or services/api get their own rendered files at those paths.

Revisions

Every workspace change — adding a package, changing a version constraint, updating target mappings — creates a new revision. Revisions are monotonically increasing integers.

workspace acme/platform-api revision 41
workspace acme/platform-api revision 42
workspace acme/platform-api revision 43

The lock file records which revision was last synced locally. wl status compares local revision against remote to detect workspace-level drift.

Local files

After wl pull, your workspace contains:

File	Purpose	Committed?
.loom/binding.toml	Workspace pointer	Yes
.loom/lock.json	Resolved package versions	Policy-driven
.loom/state.json	Local sync state, file ownership	No (gitignored)
Provider files (.claude/, AGENTS.md, etc.)	Rendered output	Policy-driven