ADR-057: CODITECT Core Initial Setup for Individual Contributors
Status
Accepted - January 6, 2026 | Updated - January 6, 2026 (v1.1.0: Protected Installation)
Context
Individual contributors need a standardized, automated way to set up CODITECT Core on their local macOS machines. The setup must:
- Detect existing installations and handle upgrades gracefully
- Back up non-CODITECT files to prevent data loss
- Configure all required dependencies and directory structures
- Set up Claude Code integration with proper hooks
- Initialize the context database for memory persistence
- Be interactive to inform users and require explicit approval
- Install to a protected location where non-technical users cannot accidentally damage the framework
Current State Analysis (macOS)
System Requirements Detected:
| Component | Required | Location | Notes |
|---|---|---|---|
| macOS | ≥12.0 (Monterey) | - | Darwin kernel required |
| Python | ≥3.10 | pyenv or Homebrew | 3.12+ recommended |
| Git | ≥2.30 | Homebrew | For submodule support |
| Node.js | ≥18.0 | nvm or Homebrew | For frontend tooling |
| Claude Code | Latest | /opt/homebrew/bin/claude | Installed via brew install --cask claude-code |
Essential File Locations:
| Path | Purpose | Created By |
|---|---|---|
~/.claude/ | Claude Code global config | Claude Code |
~/.claude/settings.json | Global hooks, plugins | User/Setup |
~/.claude/projects/ | Project-specific settings | Claude Code |
~/.claude/history.jsonl | Session history | Claude Code |
~/PROJECTS/ | Standard projects root | CODITECT convention |
~/PROJECTS/.coditect/ | Symlink to protected location | Setup script |
~/PROJECTS/.claude -> .coditect | Compatibility symlink | Setup script |
~/.coditect/ | Backward compat symlink → protected | Setup script |
~/Library/Application Support/CODITECT/core/ | Protected installation (macOS) | Setup script |
Protected Installation Architecture (v1.1.0)
Rationale: The CODITECT framework should be installed in a location where non-technical users cannot accidentally damage files by copying, moving, or deleting them. The macOS Application Support directory is:
- Hidden from Finder by default (~/Library is hidden)
- Standard macOS location for application data
- User-writable but not easily accessible
- Protected from accidental modification
Platform-Specific Paths:
| Platform | Protected Location |
|---|---|
| macOS | ~/Library/Application Support/CODITECT/core/ |
| Linux | ~/.local/share/coditect/core/ (XDG standard) |
| Windows | %APPDATA%\CODITECT\core\ (future) |
Directory Structure After Setup:
~/
├── .claude/ # Claude Code (auto-created)
│ ├── settings.json # Global hooks configuration
│ ├── settings.local.json # Local overrides
│ ├── projects/ # Per-project settings
│ └── history.jsonl # Session history
│
├── .coditect -> ~/Library/.../CODITECT/core/ # ★ BACKWARD COMPAT SYMLINK
│ # (For scripts referencing ~/.coditect)
│
├── Library/Application Support/CODITECT/ # ★ PROTECTED LOCATION
│ ├── core/ # CODITECT Core framework (git repo)
│ │ ├── machine-id.json # Hardware UUID
│ │ ├── agents/ # 139 AI agents
│ │ ├── commands/ # 155 slash commands
│ │ ├── skills/ # 207 reusable skills
│ │ ├── hooks/ # Event trigger scripts
│ │ ├── scripts/ # Automation scripts
│ │ ├── session-logs/ # Machine-specific session logs
│ │ │ ├── SESSION-LOG-2026-01-04.md
│ │ │ └── SESSION-LOG-2026-01-06.md
│ │ ├── session-logs-cache/ # Cached logs from other machines
│ │ │ └── index.json
│ │ ├── context-storage/ # SQLite database
│ │ │ ├── context.db # Main database
│ │ │ └── checkpoints/ # Session checkpoints
│ │ └── config/ # Configuration files
│ │
│ └── data/ # User data (future use)
│
└── PROJECTS/ # Projects root
├── .coditect -> ~/Library/.../core/ # ★ PRIMARY USER ACCESS (symlink)
├── .claude -> .coditect # Compatibility alias
└── BU/ # Backup directory
├── YYYY-MM-DD-HHMMSS/ # Timestamped backups
│ ├── legacy-coditect-backup/ # Migrated from ~/.coditect
│ └── protected-coditect-backup/ # Previous protected installation
└── session-logs/ # Session log backups
Symlink Chain:
~/PROJECTS/.coditect ──▶ ~/Library/Application Support/CODITECT/core/
~/PROJECTS/.claude ──▶ .coditect (relative)
~/.coditect ──▶ ~/Library/Application Support/CODITECT/core/ (backward compat)
Machine Identification
Each machine generates a unique, persistent identifier based on hardware characteristics:
File: ~/.coditect/machine-id.json
{
"machine_uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"hardware_hash": "sha256:abc123def456...",
"hostname": "hal-mbp-2024",
"platform": "Darwin",
"platform_version": "26.2",
"model": "MacBookPro18,1",
"created": "2026-01-06T10:30:00Z"
}
UUID Generation: Deterministic hash from hardware identifiers (IOPlatformUUID, serial hash, MAC hash, CPU, model) ensures:
- Same UUID across reboots and reinstalls
- Unique per physical machine
- Privacy-preserving (hashed values)
See ADR-058: Machine-Specific Session Logs for full architecture.
Decision
We will create an interactive Python setup script (CODITECT-CORE-INITIAL-SETUP.py) that:
1. Pre-Installation Checks
- Verify macOS version (≥12.0 Monterey)
- Verify Python version (≥3.10)
- Verify Git version (≥2.30)
- Check for Homebrew installation
- Detect Claude Code installation
2. Existing Installation Detection
- Check for protected location (
~/Library/Application Support/CODITECT/core/) - Check for legacy location (
~/.coditect/directory, needs migration) - Check for
~/PROJECTS/.coditectsymlink - Check for
~/PROJECTS/.claudesymlink - Identify non-CODITECT files in PROJECTS folder
- Calculate backup size requirements
3. Backup Strategy
Backup Location: ~/PROJECTS/BU/YYYY-MM-DD-HHMMSS/
What Gets Backed Up:
- Existing legacy
~/.coditectdirectory (if present, needs migration) - Existing protected installation (if updating)
- Existing
.claudefiles (if non-symlink) - Non-CODITECT project files (optional, with user consent)
- Claude Code session history (preserves context)
Backup Format:
BU/
└── 2026-01-06-103045/
├── BACKUP-MANIFEST.json # What was backed up
├── legacy-coditect-backup/ # Previous ~/.coditect (migration)
├── protected-coditect-backup/ # Previous protected installation
├── claude-history-backup/ # Session history
└── projects-backup/ # User projects (optional)
4. Installation Steps
┌─────────────────────────────────────────────────────────────────┐
│ SETUP WORKFLOW │
├─────────────────────────────────────────────────────────────────┤
│ │
│ 1. VERIFY PREREQUISITES │
│ ├── Check macOS version │
│ ├── Check Python (pyenv/homebrew) │
│ ├── Check Git version │
│ └── Check Claude Code │
│ │
│ 2. DETECT EXISTING INSTALLATIONS │
│ ├── Scan protected location (App Support) │
│ ├── Scan legacy location (~/.coditect) │
│ ├── Scan ~/PROJECTS │
│ └── Calculate changes needed │
│ │
│ 3. USER APPROVAL (Interactive) │
│ ├── Display detected state │
│ ├── Show planned changes │
│ ├── Estimate disk usage │
│ └── Require explicit YES │
│ │
│ 4. BACKUP EXISTING │
│ ├── Create timestamped backup dir │
│ ├── Backup legacy ~/.coditect (if exists) │
│ ├── Backup protected installation (if exists) │
│ ├── Preserve Claude history │
│ └── Write backup manifest │
│ │
│ 5. CLONE/UPDATE TO PROTECTED LOCATION │
│ ├── Create ~/Library/Application Support/CODITECT/ │
│ ├── git clone (new) or git pull (existing) │
│ ├── Initialize submodules │
│ └── Verify integrity │
│ │
│ 6. CREATE SYMLINKS │
│ ├── ~/PROJECTS/.coditect -> protected location │
│ ├── ~/PROJECTS/.claude -> .coditect │
│ ├── ~/.coditect -> protected (backward compat) │
│ └── Verify symlinks resolve │
│ │
│ 7. CONFIGURE CLAUDE CODE │
│ ├── Install/update ~/.claude/settings.json │
│ ├── Register hooks │
│ └── Enable plugins │
│ │
│ 8. INITIALIZE DATABASE │
│ ├── Create context-storage/ │
│ ├── Initialize context.db │
│ └── Run component indexer │
│ │
│ 9. GENERATE MACHINE ID │
│ ├── Collect hardware identifiers │
│ ├── Generate deterministic UUID │
│ ├── Write machine-id.json to protected location │
│ └── Create session-logs/ directory │
│ │
│ 10. MIGRATE SESSION LOGS │
│ ├── Find existing logs in git-tracked dirs │
│ ├── Move to protected-location/session-logs/ │
│ ├── Add machine headers to logs │
│ └── Add .gitignore entries │
│ │
│ 11. CREATE PYTHON VENV │
│ ├── python -m venv .venv │
│ ├── pip install -r requirements.txt │
│ └── Verify all imports │
│ │
│ 12. VERIFY INSTALLATION │
│ ├── Verify protected location exists │
│ ├── Verify all symlinks resolve │
│ ├── Test /cx command │
│ ├── Test database queries │
│ ├── Verify machine-id.json │
│ └── Generate success report │
│ │
└─────────────────────────────────────────────────────────────────┘
5. Post-Installation
- Display success message with next steps
- Show how to run
/orientcommand - Provide rollback instructions if needed
- Log installation details to
~/.coditect/logs/setup.log
Consequences
Positive
- Consistent Environment: All contributors have identical setup
- Data Safety: Automatic backups prevent data loss
- Idempotent: Can run multiple times safely
- Transparent: User sees and approves all changes
- Reversible: Backup manifest enables rollback
- Protected Installation: Framework files hidden from accidental modification
- Backward Compatibility: Legacy ~/.coditect symlink preserves existing scripts
Negative
- macOS Only: Initial script is macOS-specific (Linux/Windows later)
- Disk Space: Backups consume additional space
- Network Required: Git clone requires internet connection
- Hidden Location: Users must use symlinks to access framework (by design)
Risks
| Risk | Mitigation |
|---|---|
| Backup fails mid-operation | Atomic operations with rollback |
| Symlinks break paths | Verify all paths resolve after creation |
| Permission denied | Check/request permissions before operations |
| Disk full | Pre-calculate space requirements |
| Legacy scripts reference ~/.coditect directly | Backward compat symlink at ~/.coditect |
| Protected location inaccessible | Verify Application Support is writable |
Dependencies
Required Before Setup:
# Install Homebrew (if not present)
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
# Install Claude Code
brew install --cask claude-code
# Install pyenv (recommended for Python management)
brew install pyenv
pyenv install 3.12.12
pyenv global 3.12.12
# Install Node.js via nvm (optional, for frontend)
brew install nvm
nvm install 24
Configuration
Claude Code Settings (~/.claude/settings.json)
{
"enabledPlugins": {
"pyright-lsp@claude-plugins-official": true
},
"alwaysThinkingEnabled": true,
"hooks": {
"PreToolUse": [
{
"matcher": "TodoWrite",
"hooks": [
{
"type": "command",
"command": "~/.coditect/hooks/dispatcher.sh task-tracking-enforcer.py --event pre --level soft",
"timeout": 5000
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "~/.coditect/hooks/dispatcher.sh classify-document.sh",
"timeout": 30
}
]
},
{
"matcher": "TodoWrite",
"hooks": [
{
"type": "command",
"command": "~/.coditect/hooks/dispatcher.sh task-plan-sync.py",
"timeout": 10000
}
]
}
]
}
}
Verification
After installation, verify with:
# Check protected installation
ls -la ~/Library/Application\ Support/CODITECT/core/
# Check symlinks
ls -la ~/PROJECTS/.coditect # Should point to protected location
ls -la ~/PROJECTS/.claude # Should point to .coditect
ls -la ~/.coditect # Backward compat symlink
# Check database
sqlite3 ~/.coditect/context-storage/context.db ".tables"
# Check Claude Code hooks
cat ~/.claude/settings.json | jq '.hooks'
# Check machine ID
cat ~/.coditect/machine-id.json
# Test context extraction
cd ~/PROJECTS && claude
# Then run: /cx --dry-run
Expected symlink chain:
~/PROJECTS/.coditect → ~/Library/Application Support/CODITECT/core/
~/PROJECTS/.claude → .coditect (relative)
~/.coditect → ~/Library/Application Support/CODITECT/core/
Related Documents
- USER-quick-start.md
- COMPONENT-ACTIVATION-GUIDE.md
- ADR-053: Cloud Context Sync
- ADR-058: Machine-Specific Session Logs
- database-schema.md
References
- Claude Code Documentation: https://docs.anthropic.com/claude-code
- pyenv: https://github.com/pyenv/pyenv
- nvm: https://github.com/nvm-sh/nvm
Author: AI Assistant Reviewed By: Hal Casteel Approved: January 6, 2026