A quick note before we get into it: this is not the official PAI upgrade path. Daniel Miessler’s recommended approach is to clone the latest release fresh, back up your ~/.claude/ directory, overwrite it with the new version, and then bring your customizations back in. That works. I’ve done it.
What I’ve found works more consistently for me, though, is having my assistant do the migration itself. It’s aware of what changed between versions, it knows where your files need to move, and it can verify each step as it goes. The tricky part is getting the commands, the workflow, and the patterns right, which is why I’ve written this guide and the upgrade script that goes with it. It’s an attempt to package what I’ve learned doing these upgrades so other people’s assistants should be able to do the same thing.
That said, always back up first. If you don’t like what the upgrade did, you should be able to roll back. The script creates a backup for you, but a VM snapshot is even better if you have that option.
What Changed
Daniel describes v4 as “Lean and Mean” : 38 flat skill directories compressed into 12 hierarchical categories, dead systems removed, context footprint cut in half.
The biggest shift is organizational. In v3, everything lived in a flat structure. Skills, hooks, your custom stuff, PAI’s built-in stuff, all mixed together in the same directories. v4 introduces clear boundaries.
Skills got reorganized. 38 flat skill directories became 12 hierarchical categories (Research, Media, Thinking, Security, etc.) with around 63 skills total. Your custom skills move to a dedicated skills/Custom/ folder, so PAI updates never accidentally overwrite your work.
CLAUDE.md is now generated. Instead of one big hand-edited file that grew over time, v4 uses a template system. Your personal configuration lives in dedicated files under PAI/USER/, and a build tool generates a clean CLAUDE.md from them. This keeps things maintainable as both PAI and your customizations evolve.
New PAI directory. v4 adds a PAI/ directory for system documentation, tools, and user context. The PAI/USER/ subdirectory is where your identity, preferences, and project context now live. It’s explicitly portable across upgrades.
Context footprint dropped. Daniel’s release notes say startup context went from ~38% to ~19%. That means more of Claude’s attention goes to your actual work instead of system overhead.
What Gets Preserved
Everything you’ve built should come with you:
- Your custom skills (relocated to
skills/Custom/) - Your steering rules and identity settings (migrated to
PAI/USER/) - Your memory, sessions, and learning data
- Any custom hooks you’ve added
The file layout changes, but your content is preserved.
Before You Start
If you’re running PAI in a VM and your hypervisor supports snapshots or clones, take one now. The upgrade tool creates its own backup, but having a full VM snapshot means you can roll back the entire machine if anything unexpected happens. It takes a minute and it’s the best safety net you can have.
Run the Upgrade
If you’re already using PAI Companion : Tell your assistant to pull the latest changes and run the upgrade:
Pull the latest PAI Companion changes, then read ~/pai-companion/upgrade/UPGRADE.md and follow the upgrade phases.
If you’re not using PAI Companion and just want to upgrade PAI to v4, your assistant can read the upgrade guide directly from GitHub without cloning anything:
Fetch and read https://raw.githubusercontent.com/chriscantey/pai-companion/main/upgrade/UPGRADE.md and follow the upgrade phases.
Either way, the tool should detect your version, back everything up, and walk through each phase.
When it’s done, exit PAI / Claude Code. Run this before you relaunch:
source ~/.bashrc
If you run into any errors after the upgrade, most of them should be resolvable by logging completely out of your VM, logging back in, and starting a fresh Claude Code session.
If you’re doing a fresh install instead of upgrading, the setup guide and companion post cover that path.
Part of the PAI Setup Series. Previous: Build or Buy May Have Changed