Separate PAI installation from CC config: CLAUDE_CONFIG_DIR + PAI_DIR=~/.pai

[virtualian]

Motivation

PAI_DIR currently conflates two concerns: Claude Code's config root (~/.claude) and PAI's installation root (~/.claude/PAI/). This prevents PAI from being installed independently of CC's config directory and makes PAI_DIR's name a lie — it points to the Claude home, not the PAI directory.

Goal: Use the official CLAUDE_CONFIG_DIR for CC config and make PAI_DIR user-configurable at install time, defaulting to ~/.pai.

Architecture

Env Vars After Separation (Two Variables Only)

Variable	Purpose	Default	settings.json
CLAUDE_CONFIG_DIR	CC config root	~/.claude	env.CLAUDE_CONFIG_DIR (literal absolute)
PAI_DIR	PAI installation root (redefined)	~/.pai	env.PAI_DIR (literal absolute)
PAI_CONFIG_DIR	XDG user preferences	~/.config/PAI	Unchanged

Live-tested (2026-04-06): Setting CLAUDE_CONFIG_DIR in settings.json env makes it available to hook commands via shell expansion. It does NOT relocate CC's config directory (CC has already found settings.json by that point). No third variable needed.

What Stays vs What Moves

Stays at CLAUDE_CONFIG_DIR (~/.claude):

• hooks/ — CC discovers hooks from its config dir
• MEMORY/ — session state, per-project memory
• settings.json, CLAUDE.md, projects/

Moves to PAI_DIR (~/.pai):

• PAI/ — tools, algorithms, documentation
• skills/ — skill definitions
• agents/ — agent definitions
• PAI-Install/ — installer engine
• VoiceServer/ — voice notification server

Critical Constraint: Hook Command Paths

settings.json hook commands use ${PAI_DIR}/hooks/ (27 references). Changing PAI_DIR breaks hook discovery. Solution: Add CLAUDE_CONFIG_DIR to settings.json env; migrate hook commands from ${PAI_DIR}/hooks/ to ${CLAUDE_CONFIG_DIR}/hooks/ before changing PAI_DIR.

paths.ts Redesign

getConfigDir()  → CLAUDE_CONFIG_DIR || ~/.claude
getPaiDir()     → PAI_DIR || ~/.pai
configPath(...) → getConfigDir() + segments  (hooks, MEMORY, settings)
codePath(...)   → getPaiDir() + segments     (PAI/Tools, Algorithm, docs)
paiPath(...)    → DEPRECATED → configPath()

File Audit

Category	Files	References
settings.json	1	28 (1 def + 27 hook cmds)
Hook TS files	15	~20 relative imports
PAI Tool scripts	27	~70 path constructions
PAI documentation	12	102 hardcoded paths
Installer/build	18	120+ references
Config (CLAUDE.md etc)	3	~10 references
Skill files	3	~16 references
Total	79	~366

Static Dependencies (Cannot Use Env Vars)

Location	Why
settings.json env values	CC doesn't expand shell vars — must be literal absolute paths
settings.json additionalDirectories	Literal paths required
~/.claude.json	OAuth state, ignores CLAUDE_CONFIG_DIR entirely

Execution Plan

Pre-Migration Gate — PASSED ✅

• Add CLAUDE_CONFIG_DIR to settings.json env, change one hook command to use it, verify it fires

Phase 0: Centralise Imports

• Convert 15 hook files' relative ../PAI/Tools/ imports to use paths.ts resolvers
• Zero directory changes, zero breakage

Phase 1: Add CLAUDE_CONFIG_DIR + Update paths.ts

• Add CLAUDE_CONFIG_DIR to settings.json env
• Add getConfigDir(), configPath(), codePath() to paths.ts
• Write resolution tests for fallback chain
• Migrate 27 hook commands from ${PAI_DIR}/hooks/ to ${CLAUDE_CONFIG_DIR}/hooks/

Phase 2: Copy PAI Code + Redefine PAI_DIR

• Copy PAI/, skills/, agents/, PAI-Install/, VoiceServer/ to ~/.pai/
• Update settings.json env.PAI_DIR to ~/.pai
• Update CLAUDE.md hardcoded paths
• Update PAI Tool scripts

Phase 3: Validate + Documentation

• Verify all hooks fire correctly
• Verify loadAtStartup, Algorithm loading, Notify.ts
• Bulk-replace documentation paths
• Update installer templates

Phase 4: Cleanup

• Remove old PAI code from ~/.claude/ after 2-week validation
• Optional: symlink old locations for safety

Rollback

At any phase: Set PAI_DIR back to ~/.claude in settings.json. Old code never left during Phases 0-3. One-line revert, under 60 seconds.

Pre-migration backup:

tar czf ~/tmp/pai-pre-migration.tar.gz ~/.claude/settings.json ~/.claude/hooks/ ~/.claude/PAI/ ~/.claude/skills/ ~/.claude/agents/ ~/.claude/CLAUDE.md

Council Report

See reports/2026-04-06-council-claude-config-dir-pai-dir-separation.md for the full 3-round debate transcript and detailed analysis.

[virtualian]

Council Findings: PAI_DIR Architecture

A council of 4 specialists (PAI System Architect, Claude Code Platform Architect, PAI Operator, Systems Designer) debated across 3 rounds. Key findings:

Research: How Claude Code Uses ~/.claude

• CLAUDE_CONFIG_DIR env var can relocate ~/.claude/ (official, documented)
• CC creates: settings.json, CLAUDE.md, rules/, skills/, commands/, agents/, projects/, plugins/
• settings.json env does NOT expand shell vars (${HOME} passed literally)
• Hook command strings DO get shell-expanded (${PAI_DIR} works at runtime)
• ~/.claude is explicitly documented as user-extensible
• Sources: code.claude.com/docs, anthropics/claude-code issues #3833, #25762, #4276

Research: How PAI Uses ~/.claude

• PAI_DIR currently = ~/.claude (Claude Code config root, NOT the PAI directory)
• getPaiDir() returns PAI_DIR env or falls back to ~/.claude
• paiPath('hooks') = ~/.claude/hooks/, paiPath('PAI') = ~/.claude/PAI/
• PAI_DIR is used for EVERYTHING: hooks, MEMORY, settings, AND PAI code
• Installer sets PAI_DIR = CLAUDE_DIR (which is CLAUDE_CONFIG_DIR or ~/.claude)

Research: PAI_DIR Design Intent (Git History)

• Commit 9647d9e: "restore PAI_DIR for location-agnostic installation"
• Commit 99af5ce: "standardize all paths to use ${PAI_DIR}/"
• Commit b49778d: PAI_DIR was REMOVED because CC doesn't expand vars in settings.json
• Commit ebccb81: Made PAI_DIR aware of CLAUDE_CONFIG_DIR
• Verdict: PAI_DIR was INTENDED to mean "where PAI lives" (commit messages say so), but the IMPLEMENTATION made it mean "where Claude lives"

Council Verdict: Can PAI_DIR Just Be Set to ~/data?

No — not today. Yes — after separation.

PAI_DIR is currently load-bearing for $PAI_DIR/hooks/..., $PAI_DIR/MEMORY/..., $PAI_DIR/settings.json. Setting it to ~/data breaks all of those. But once you separate CLAUDE_HOME=~/.claude from PAI_DIR, then PAI_DIR=~/data works exactly as intended.

Revised Architecture: Phased Two-Variable Approach

The original issue proposed PAI_INSTALL_DIR. The council recommends a different approach:

Phase	Action	Risk	Breakage
0	Add CLAUDE_HOME env var as alias for current PAI_DIR value. New code uses it.	Zero	Zero
1	Write path-resolution tests covering the fallback chain	Zero	Zero
2	Migrate 671 refs: "Claude config" refs → CLAUDE_HOME, "PAI code" refs → PAI_DIR	Low	Per-ref tested
3	Redefine PAI_DIR to mean PAI install root. Set PAI_DIR=~/data. Move directory.	Medium	Covered by Phase 1-2
4	Deprecate old shim after 2 release cycles	Low	None

Key Changes from Original Issue

1. No PAI_INSTALL_DIR — instead, repurpose PAI_DIR to mean what it always should have meant
2. Add CLAUDE_HOME — truthful name for what PAI_DIR currently points to
3. Phase 0 is zero-cost — alias with fallback, nothing breaks
4. Tests before migration — Operator's gate condition accepted unanimously
5. Container/remote readiness — the separation enables PAI on different volumes, shared machines, CI

[virtualian]

Late Research: Daniel Miessler's Direct Statements on PAI_DIR

The background research agents returned with additional evidence from Daniel's own documentation and GitHub discussions.

Evidence 1: Documentation Comment in settings.json

From Releases/v4.0.3/.claude/settings.json line 1000:

"PAI_DIR": "Root directory for your PAI installation (~/.claude). Skills, hooks, memory live here."

Unambiguous. PAI_DIR = ~/.claude. Not ~/.claude/PAI/. The "PAI installation" IS the entire ~/.claude/ tree.

Evidence 2: Daniel's Discussion #263 (Multi-Environment Setup)

"The PAI_DIR environment variable in settings.json env section is the right hook for multi-environment setups. The v3.0 installer respects CLAUDE_CONFIG_DIR as well."

Daniel explicitly equated PAI_DIR with CLAUDE_CONFIG_DIR — same concept, PAI's name for it.

Evidence 3: Discussion #11 (Vendor Agnosticism)

Community member suggested renaming .claude folder. Daniel responded "Oh great idea." When they noted PAI_DIR was already good for this, Daniel said "100." PAI_DIR was created as a portability mechanism — to avoid hardcoding .claude paths. Not to point at a subdirectory.

Evidence 4: The PAI_DIRECTORY Rename

The old repo renamed .claude/ TO PAI_DIRECTORY/ for vendor agnosticism. PAI_DIRECTORY and ~/.claude/ are the SAME concept — the entire config root, not a subdirectory within it.

Evidence 5: CLAUDE_CONFIG_DIR Has Known Bugs

Per CC research, CLAUDE_CONFIG_DIR has incomplete isolation:

• Issue #3833: still creates .claude/ in projects
• Issue #4739: IDE integration breaks
• Issue #15071: some paths remain hardcoded to ~/.claude
  Not a reliable foundation to build on today.

Evidence 6: loadAtStartup is NOT Claude Code Native

It's a PAI convention implemented by LoadContext.hook.ts, not a CC feature. Paths in it are resolved by PAI's hook code, not by CC.

Impact on Recommended Approach

The council's phased approach remains correct, but the framing should be adjusted:

Before (incorrect): "PAI_DIR was always meant to be the PAI install dir, the implementation got it wrong"
After (correct): "PAI_DIR was always meant to be the Claude home dir. To move PAI code separately, we need to CHANGE its meaning via a controlled migration — introduce CLAUDE_HOME for the current semantics, then repurpose PAI_DIR for the new semantics."

The migration phases from the council comment remain unchanged. The key difference is recognising this is a deliberate semantic change, not a bug fix.