PAI is (still) a mess - A proposition

[smolcompute]

The repo hasn't reached a stable MVP state, and I think the architecture is why. I'd like to propose a workflow that could eliminate a lot of friction going forward.

The problem

The repo is not a sanitized version of Daniel's own PAI. What I suspect happens: Daniel's PAI works as intended, so he keeps building more features into it. Meanwhile, the PAI repo itself never gets to a state of MVP because the two versions do not share a common foundation: instead of public PAI being like Chapter 1 of a book, and Daniel's own PAI being Chapter 1 + 2 (common foundation, with next chapter), public PAI is like chapter 1 with missing pages at random places. The maintainer never actually uses and stress tests public PAI in production and each time PAI gets updated new pages go missing.

Proposition

There is a way for Daniel (and the rest of us) of using the actual public PAI as a shared in production foundation while still extending it. It also happens to make pulling updates from public PAI a lot easier. The trick is to use ~/.claude as the staging area for multiple sources, i.e., both public PAI and whatever additions and customizations you have made. This way everyone uses the same foundation (like an application binary), zero fork drift, zero merge conflicts.

This is what Daniel's (and everyone's) install could look like:

# Sources
$DA_HOME/
├── PAI/.claude/              # exact copy of public PAI (zero fork drift)
│   ├── agents/
│   │   └── architect.md         
│   ├── hooks/
│   ├── skills/
│   │   └── CORE/SKILL.md
│   └── voice-server/
│
├── KAI/.claude/             # Kai-only additions (not yet in public PAI)
│   ├── agents/
│   │   └── custom-agent.md   # Kai-only agent
│   ├── hooks/
│   └── skills/
│
├── OVERRIDES/.claude/        # current overrides of PAI files
│   └── skills/
│      └── CORE/SKILL.md     # overrides PAI/.claude/skills/CORE/SKILL.md



#  Runtime view (what Claude reads; dirs are real, files are symlinks)
~/.claude/
├── agents/              # real dir, created by sync script
│   ├── architect.md    -> $PAI_REPO/.claude/agents/architect.md
│   ├── custom-agent.md -> $KAI_REPO/.claude/agents/custom-agent.md
│   └── ...             -> other agent files from PAI/CAI/OVERRIDES/PRIVATE
├── skills/
│   ├── CORE/SKILL.md   -> $OVERRIDE_REPO/.claude/skills/CORE/SKILL.md 
│   └── ...             -> PAI/KAI files unless overridden
├── hooks/              -> PAI/KAI (or OVERRIDE if present)
├── voice-server/       -> PAI (symlinked files inside as needed)
└── shell-snapshots/    # real dir; Claude’s shell/code session data (not linked from repos)

Quick Mental Model

• Think of PAI as the shared toolbox
• KAI as Kai’s unique add-ons or not yet public features,
• OVERRIDES as the explicit override layer.
• $PAI_DIR ( ~/.claude ) is the staging area that Claude actually sees.

Making it all work together in ~/.claude

The symlinks in ~/.claude are created and updated by a script that walks each source with find -type f, then ensure_dir creates real directories in $PAI_DIR; only the files become symlinks. The order of the walks ensures which source wins when there's collisions for a single path.

1. Walks $PAI_REPO/.claude, $KAI_REPO/.claude, then $OVERRIDES_REPO/.claude in that order (KAI overrides PAI; OVERRIDES overrides both).
2. Creates real directories in the target ($PAI_DIR, default ~/.claude) and symlinks every file; skips exclusions, .git, and .DS_Store.
3. Prunes broken links pointing into those sources, respecting exclusions.
4. Warns and skips if a real file already exists at the target path instead of a symlink.
5. Reports per-source link counts, lists newly created links, and groups collisions to show which repo overrode which. This is important.

Customizing PAI Without Fork Drift

How to customize a PAI file (e.g., settings.json or a hook):

1. Copy the file from $PAI_REPO/.claude/... into the identical path under $OVERRIDES_REPO/.claude/....
2. Edit the copy in $OVERRIDES_REPO. Leave the original in $PAI_REPO untouched.
3. Run the symlink sync:

Why this works:

• The sync script processes $PAI_REPO first, then $OVERRIDES_REPO, so any path collision is resolved by the OVERRIDES version (“OVERRIDES wins”).
• At runtime, Claude reads from $PAI_DIR, which now points to your OVERRIDES override, while $PAI_REPO stays clean for upstream pulls.

When to use this:

• Any time you’d otherwise edit a file in $PAI_REPO (config, hooks, skills, etc.).

Result

Daniel (like us) is using the public repo in production. He can slowly transition things from KAI to PAI simply by moving the files from one repo to the other. At any moment, it is always very clear which parts of PAI are being overriden (settings.json, CORE/SKILL.md, etc.) and which are absent from PAI and KAI only. Daniel uses the same core PAI as everyone else and is incentivized to treat it as "real", shared infrastructure.

Notes

• You can add extra sources, for example, you can have a PRIVATE/.claude/ source that is not a repo so never gets pushed to github where you can store skills that contain sensitive information (like memories).
• DA_HOME here is just a folder containing all the sources. Could be ~/Projects or anything.
• I'm happy to provide the symlink-sync script.

Finally, I truly appreciate all the work Daniel is putting into this project. I just see that we are hitting a particular stumbling block that has to do with fork drift between the version the maintainer actually uses in production and the version made publicly available. This is my attempt at a solution and also at a way of making updating one's PAI easy in the future (zero merge conflicts).

[danielmiessler]

I think you're absolutely correct here that things are not working in the current system.

And I truly appreciate you putting all this effort into finding a solution.

I think I am going to do something more drastic that solves all of it in a different way. Check the discussion board for a new post.

And thank you again, @smolcompute, for all the effort that you have put into the project so far.

[smolcompute]

thanks again, Daniel