Deployment¶
Source: hooks/ways/meta/deployment/deployment.md
Frontmatter
| Field | Value |
|---|---|
description |
How agent-ways itself deploys into the home config dir — ~/.claude as a thin projection of an XDG application (source in $XDG_DATA_HOME/agent-ways), how the agent-ways installer/update/ways manage repair work under it, how to spot a legacy pre-1.0 in-place agent-ways clone that must ways migrate instead of pull, and where the migrator lives now that 1.9.0 removed it from the binary — surfaced only when installing, updating, migrating, or reconciling agent-ways itself, or resolving an existing ~/.claude conflict during agent-ways setup |
vocabulary |
agent-ways ~/.claude thin projection XDG application $XDG_DATA_HOME/agent-ways ways manage repair reinstall ways migrate reproject legacy in-place clone pre-1.0 agent-ways projected roots settings.json merge curl bash agent-ways installer existing .claude clobber subdirectory topology ADR-142 activation opt-out reprojection disabled adopters re-materialize |
pattern |
agent-ways|~/.claude|existing .?claude|ways (manage|reconcile|migrate|update)|in-place clone|thin projection|xdg.?data |
refire |
0.15 |
scope |
agent, subagent |
In 1.0, ~/.claude is a thin projection of an XDG application, not the app itself (ADR-142). The source lives in $XDG_DATA_HOME/agent-ways; ~/.claude gets symlinks to the projected roots (skills/, agents/, commands/, hooks/ways/, built binaries) plus a three-way merge into settings.json. Everything else the app ships — scripts/, tools/, docs/, governance/ — stays in $XDG_DATA and is deliberately not projected. So ~/.claude remains the user's own directory (their sessions, credentials, and settings survive); agent-ways adds its links, and it refuses to replace a real directory or file it finds at a projected root.
This supersedes the pre-1.0 world where ~/.claude was the git clone. That "in-place" topology (and the subdirectory variant, ADR-140) is now
legacy: an install still on it needs to migrate, not update in place.
How install and update work now¶
Every ways manage verb that changes the install reports what it would change and changes nothing until --commit (ADR-511). To preview, pass --what-if: it reports even where install.manage_mode: commit makes the bare verb apply.
- Fresh install — the
curl … | bashone-liner stages the app into$XDG_DATA_HOME/agent-ways, builds it, links the binaries ontoPATH, and runs the projection repair (under the hidden fixed name ofways manage repair --commit, which applies with no flag) to materialize the projection and mergesettings.json. An existing~/.claudeis preserved: reconcile adds or repairs the projected roots, and when a projected root path is already a real directory or file it stops before touching anything and names the path.ways manage repair --commit --forcerenames each such path to a timestamped sibling (<name>.ways-backup-<seconds>) and then links; nothing is ever deleted. There is no "clobber vs. keep" menu to reason about anymore. - Update —
ways manage update --what-iffetches and reports what an update would change (versions, release notes, the commits by area, local changes, the actions, dev links) and changes nothing. Read it back to the user.ways manage update --commitpulls the app source, refreshes the binaries and reprojects. Because the roots are symlinks into the app dir, a symlink projection is live the moment the source updates; reconcile is idempotent and silent when nothing changed. - Repair —
ways manage repair --commitre-materializes any missing or stale projected root;--what-ifreports what it would link, merge and withdraw. On a legacy in-place clone the repair stops at the clone's real directories and changes nothing; that case needs the migrator (below). - Reinstall —
ways manage reinstallputs the installed version back from the source it came from, keeping the user's config and state. It fetches and verifies the new copy before it removes anything, so a failed fetch leaves the install as it was. All of these live underways manage(ADR-509), whose help lists them.
Targets: where the install is active (ADR-184)¶
Installation and activation are separate states. The projection lands in each target, a Claude Code config directory recorded under targets: in the user config. ways manage repair converges every enabled target and withdraws from every disabled one: our symlinks unlinked, our hooks block and permissions removed through the merge base that wrote them, nothing else touched. With no targets key the one target is ~/.claude, enabled.
ways manage target listlists targets and their converged state;ways statussays it on its first line.ways manage target plan <dir>previews activation: every root as linked, link, relink, or refused, and the settings merge as kept, added, replaced, removed. Nothing is touched.ways manage target add <dir> --commitrecords the target and projects, and stops (exit 3) when a real path sits at a root or an entry of the user's would go.--forcemoves real paths aside.ways manage target disable <dir> --commitandremove <dir> --commitwithdraw.- A project switches ways off for itself with
enabled: falsein.claude/ways.yaml.
When a user asks whether agent-ways will touch something they own, the answer is the plan. Run it and read it back to them before add --commit. The installer still activates the default target on its own in this release; the handoff to the targets bootstrap is the next increment of ADR-184.
The one decision left: is this a legacy in-place clone?¶
The only fork worth establishing before giving a command is whether ~/.claude is a pre-1.0 in-place clone (it has its own .git and ships the app source — ~/.claude/tools/, ~/.claude/docs/). If so, do not git pull it and do not reconcile it — point the user at migration.
ways migrate was removed in 1.9.0 (ADR-179) and lives at the ways-v1.8.3 tag. Build it in a scratch clone; it acts on ~/.claude and the XDG roots at runtime, so where it was built doesn't matter:
git clone --branch ways-v1.8.3 https://github.com/aaronsb/agent-ways /tmp/ways-migrator
cargo build --release --manifest-path /tmp/ways-migrator/tools/ways-cli/Cargo.toml
/tmp/ways-migrator/tools/target/release/ways migrate --what-if # preview (read-only dry-run)
/tmp/ways-migrator/tools/target/release/ways migrate --execute # relocate the clone to $XDG_DATA, build the projection
Migration is gated and backs up first. See https://github.com/aaronsb/agent-ways/blob/ways-v1.8.3/docs/migration-1.0.md for the full walkthrough.
An un-migrated install is not read: paths.rs resolves the 1.0 locations only (ADR-506). ways manage repair stops at the real directories an in-place clone has at the projection roots, and ways manage update needs the app source in $XDG_DATA_HOME. Point the user at https://github.com/aaronsb/agent-ways/blob/ways-v1.8.3/docs/migration-1.0.md.
Why this way exists¶
The first touch for many adopters is curl … | bash, often with a Claude reading the errors and guiding them. That Claude is you. The pre-1.0 hazard was steering an existing-config user into a clobber; the 1.0 hazard is telling a legacy in-place user to git pull (which drifts them) instead of to migrate. Establish the projection model first, then give the command.
See Also¶
- skills(meta) — skills are one of the projected roots
docs/development.md— the same projection model, from a contributor's seat (install vs dev checkout vs sandbox)- https://github.com/aaronsb/agent-ways/blob/ways-v1.8.3/docs/migration-1.0.md — the
ways migratewalkthrough, run from theways-v1.8.3tag