Skip to main content

Getting Started

Get Workloom running in your project in under 5 minutes.

Prerequisites​

  • Node.js >= 22
  • A git repository (monorepo or single-app)

Installation​

npm install -g @workloom/cli

Or with your preferred package manager:

pnpm add -g @workloom/cli
yarn global add @workloom/cli

Initialize Your Project​

cd your-project
wl init

This creates a .loom/binding.toml file — your project's connection to a Workloom workspace.

# .loom/binding.toml
[workspace]
org = "my-org"
name = "frontend-team"

[targets.root]
path = "."
providers = ["claude", "codex"]

Authenticate​

wl auth

This opens a device authorization flow. For CI environments, use service account tokens instead.

Bind to a Workspace​

wl bind my-org/frontend-team

This connects your local repo to your team's workspace in the Workloom registry. The workspace defines which packages and versions your team uses.

Pull Your Configuration​

wl pull

That's it. Workloom:

  1. Fetches your workspace's desired state
  2. Resolves the render plan (packages → providers → files)
  3. Renders provider-specific config files
  4. Writes ownership metadata for drift tracking

You'll see output like:

✓ Resolved 3 packages for workspace "frontend-team" (revision 12)
✓ Rendering for targets: root, apps/web, apps/api
  → Claude: CLAUDE.md, .claude/settings.json, .claude/skills/review.md
  → Codex:  AGENTS.md, .codex/config.toml
✓ Wrote 5 files, updated .loom/state.json

Verify in CI​

Add drift checking to your CI pipeline:

# .github/workflows/drift-check.yml
name: AI Config Drift Check
on: [pull_request]
jobs:
  drift:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npm install -g @workloom/cli
      - run: wl sync --check

wl sync --check exits non-zero if local files don't match the workspace's desired state. Your team will never silently drift again.

What's Next?​

  • Learn about Packages — the core unit of Workloom
  • Understand Workspaces — how teams organize and assign packages
  • See how Providers work — one package, multiple rendered outputs
  • Set up Drift Detection — catch problems before production
  • Read the Team Lead Guide for publishing and managing configs