FAQ

General

What is Workloom?

Workloom is a package manager for AI workflows. It lets you distribute and manage AI agent configurations (Claude, Codex, Copilot, Gemini) across your organization, similar to how npm manages JavaScript packages. Instead of copy-pasting config files or maintaining custom sync scripts, you publish packages to a registry and pull them where needed.

How is it different from just committing config files to git?

Git commits config files, but doesn't version them independently, handle monorepos cleanly, or provide a trust model for third-party configs. Workloom gives you immutable versioning, trust classes, drift detection, and a renderer that produces provider-specific files from canonical assets. You can pull configs from multiple sources, control what auto-applies vs needs approval, and detect when local changes diverge from published packages.

Which AI providers are supported?

Currently supported: Claude (via .claude/ and CLAUDE.md), GitHub Copilot, OpenAI Codex, and Google Gemini. The renderer transforms canonical package assets into provider-specific file formats. Each provider has its own output directory and file conventions.

Do I need to change my existing AI configs?

No. Workloom works alongside your existing config files. The .loom/binding.toml file (committed to git) declares which packages you're using, and wl pull generates the provider files. You can keep hand-written configs and Workloom-managed configs in the same workspace. If you modify a Workloom-managed file, wl sync --check will detect the drift.

Is Workloom open source?

The CLI tool and core renderer are open source. Registry hosting is provided as a managed service, though you can run a private registry for your organization. All package metadata and content are content-addressed (SHA-256) for transparency.

What's the minimum team size where this makes sense?

It's useful for teams of 3+ developers who share AI workflows. Solo developers can use it to sync configs across machines or publish reusable patterns. The real value comes when you need to distribute updates, enforce standards, or pull third-party agent configs without manual copy-paste.

Setup & Usage

How do I install it?

npm install -g @workloom/cli
# or
pnpm add -g @workloom/cli

Then initialize a workspace:

wl init

This creates .loom/binding.toml (commit this) and .loom/state.json (add to .gitignore).

What happens during wl pull?

wl pull reads .loom/binding.toml, fetches packages from the registry, verifies content hashes, and runs the renderer to generate provider-specific files. It respects trust classes: trusted packages auto-apply, untrusted packages require explicit approval. Output files are written to .claude/, .copilot/, etc., based on your targets.

Can I override a package's settings locally?

Yes. Workloom generates base files, but you can layer local overrides on top. For example, if a package provides CLAUDE.md, you can create CLAUDE.local.md (gitignored) that takes precedence. The wl sync command will ignore local-only files unless they conflict with managed paths.

How does drift detection work?

Run wl sync --check in CI to detect if managed files have been modified locally. Workloom compares the generated output against what's on disk. If there's a mismatch, it exits with a non-zero status. Use wl sync (without --check) to regenerate files and resolve drift.

What if I modify a Workloom-managed file locally?

Workloom won't overwrite your changes until you run wl sync or wl pull again. The next wl sync --check will flag the drift. You can commit your changes to git, but they'll be overwritten on the next pull unless you remove that file from Workloom's management (edit binding.toml to exclude it).

Can I use Workloom in a monorepo?

Yes. Each workspace target (a directory in your monorepo) can have its own .loom/binding.toml. You can share some packages across all targets and use target-specific packages where needed. The CLI detects monorepo boundaries and operates on the current target by default.

Security & Trust

What's a trust class?

Trust classes control how packages are applied. trusted packages (e.g., from your org) auto-apply on wl pull. untrusted packages (third-party or experimental) require manual approval via wl approve <package>. This gates shell hooks, custom instructions, and other sensitive config from running without review.

Can a package silently add shell hooks?

No. Shell hooks and other risky assets (scripts, custom tools) are flagged during wl pull. If the package is untrusted, you'll see a prompt listing the hooks and must explicitly approve before they're written to disk. Even trusted packages log hook additions for audit trails.

How does the approval workflow work?

When you pull an untrusted package, Workloom shows a diff of what will be written and prompts for approval. You can approve once (wl approve <package>@<version>) or trust the publisher (wl trust <publisher>). Approved packages are recorded in .loom/state.json (gitignored), so each developer approves independently.

What data does Workloom send?

Workloom sends package names, versions, and content hashes to the registry over HTTPS. It does not send your source code, API keys, or workspace contents. The registry logs download counts for public packages. Private packages are only accessible to authorized org members.

Packages & Publishing

Who can publish packages?

Anyone with a Workloom account can publish public packages. Private packages require an org plan. You control package namespaces via your account or org scope (e.g., @myorg/my-package). Publishing requires authentication via wl login.

Can I have private packages?

Yes. Use wl publish --private to publish packages visible only to your organization. Private packages are pulled via org-scoped credentials. They follow the same trust model as public packages but aren't listed in the public registry search.

What happens when I yank a version?

Yanking a version (wl yank <package>@<version>) removes it from new installs but doesn't break existing users. Yanked versions still resolve if explicitly pinned in binding.toml, but wl pull will warn you. Use yanking for versions with security issues or broken assets.

How do release channels work?

Release channels (e.g., stable, beta, nightly) let you publish to different streams. Users opt in via binding.toml:

[packages]
"@myorg/my-agent" = { version = "^1.0.0", channel = "beta" }

Channels are independent version streams. A beta channel release doesn't affect stable users until you promote it.