loom

loom is a preview-first dotfiles workflow CLI built on top of chezmoi. It keeps one repo as the source of truth, lets you keep editing live files, and helps you discover, inspect, track, ignore, sync back, and apply changes with explicit control.

The npm package name is @kitsunekode/loom. The installed executable stays loom.

Why it exists

chezmoi is excellent at rendering one source repo onto scattered files in $HOME, but its raw commands are still a bit low-level for day-to-day "what changed and what should I do with it?" flows.

loom adds that missing layer:

• preview-first workflows instead of surprise mutation
• human-readable discovery of managed, unmanaged, ignored, and template-backed files
• stable --json output for agents and automation
• .loomignore files that can live at the repo root or near noisy subtrees
• no extra tracking database beyond your Git repo and chezmoi

Design goals

• keep chezmoi as the engine
• keep git as the review and history layer
• default every mutation to preview-first
• avoid partial local file corruption by validating before mutation and using atomic local file writes where loom edits files itself
• keep startup fast and dependencies minimal

Install locally

bun install
bun run build
./bin/loom doctor

Optional global link:

bun run link:global

Versioning with Changesets

loom uses Changesets for release intent and version bumps.

Normal flow:

bun run changeset
git add .changeset
git commit -m "feat: ..."

When you're ready to cut a release version:

bun run version-packages
git add package.json bun.lock .changeset
git commit -m "chore: version packages"

Publish to npm

The repo is ready for npm-style packaging:

• package.json exposes bin/loom
• files keeps the published package minimal
• prepack builds dist/loom.js

Before publishing:

bun run changeset:status
bun run check
npm pack --dry-run --ignore-scripts
bun run release:dry-run

The automated publish flow lives in /.github/workflows/release.yml. It is configured for npm trusted publishing with GitHub OIDC, not NPM_TOKEN.

Before the first real publish, configure a trusted publisher on npm for:

• GitHub user or org: KitsuneKode
• Repository: loom-cli
• Workflow filename: release.yml

See docs/releasing.md for the full release checklist.

Important:

• pending changesets block the automated publish workflow
• trusted publishing requires a GitHub-hosted runner and a matching npm trusted publisher configuration
• once versions are cut and no changesets are pending, the main branch release workflow can publish the new npm version

Quick start

Initialize a repo-local config in a dotfiles repo:

loom init --write

Inspect what changed:

loom status
loom diff ~/.config/zsh ~/.config/hypr
loom discover ~/.config/hypr

Sync live edits back into the repo:

loom pull ~/.config/zsh ~/.config/hypr
loom pull --write ~/.config/zsh ~/.config/hypr

Track a new config file:

loom track ~/.config/zed/settings.json
loom track --write ~/.config/zed/settings.json

Add a subtree-local ignore file:

loom ignore add --scope ~/.config/hypr 'shaders/.compiled.cache.glsl'
loom ignore add --scope ~/.config/hypr --write 'shaders/.compiled.cache.glsl'

Core model

• git: review, commit, push, branch, revert
• chezmoi: source/destination mapping, add, re-add, apply, templates, encryption
• loom: discovery, inspection, ignore ergonomics, preview-first mutation

Commands

• loom init [--write]
• loom doctor [--json]
• loom config show [--json]
• loom status [paths...] [--json]
• loom diff [paths...]
• loom discover [paths...] [--json]
• loom inspect <paths...> [--json]
• loom pull [paths...] [--write] [--json]
• loom apply [paths...] [--write] [--json]
• loom track <paths...> [--template|--encrypt|--exact|--follow|--interactive] [--write]
• loom ignore add --scope <dir> <patterns...> [--write]
• loom ignore list <path> [--json]
• loom source <paths...>
• loom managed [--json]
• loom unmanage <paths...> [--write]

See docs/architecture.md, docs/config-reference.md, and docs/workflow.md for the full model.