Skip to main content

Quickstart

This guide walks you through the core Workloom loop: bind a workspace, sync packages, and inspect the result.

Current status

Workloom currently uses in-memory stores and a fixture registry. No external database or hosted service is required. Everything runs locally.

1. Start the API server​

pnpm dev

This starts the Fastify API server on port 3001 and the Next.js web app on port 3000.

2. Log in (dev mode)​

wl login

In development mode, the server auto-approves device authorization. You will see a device code and verification URL — the token is issued immediately without manual approval.

3. Create a package​

Use the API or web app to create a package. Here is an example using curl:

# Create a package
curl -X POST http://localhost:3001/packages \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $(cat ~/.config/workloom/credentials.json | jq -r .accessToken)" \
  -d '{
    "name": "@acme/security-review",
    "orgId": "acme",
    "description": "Security review skill for code analysis",
    "providers": ["claude", "codex"],
    "visibility": "public"
  }'

4. Publish a version​

wl push .claude/skills/security-review \
  --package @acme/security-review \
  --bump minor

This detects local asset files, computes SHA-256 hashes, uploads objects, and creates a draft package version.

5. Initialize a workspace​

cd /path/to/your/repo
wl init

This creates a .loom/binding.toml file that links your local directory to a workspace identity.

6. Bind to a workspace​

wl bind --workspace acme/platform-api

7. Pull and render​

wl pull

The CLI fetches the workspace manifest, resolves packages, downloads objects, and renders provider-specific files:

Installed:
  @acme/security-review@1.0.0

Rendered:
  .claude/skills/security-review/SKILL.md
  .claude/settings.json
  AGENTS.md
  .codex/config.toml

Status: clean

8. Check status​

wl status

Shows installed packages, rendered files, and any drift from the desired state.

9. CI enforcement​

Add this to your CI pipeline:

wl sync --check

Exits 0 if all AI config files match the desired workspace state. Exits non-zero if files are stale, missing, or drifted.

Next steps​