Luwu is an early-stage configuration orchestrator for dotfiles, developer tools, and agent configuration.
It is intended to make configuration drift explainable and repairable without pretending that every difference should be overwritten. Luwu explores explicit resource semantics, semantic drift, field ownership, controlled reverse sync, and narrow external providers.
The project is an early developer preview. A manifest declares profiles,
packages, layered public inputs, and resources. inspect and plan are
read-only; writes require explicit confirmation. Start with the isolated
example below and consult the current verified scope before
selecting a real target.
The preview requires Python 3.12+ and uv. The synthetic profile fixture lives
under tests/fixtures/dotfiles_profile. Copy it to a temporary directory so
apply does not modify fixture data, and point HOME there so nothing outside
the copy is touched:
uv sync
demo_dir="$(mktemp -d)"
trap 'rm -rf "$demo_dir"' EXIT
cp -a tests/fixtures/dotfiles_profile/. "$demo_dir"/
export HOME="$demo_dir/home"
uv run luwu plan --manifest "$demo_dir/luwu.toml" --profile synthetic
A fresh profile needs an explicit accept for structured templates before
apply --yes writes them, and an explicit adopt for a copy or text
template whose target already exists. Symlink resources, the default
deployment, need none, a copy or text template with an absent target is
created by apply, and a confirmed apply advances the baselines it wrote. The
isolated profile fixture guide
walks through the complete loop, including reverse sync.
Read the current reference for the manifest, CLI, JSON, and safety contract, and implementation status for the verified scope and open limits. The reference and status documents are the authority for current capabilities; this page intentionally stays at user-entry-point level. The per-target Dotter handoff workflow applies before a real target is managed.
Run the deterministic test suite with:
uv run --locked python -m unittest discover -s tests -t . -v
- Product direction
- Current command and manifest reference
- Implementation status
- Current internal design
- Development and release workflow
- Delivery roadmap
- Changelog
- Agent and maintainer entry point
Documentation ownership and single-source-of-truth rules are defined in
AGENTS.md.
Luwu is an independent implementation inspired by the concepts and workflow of Dotter. It does not copy or include Dotter's source code.