haven v1.0.0 Release Notes

Release date: 2026-03-29

haven 1.0

haven is a production-ready dotfiles and AI environment manager. This release marks the stabilization of the core CLI, file format, and state layout — these will not have breaking changes without a new major version.

What's in 1.0

haven manages three things across your machines:

Dotfiles — tracked with magic-name encoding (like chezmoi), deployed with Tera templates, profile/module scoping, and conflict detection so user edits are never silently overwritten.

Packages — Homebrew Brewfile management integrated with modules. haven apply installs, haven diff shows what's missing, --zap removes unreferenced packages.

AI tools — skill declarations in ai/skills.toml with SHA-pinned fetches, multi-backend support (native and AgentSkills), and per-skill snippet injection into ~/.claude/CLAUDE.md.

Key features that shipped on the way to 1.0:

  • haven import --from chezmoi with template conversion
  • jujutsu (jj) VCS backend alongside git
  • Parallel skill fetches, haven.lock SHA verification, tarball traversal security fix
  • Conflict detection (C/MC markers) with per-file hash tracking
  • haven security-scan for detecting secrets before they reach GitHub
  • haven telemetry for local annotation logging
  • Self-upgrade via haven upgrade
  • Shell completions for fish, zsh, and bash

What's new in v1.0.0

CLAUDE.md no longer lists skills and commands

haven apply previously wrote an "Installed Skills" and "Installed Commands" index into the managed section of ~/.claude/CLAUDE.md. Claude Code discovers skills from ~/.claude/skills/ automatically at runtime, so this listing was redundant noise.

The managed section now contains only snippet content — the text from each skill's all.md and claude-code.md files. These carry instructions and usage notes that Claude Code does not read from SKILL.md automatically, so they remain genuinely useful.

Run haven apply --ai after upgrading to regenerate a cleaner CLAUDE.md.

State and cache directories now follow XDG

haven now follows the XDG Base Directory Specification for its runtime directories. The old ~/.haven/ has been split:

Purpose Old path New path
Applied state, lock, telemetry, backups ~/.haven/ ~/.local/state/haven/
Skill download cache ~/.haven/skills/ ~/.cache/haven/skills/
Local platform registry ~/.haven/platforms.toml ~/.local/state/haven/platforms.toml

Both paths respect XDG_STATE_HOME and XDG_CACHE_HOME environment variables.

Note: haven.lock is not affected — it lives in the repo root and is intentionally tracked by VCS for reproducible installs across machines.

Upgrade

From v0.9.x

haven upgrade

After upgrading, migrate your state directory:

# Migrate state (applied state, telemetry, backups, platform overrides)
mkdir -p ~/.local/state/haven
cp -r ~/.haven/state.json ~/.haven/telemetry.jsonl ~/.haven/backups \
       ~/.local/state/haven/ 2>/dev/null || true
[ -f ~/.haven/platforms.toml ] && \
  cp ~/.haven/platforms.toml ~/.local/state/haven/ 2>/dev/null || true

# Migrate skill cache
mkdir -p ~/.cache/haven
mv ~/.haven/skills ~/.cache/haven/skills 2>/dev/null || true

# Remove old directory once you've verified haven works
rm -rf ~/.haven

# Regenerate CLAUDE.md without the skills/commands index
haven apply --ai

If you have no ~/.haven/ directory (fresh install), no action is needed.

What happens if you don't migrate

haven will start fresh with empty state — no applied-file hashes, no saved profile, no telemetry history. Skills will be re-fetched on the next haven apply. No files on disk are modified; only the state tracking is lost.