Prerequisites
scripts/install.bash requires git, ln, readlink, awk, and
nix-build on PATH. The project’s devenv.nix provides everything
needed; entering the dev shell satisfies the requirements automatically.
Run the installer
PATH (which adds the
nix-built runtime under ~/.local/state/jstack/runtime/bin) is
picked up:
What it does
The installer is idempotent — re-running on a clean tree reports zero actions.| Phase | Action |
|---|---|
preflight | Verify the repo layout and required tools |
seed CLAUDE.md | Optional: copy live ~/.claude/CLAUDE.md into the repo (--seed-from-live) |
link files | Symlink settings.json and CLAUDE.md into ~/.claude/ |
link directories | Symlink skills/, agents/, commands/, hooks/ into ~/.claude/ |
migrate plugins | Symlink plugins/ into ~/.claude/plugins, backing up any existing tree |
build runtime | nix-build runtime/default.nix and link the result under ~/.local/state/jstack/runtime |
shell rc | Append a marker block to ~/.zshrc (or ~/.bashrc) that prepends the runtime to PATH |
Backups
Anything the installer would overwrite is moved aside first. Backups land at:RESTORE.md is dropped alongside the backup describing how to recover.
First-run prerequisites
If~/.claude/settings.json or ~/.claude/CLAUDE.md is currently a
symlink into the nix store (managed by an existing home-manager module),
install.bash will replace it but the home-manager module will recreate
the symlink on the next home-manager switch. Disable the module first:
Remove the home-manager module
Delete
programs.jstack.enable = true; (or equivalent) from your
home-manager configuration.Flags
| Flag | Meaning |
|---|---|
--dry-run | Print actions, change nothing |
--verbose / -v | Print every action including skips |
--seed-from-live | Seed CLAUDE.md from ~/.claude/CLAUDE.md if the repo file is empty and the live one is a nix-store symlink |
-h / --help | Show inline help |
Environment overrides
| Variable | Default | Use |
|---|---|---|
CLAUDE_HOME | ~/.claude | Override the install target (useful for testing) |
XDG_STATE_HOME | ~/.local/state | Override where the runtime symlink is written |