Loom

中文说明

Loom is a versioned registry of portable AI-agent assets: skills, plugins, prompts, rules, agent profiles, hooks, and global instructions. It is not a daemon, a visual application, a timer, or a self-updating configuration service.

The repository separates shared assets from harness-specific assets:

assets/
  shared/                 # cross-harness skills, personas, and memory
  agents/<harness>/       # Codex, Claude, Gemini, Hermes, Grok, Cursor, etc.
catalog/
  manifest.json           # explicit asset-to-home mapping
  plugins/claude.json     # reproducible Claude marketplace/plugin catalog
bin/loom.mjs              # one-shot Bunx entry point

Install On Another Computer

Install Bun 1.1 or newer first (bunx is included), then run the repository directly. No Loom directory, background process, timer, or hook is installed.

bunx --bun github:yhyzgn/loom#main install

For a reproducible snapshot, replace #main with a commit hash, for example github:yhyzgn/loom#7615352.

Apply only selected harness assets, or target a test/home directory:

bunx --bun github:yhyzgn/loom#main apply --agent codex --agent claude
bunx --bun github:yhyzgn/loom#main install --home "$HOME"
bunx --bun github:yhyzgn/loom#main install --dry-run

Use --home for a test directory before changing a real home. --dry-run only prints planned writes. install and apply are equivalent one-shot operations; repeated runs overwrite the managed files listed in the manifest while leaving unrelated files in place. --agent can be repeated or given a comma-separated list.

On Windows PowerShell, use the native home variable:

bunx --bun github:yhyzgn/loom#main install --home "$env:USERPROFILE" --dry-run

Inspect the registry and validate its safety boundary:

bunx --bun github:yhyzgn/loom#main list
bunx --bun github:yhyzgn/loom#main doctor
bunx --bun github:yhyzgn/loom#main plugins list
bunx --bun github:yhyzgn/loom#main plugins install claude --dry-run

plugins install claude registers the catalog's marketplaces and installs its declared Claude plugins using the local claude executable. This is the only command that invokes another native CLI and can change Claude's local plugin state; use --dry-run to inspect it first. It deliberately does not copy plugin caches.

The current snapshot includes shared assets plus Codex, Claude, Gemini, Hermes, Grok, OpenCode, Trae, Qwen, Augment, CodeBuddy, Cline, Cursor, GitHub Copilot/GSD, Kiro, Junie, Kilo, OMP, and OMX-specific assets.

The entry point uses Node/Bun path APIs and has no POSIX-only shell dependency for install/apply. Windows, macOS, and Linux are covered by the verification workflow; plugins install claude additionally requires the native claude CLI on PATH.

Source Machine

import-local is a maintenance command for the machine whose global assets are being captured. Run it from a Loom checkout after changing skills or agent settings; it is not needed on a target machine that only consumes the published registry.

bun run import-local -- --from "$HOME"
bun test
bun run check

PowerShell equivalent:

bun run import-local -- --from "$env:USERPROFILE"

Review the generated diff before committing. catalog/manifest.json is the source of truth for asset-to-home mappings; catalog/inventory.json is generated metadata.

Safety Boundary

Loom imports portable text/assets only. It excludes API keys, credentials, OAuth/auth files, .env files, caches, databases, sessions, logs, lock files, package installs, generated runtime state, and legacy sync hooks. JSON, YAML, and TOML configuration is sanitized during import; an existing machine's sensitive configuration values are preserved when managed JSON, YAML, or TOML files are applied locally.

Plugin packages and marketplace clones are intentionally not vendored. Their identifiers, sources, and versions are kept in the catalog so another machine can recreate them through its native plugin CLI.

Maintaining The Registry

After intentionally changing global assets on the source machine, refresh the checked-in snapshot using the Source Machine workflow. doctor rejects catalog entries that are missing or contain credential-like values. Plugin packages and marketplace clones remain catalog references and are recreated through the native plugin CLI.

License

MIT