User Quick Start Guide

Complete CODITECT installation in 20 minutes. This guide mirrors CODITECT-CORE-INITIAL-SETUP.py v3.0.0.

Are you a contributor? If you are developing CODITECT (working with submodules, creating PRs), use Developer Quick Start instead. This guide is for end users installing CODITECT for use.

Before You Begin

You will need:

Requirement	Version	How to Check
macOS	12.0+ (Monterey or later)	Open Terminal, type: `sw_vers`
Python	3.10 or higher	`python3 --version`
Git	2.30 or higher	`git --version`
GitHub Account	Free or paid	https://github.com

For AI Features:

A Claude Max subscription provides full AI agent capabilities

Optional but recommended:

VS Code - The script will offer to install this
Homebrew - macOS package manager

GitHub Setup (First-Time Users)

CODITECT is distributed via a private GitHub repository. You need a GitHub account and authentication configured before installation.

Already have GitHub set up? Skip to Step 1: Open Terminal.

GitHub Step 1: Create a GitHub Account

If you don't have a GitHub account:

Go to https://github.com/signup
Enter your email address
Create a password
Choose a username
Verify your email address

GitHub Step 2: Install GitHub CLI

The GitHub CLI (gh) is the easiest way to authenticate with GitHub.

Option A - Using Homebrew (recommended):

brew install gh

Option B - Direct download:

Go to https://cli.github.com
Download the macOS installer
Run the installer

Verify installation:

gh --version

You should see something like: gh version 2.40.0 (2024-01-15)

GitHub Step 3: Authenticate with GitHub

Run:

gh auth login

You will see prompts. Choose these options:

? What account do you want to log into? GitHub.com
? What is your preferred protocol for Git operations on this host? HTTPS
? Authenticate Git with your GitHub credentials? Yes
? How would you like to authenticate GitHub CLI? Login with a web browser

A browser window will open. Log in to GitHub and authorize the CLI.

What you will see when successful:

✓ Authentication complete.
- gh config set -h github.com git_protocol https
✓ Configured git protocol
✓ Logged in as your-username

GitHub Step 4: Set Up SSH Keys (Recommended)

SSH keys provide secure, passwordless authentication with GitHub. This step is optional but recommended.

Check if you already have SSH keys:

ls -la ~/.ssh

If you see files like id_ed25519 and id_ed25519.pub, you already have SSH keys. Skip to "Add SSH key to GitHub" below.

Generate new SSH keys:

# Generate a new SSH key (press Enter to accept defaults)
ssh-keygen -t ed25519 -C "your-email@example.com"

You will see:

Generating public/private ed25519 key pair.
Enter file in which to save the key (/Users/you/.ssh/id_ed25519): [Press Enter]
Enter passphrase (empty for no passphrase): [Press Enter or type a passphrase]
Enter same passphrase again: [Press Enter or repeat passphrase]

Start the SSH agent:

eval "$(ssh-agent -s)"

Add your key to the agent:

ssh-add ~/.ssh/id_ed25519

Add SSH key to GitHub:

gh ssh-key add ~/.ssh/id_ed25519.pub --title "My Mac $(date +%Y-%m-%d)"

You should see:

✓ Public key added to your account

Test your connection:

ssh -T git@github.com

You should see:

Hi your-username! You've successfully authenticated, but GitHub does not provide shell access.

GitHub Step 5: Configure Git Protocol (Optional)

If you set up SSH keys, configure Git to use SSH by default:

gh config set git_protocol ssh

This makes all future Git operations use SSH instead of HTTPS.

GitHub Setup Complete

Your GitHub setup is complete. You can now proceed with CODITECT installation.

Summary of what you configured:

Item	Status
GitHub account	Created/verified
GitHub CLI	Installed
GitHub authentication	Configured
SSH keys	Generated and added (optional)

Step 1: Open Terminal

Press Cmd + Space to open Spotlight
Type Terminal and press Enter
A black window with a command line will appear

Step 2: Create Your Projects Folder

Choose where your projects will live. Type ONE of these commands:

Option A - Standard (recommended):

mkdir -p ~/PROJECTS && cd ~/PROJECTS

Option B - Custom name:

mkdir -p ~/MyProjects && cd ~/MyProjects

You will see no output if successful. The command creates the folder and navigates into it.

Step 3: Download CODITECT

Type this command:

git clone https://github.com/coditect-ai/coditect-core.git

What you will see:

Cloning into 'coditect-core'...
remote: Enumerating objects: 1234, done.
remote: Counting objects: 100% (1234/1234), done.
Receiving objects: 100% (1234/1234), 5.67 MiB | 8.90 MiB/s, done.
Resolving deltas: 100% (456/456), done.

This downloads CODITECT to your computer. It takes about 30 seconds.

Step 4: Run the Installation Script

Type this command:

python3 coditect-core/scripts/CODITECT-CORE-INITIAL-SETUP.py

Press Enter. The installation process will begin.

What Happens During Installation

The script runs in several phases. Here is what you will see:

Phase 1: License Agreement

================================================================================
                    CODITECT SOFTWARE LICENSE AGREEMENT
================================================================================

CODITECT Framework - Copyright (c) 2025 AZ1.AI Inc. All Rights Reserved.

WHAT YOU CAN DO:
- Use CODITECT for your internal business purposes
- Use AI-generated outputs in your projects
- Install on multiple machines you control

WHAT YOU CANNOT DO:
- Copy, modify, or redistribute CODITECT without permission
- Reverse engineer or decompile the software
- Use CODITECT to build competing products

Do you accept these terms? (yes/no)
>

Action required: Type yes and press Enter to continue.

Phase 2: Prerequisite Checks

The script checks your system:

========================== PREREQUISITE CHECKS ==========================

Required:
  ✓ macOS: 14.2 (required: >= 12.0)
  ✓ Python: 3.12 (required: >= 3.10)
  ✓ Git: 2.43.0 (required: >= 2.30)

Optional/Recommended:
  ✓ Homebrew: 4.2.0
  ✓ Node.js: 22.1.0
  ○ VS Code: Not installed
  ○ Claude Code: Not installed

Green checkmarks (✓) = Installed and ready
Open circles (○) = Optional, not installed

If any Required item shows a red X, you must install it before continuing.

Phase 3: VS Code Installation (Optional)

If VS Code is not installed, you will see:

VS Code Installation (Recommended)

VS Code is the recommended editor for CODITECT development.

Installation Options:
  1. Download from: https://code.visualstudio.com/download
  2. Using Homebrew: brew install --cask visual-studio-code
  3. Skip for now

Would you like to install VS Code now using Homebrew? (yes/no/skip)
>

Action required: Type yes, no, or skip and press Enter.

yes - Installs VS Code automatically (requires Homebrew)
no or skip - Continues without VS Code

Phase 4: Detecting Existing Installations

========================== DETECTING EXISTING INSTALLATIONS ==========================

ℹ No existing protected installation found (fresh install)
  └─ Will install to: /Users/YOU/Library/Application Support/CODITECT/core

The script checks if CODITECT is already installed. For a first installation, you will see "fresh install".

Phase 5: Installation Plan

The script shows what it will do:

========================== INSTALLATION PLAN ==========================

The following changes will be made:

INSTALL:
  • Clone/update CODITECT Core to PROTECTED location:
      /Users/YOU/Library/Application Support/CODITECT/core
  • Select optional products (Financial Model, Runway Calculator, etc.)
  • Create symlink ~/PROJECTS/.coditect -> protected location
  • Create symlink ~/PROJECTS/.claude -> .coditect
  • Create backward compat symlink ~/.coditect -> protected location
  • Configure hooks
  • Initialize context databases (6 databases, ADR-118)
  • Generate unique machine identifier
  • Set up Python virtual environment
  • Configure statusline
  • Install context services (watcher + indexer)
  • Initialize licensing and platform databases
  • Install selected products to protected location
  • Set up user component directories
  • Apply framework protection

PROTECTED LOCATION:
  /Users/YOU/Library/Application Support/CODITECT/
  ├── core/       (Framework - hidden from Finder)
  └── products/   (Optional products - hidden from Finder)

Proceed with installation?
Type 'YES' to continue, anything else to cancel:

Action required: Type YES (in capitals) and press Enter.

Phase 6: Installation Progress (19 Steps)

The script performs 19 installation steps. Here is what each step does:

Step 1 of 19: Clone Repository

[1/19] Setting up CODITECT Core repository
       ✓ Cloned CODITECT Core to protected location

What happens:

Creates the protected directory: ~/Library/Application Support/CODITECT/
Performs a fresh git clone from GitHub
Initializes git submodules if present
Location is hidden from Finder to prevent accidental modification

Files created:

~/Library/Application Support/CODITECT/core/ - Complete CODITECT framework

Step 2 of 19: Select Optional Products (NEW in v3.0.0)

[2/19] Selecting optional products

  Available products:
  [x] 1. Financial Model Engine - SaaS financial projections (60-month, 4 output formats)
  [ ] 2. Runway Calculator - Cash runway and burn rate analysis

  Enter numbers to toggle, or press Enter to continue:

What happens:

Displays available optional products from the product registry (ADR-180)
Products marked with [x] are selected by default
Toggle selections by entering numbers
In --non-interactive mode, all default products are auto-selected
Selections are saved to config.json for future reinstalls

Products available:

Product	Description	Default
Financial Model Engine	SaaS financial projections (60-month, 4 output formats)	Yes
Runway Calculator	Cash runway and burn rate analysis	No

Step 3 of 19: Create Symlinks

[3/19] Creating symlinks
       ✓ Created ~/PROJECTS/.coditect -> protected location
       ✓ Created ~/PROJECTS/.claude -> .coditect
       ✓ Created ~/.coditect -> protected location (backward compatibility)

What happens:

Creates three symlinks pointing to the protected installation
Enables access via ~/PROJECTS/.coditect (primary)
Enables access via ~/.coditect (backward compatibility)
The .claude symlink is a relative link to .coditect

Symlink architecture:

~/PROJECTS/.coditect  ->  ~/Library/Application Support/CODITECT/core/
~/PROJECTS/.claude    ->  .coditect (relative)
~/.coditect           ->  ~/Library/Application Support/CODITECT/core/

Step 4 of 19: Configure Claude Code

[4/19] Configuring Claude Code
       ✓ Configured Claude Code hooks

What happens:

Creates or updates ~/.claude/settings.json
Registers PreToolUse hooks (task tracking enforcer)
Registers PostToolUse hooks (document classification, task sync)
Enables pyright-lsp plugin for Python development

Hooks configured:

Event	Hook	Purpose
PreToolUse:TodoWrite	task-tracking-enforcer.py	Validate task IDs
PostToolUse:Write/Edit	classify-document.sh	Auto-classify documents
PostToolUse:TodoWrite	task-plan-sync.py	Sync tasks to PILOT plan

Step 5 of 19: Initialize Databases

[5/19] Initializing databases (ADR-118 four-tier)
       ✓ Initialized org.db (decisions, learnings)
       ✓ Initialized sessions.db (messages, analytics)
       ✓ Created FTS5 full-text search indexes

What happens:

Creates ~/PROJECTS/.coditect-data/context-storage/ directory
Creates exports-pending/ and exports-archive/ subdirectories
Creates logs/ directory for service logs
Initializes SQLite databases with FTS5 full-text search
Creates tables with indexes and triggers

Databases created (ADR-118 Six-Tier):

Database	Tier	Purpose	Regenerable?
`org.db`	2	Decisions, learnings, error solutions	NO - IRREPLACEABLE
`sessions.db`	3	Messages, session metadata, analytics	Yes
`platform.db`	1	Component index and metadata	Yes
`projects.db`	4	Project registry and configuration	Yes
`messaging.db`	5	Inter-agent messaging	Yes
`call_graph.db`	6	Code call graph index	Yes

Files created:

~/PROJECTS/.coditect-data/context-storage/org.db
~/PROJECTS/.coditect-data/context-storage/sessions.db
~/PROJECTS/.coditect-data/context-storage/exports-pending/
~/PROJECTS/.coditect-data/context-storage/exports-archive/
~/PROJECTS/.coditect-data/logs/

Step 6 of 19: Generate Machine ID

[6/19] Generating machine identifier
       ✓ Generated machine UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
         Hostname: your-mac
         Model: MacBookPro18,1

What happens:

Collects hardware identifiers (IOPlatformUUID, serial hash, MAC hash, CPU, model)
Generates a deterministic UUID that survives reboots and reinstalls
Creates machine-id.json with hardware fingerprint
Creates session-logs/ directory for machine-specific logs

Why this matters:

Same UUID across reboots and reinstalls on same hardware
Unique per physical machine
Privacy-preserving (values are hashed)
Enables session log syncing across machines

Files created:

~/.coditect/machine-id.json - Machine identification
~/.coditect/session-logs/ - Local session logs
~/.coditect/session-logs-cache/ - Cached logs from other machines

Step 7 of 19: Migrate Session Logs

[7/19] Migrating session logs
       ℹ No session logs to migrate
       (or)
       ✓ Migrated 5 session logs
         └─ Added machine headers to logs

What happens:

Scans for existing session logs in git-tracked directories
Adds machine identification headers to each log
Copies logs to the protected session-logs/ directory (skips if destination exists)
Preserves original creation dates

For first-time installations: You will see "No session logs to migrate"

Step 8 of 19: Setup Python Environment

[8/19] Setting up Python environment
       ✓ Created Python virtual environment
       ✓ Installed Python dependencies (42 packages)

What happens:

Creates a Python virtual environment at ~/.coditect/.venv/
Installs all required packages from requirements.txt
Packages include: PyYAML, requests, sqlite-utils, and more

Files created:

~/.coditect/.venv/ - Python virtual environment

To activate manually:

source ~/.coditect/.venv/bin/activate

Step 9 of 19: Configure Statusline

[9/19] Configuring statusline
       ✓ Created statusline script
       ✓ Configured Claude Code to use statusline
         └─ All 7 sections enabled (FULL mode)

What happens:

Creates ~/.claude/statusline-command.sh - Statusline script
Creates ~/.claude/statusline-config.json - Section configuration
Enables all 7 statusline sections by default

Statusline sections:

#	Icon	Key	What it shows
1	project	project	Current working directory
2	git	git	Branch, status, ahead/behind
3	claude	claude	Model, context %, tokens
4	environment	environment	Python, Node, Docker versions
5	system	system	Battery, RAM, disk
6	identity	identity	user@host, time
7	task	task	CODITECT task ID

Files created:

~/.claude/statusline-command.sh - Statusline generation script
~/.claude/statusline-config.json - Section toggle configuration

Step 10 of 19: Install Context Watcher

[10/19] Installing context watcher
        ✓ Installed codi-watcher v2.0.0 binary to ~/.coditect/bin/
        ✓ Installed ai.coditect.context-watcher.plist (daemon)
        ✓ Installed ai.coditect.context-indexer.plist (every 15 min)
        ✓ Started context watcher service
        ✓ Started context indexer service

What happens:

Downloads or builds the codi-watcher v2.0.0 binary (Rust, ADR-134)
Installs to ~/.coditect/bin/codi-watcher
Copies launchd plist files to ~/Library/LaunchAgents/
Starts both services using launchctl load

Services installed:

Service	Type	Purpose
ai.coditect.context-watcher	Daemon (always running)	Monitors Claude sessions, triggers `/cx` at 75% context
ai.coditect.context-indexer	Periodic (every 15 min)	Extracts messages, builds search index

Files created:

~/.coditect/bin/codi-watcher - Context watcher binary (v2.0.0)
~/Library/LaunchAgents/ai.coditect.context-watcher.plist - Watcher service config
~/Library/LaunchAgents/ai.coditect.context-indexer.plist - Indexer service config

Step 11 of 19: Configure Backup

[11/19] Configuring backup
        ✓ Configured scheduled backup (every 6 hours)

What happens:

Installs launchd plist for scheduled context database backup
Backs up org.db (irreplaceable) and other databases to GCS
Runs every 6 hours automatically

Step 12 of 19: Initialize Licensing

[12/19] Initializing licensing
        ✓ Created licensing directory
        ✓ Created license templates
          └─ Run 'coditect activate' to activate your license

What happens:

Creates ~/.coditect/licensing/ directory
Creates license template files
Creates validation cache for offline use
Displays activation instructions

Files created:

~/.coditect/licensing/license.json.template - License template
~/.coditect/licensing/validation-cache.json - Offline validation cache
~/.coditect/licensing/offline-log.json - Offline usage log

Step 13 of 19: Initialize Platform Database

[13/19] Initializing platform database (ADR-089)
        ✓ Indexed 776 agents, 377 commands, 445 skills
        ✓ Created component_origin column

What happens:

Indexes all framework components into platform.db
Creates FTS5 search indexes for component discovery
Adds component_origin column (system, product, or user)
Enables /which, /what, and component search

Step 14 of 19: Initialize Platform-Index Database

[14/19] Initializing platform-index database (ADR-103)
        ✓ Built capability index

What happens:

Creates secondary indexes for fast capability lookups
Powers the /which semantic agent matching

Step 15 of 19: Initialize Projects Database

[15/19] Initializing projects database (ADR-118 TIER 4)
        ✓ Created projects registry

What happens:

Initializes projects.db for project registry and configuration
Creates project tracking tables

Step 16 of 19: Configure MoE Tools

[16/19] Configuring MoE tools
        ✓ Configured MoE classifier and routing

What happens:

Sets up Mixture of Experts (MoE) document classification tools
Configures agent routing and capability matching
Enables /classify, /moe-agents, /moe-judges commands

Step 17 of 19: Install Selected Products (NEW in v3.0.0)

[17/19] Installing selected products
        ✓ Cloned coditect-financial-model to protected location
        ✓ Created product venv with xlsxwriter
        ✓ Created discovery symlink

What happens:

For each product selected in Step 2:
- Clones product repo to ~/Library/Application Support/CODITECT/products/{product-name}/
- Creates per-product Python virtual environment (if has_venv)
- Installs product dependencies from requirements.txt
- Creates discovery symlink from core to product location
Skipped if no products were selected

Files created (per product):

~/Library/Application Support/CODITECT/products/coditect-financial-model/ - Product files
~/Library/Application Support/CODITECT/products/coditect-financial-model/.venv/ - Product venv

Step 18 of 19: Setup User Component Directories (NEW in v3.0.0)

[18/19] Setting up user component directories
        ✓ Created user-components/ directory structure
        ✓ Created README with templates

What happens:

Creates directories for user-created components:

~/PROJECTS/.coditect-data/user-components/
├── agents/
├── skills/
├── commands/
├── hooks/
└── README.md

The README explains how to create custom components
User components are indexed with component_origin: user in platform.db

Step 19 of 19: Apply Framework Protection

[19/19] Applying framework protection
        ✓ Applied read-only protection to core
        ✓ Applied read-only protection to products
        ✓ Generated integrity checksums

What happens:

Sets protected installation to read-only
Generates SHA-256 checksums for integrity verification
Removes .git directory from protected copies (prevents accidental pushes)
Applies protection to both core and installed products

Phase 7: Verification

The script verifies the installation:

========================== VERIFYING INSTALLATION ==========================

✓ Protected installation: /Users/YOU/Library/Application Support/CODITECT/core
✓ Symlink ~/PROJECTS/.coditect -> protected location
✓ Symlink ~/PROJECTS/.claude -> .coditect
✓ Backward compat symlink ~/.coditect -> protected location
✓ Databases initialized (6 databases, ADR-118)
✓ Claude Code hooks configured
✓ Python virtual environment ready
✓ Directory agents/ (776 items)
✓ Directory commands/ (377 items)
✓ Directory skills/ (445 items)
✓ Machine ID: a1b2c3d4... (your-mac)
✓ Statusline configured (7/7 sections enabled)
✓ Context watcher v2.0.0 binary installed
✓ Context watcher service running
✓ Context indexer service installed (runs every 15 min)
✓ Logs directory created
✓ Licensing directory initialized
✓ Platform database indexed (component_origin enabled)
✓ Projects database initialized
✓ MoE tools configured
✓ Product: coditect-financial-model installed
✓ User component directories created
✓ Framework protection applied

All items should show green checkmarks (✓).

Phase 8: Installation Complete

========================== INSTALLATION COMPLETE ==========================

✓ CODITECT Core v3.0.0 has been successfully installed!

Installation Locations:
   • Protected core: /Users/YOU/Library/Application Support/CODITECT/core
   • Protected products: /Users/YOU/Library/Application Support/CODITECT/products/
   • User access: ~/PROJECTS/.coditect (symlink)
   • Backward compat: ~/.coditect (symlink)
   • User components: ~/PROJECTS/.coditect-data/user-components/

Products Installed:
   • coditect-financial-model (Financial Model Engine)

Background Services:
   • ai.coditect.context-watcher (daemon - auto-export at 75% context)
   • ai.coditect.context-indexer (every 15 min - search indexing)
   • ai.coditect.backup (every 6 hours - database backup)

Next Steps:

1. Activate the virtual environment:
   source ~/.coditect/.venv/bin/activate

2. Start your AI-powered workflow:
   /orient

3. Try the financial model (if installed):
   /fm seed-defaults mycompany
   /fm build mycompany --format all

Machine Identification:
   • Machine UUID: a1b2c3d4... (your-mac)
   • Session logs: ~/.coditect/session-logs/

Installation is complete.

Step 5: Verify Your Installation

Run this command to verify everything is working:

python3 coditect-core/scripts/CODITECT-CORE-INITIAL-SETUP.py --verify-only

You should see all green checkmarks (✓).

Manual verification commands:

# Check symlinks
ls -la ~/PROJECTS/.coditect ~/.coditect

# Check databases (ADR-118 Six-Tier)
ls ~/PROJECTS/.coditect-data/context-storage/*.db
sqlite3 ~/PROJECTS/.coditect-data/context-storage/sessions.db ".tables"

# Check services running
launchctl list | grep coditect

# Check watcher status
~/.coditect/bin/codi-watcher --status

# Check machine ID
cat ~/.coditect/machine-id.json | head -5

# Check installed products
ls ~/Library/Application\ Support/CODITECT/products/

# Check user component directories
ls ~/PROJECTS/.coditect-data/user-components/

Step 6: Start Using CODITECT

Activate the Environment

Every time you start a new terminal session, run:

source ~/.coditect/.venv/bin/activate

Your prompt will change to show (.venv) at the beginning.

Basic Commands

Command	What it does
`/orient`	Start of session - shows your project status
`/which "task"`	Find the right AI agent for a task
`/cx`	Save your session work (run at end of session)
`/cxq "search"`	Search your past work

What Gets Deployed

CODITECT installs background services that power the anti-forgetting memory system.

Background Services

Service	Purpose	How It Works
codi-watcher	Real-time context monitoring	Watches your Claude sessions, triggers `/cx` when context reaches 75%
context-indexer	Scheduled search indexing	Runs every 15 minutes, keeps `/cxq` search up-to-date

Service Architecture

┌─────────────────────────────────────────────────────────────────┐
│                 CODITECT Memory Automation                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  codi-watcher (Real-time)          context-indexer (Scheduled)  │
│  ┌─────────────────────┐           ┌─────────────────────────┐  │
│  │ • Watches sessions  │           │ • Runs every 15 min     │  │
│  │ • Counts tokens     │           │ • Extracts messages     │  │
│  │ • Triggers at 75%   │           │ • Builds search index   │  │
│  │ • Runs /cx auto     │           │ • Updates sessions.db   │  │
│  └──────────┬──────────┘           └────────────┬────────────┘  │
│             │                                    │               │
│             └────────────────┬───────────────────┘               │
│                              ▼                                   │
│              ┌───────────────────────────────────┐               │
│              │   ADR-118 Four-Tier Databases     │               │
│              │   • 74K+ messages indexed         │               │
│              │   • Full-text search (FTS5)       │               │
│              │   • Decisions, patterns, errors   │               │
│              └───────────────────────────────────┘               │
│                              │                                   │
│                              ▼                                   │
│                    /cxq "search query"                           │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Verify Services Are Running

# Check both services
launchctl list | grep coditect

# Expected output (two services with PID numbers):
# 12345  0  ai.coditect.context-watcher
# 67890  0  ai.coditect.context-indexer

# Check codi-watcher status
~/.coditect/bin/codi-watcher --status

# View service logs
tail -20 ~/PROJECTS/.coditect-data/logs/context-watcher.log
tail -20 ~/PROJECTS/.coditect-data/logs/context-indexer.log

Service Management

# Start services (if not running)
launchctl load ~/Library/LaunchAgents/ai.coditect.context-watcher.plist
launchctl load ~/Library/LaunchAgents/ai.coditect.context-indexer.plist

# Stop services
launchctl unload ~/Library/LaunchAgents/ai.coditect.context-watcher.plist
launchctl unload ~/Library/LaunchAgents/ai.coditect.context-indexer.plist

# Restart (stop then start)
launchctl unload ~/Library/LaunchAgents/ai.coditect.context-watcher.plist
launchctl load ~/Library/LaunchAgents/ai.coditect.context-watcher.plist

File Locations

File	Purpose
`~/.coditect/bin/codi-watcher`	Watcher binary
`~/PROJECTS/.coditect-data/context-storage/sessions.db`	Session data (Tier 3)
`~/PROJECTS/.coditect-data/logs/context-watcher.log`	Watcher logs
`~/PROJECTS/.coditect-data/logs/context-indexer.log`	Indexer logs
`~/Library/LaunchAgents/ai.coditect.context-watcher.plist`	macOS service config
`~/Library/LaunchAgents/ai.coditect.context-indexer.plist`	macOS service config

Complete File Inventory

After installation, these files and directories exist:

~/Library/Application Support/CODITECT/
├── core/                              # Protected installation (git repo)
│   ├── agents/                        # 776 AI agents
│   ├── commands/                      # 377 slash commands
│   ├── skills/                        # 445 reusable skills
│   ├── scripts/                       # Automation scripts
│   │   └── services/                  # launchd plist templates
│   ├── hooks/                         # Event triggers
│   ├── bin/                           # Binary executables
│   │   └── codi-watcher               # Context watcher daemon (v2.0.0)
│   ├── licensing/                     # License files
│   │   ├── license.json.template
│   │   └── validation-cache.json
│   ├── machine-id.json                # Hardware identifier
│   ├── .venv/                         # Python virtual environment
│   └── config/                        # Configuration files
│       └── config.json                # Product selections (persisted)
│
└── products/                          # Optional products (ADR-180)
    └── coditect-financial-model/      # Financial Model Engine
        ├── src/coditect_fm.py         # Engine script
        ├── requirements.txt
        └── .venv/                     # Product-specific venv

~/PROJECTS/
├── .coditect -> ~/Library/.../core/   # Primary symlink
├── .claude -> .coditect               # Compatibility symlink
└── .coditect-data/                    # User data (ADR-114)
    ├── context-storage/               # Databases and exports
    │   ├── org.db                     # Tier 2: CRITICAL - decisions, learnings
    │   ├── sessions.db                # Tier 3: Session data, messages
    │   ├── platform.db                # Tier 1: Component index
    │   ├── projects.db                # Tier 4: Project registry
    │   ├── messaging.db               # Tier 5: Inter-agent messaging
    │   ├── call_graph.db              # Tier 6: Code call graph
    │   ├── exports-pending/
    │   └── exports-archive/
    ├── session-logs/                  # Machine-specific logs
    ├── logs/                          # Service logs
    │   ├── context-watcher.log
    │   └── context-indexer.log
    └── user-components/               # User-created components (ADR-180)
        ├── agents/
        ├── skills/
        ├── commands/
        ├── hooks/
        └── README.md

~/.coditect -> ~/Library/.../core/     # Backward compat symlink

~/.claude/
├── settings.json                      # Claude Code settings (hooks)
├── statusline-command.sh              # Statusline script
└── statusline-config.json             # Statusline configuration

~/Library/LaunchAgents/
├── ai.coditect.context-watcher.plist  # Watcher service
└── ai.coditect.context-indexer.plist  # Indexer service

Troubleshooting

"Python version too old"

Install Python 3.12:

brew install python@3.12

Then run the installation script again.

"Git not found"

Install Git:

xcode-select --install

Click "Install" when prompted, then run the installation script again.

"Permission denied"

Run:

sudo chown -R $(whoami) ~/Library/Application\ Support/

Enter your Mac password when prompted, then run the installation script again.

"Symlink broken"

Run the installation script again. It will repair broken symlinks automatically.

"Services not running"

# Reload services
launchctl unload ~/Library/LaunchAgents/ai.coditect.context-watcher.plist 2>/dev/null
launchctl load ~/Library/LaunchAgents/ai.coditect.context-watcher.plist

launchctl unload ~/Library/LaunchAgents/ai.coditect.context-indexer.plist 2>/dev/null
launchctl load ~/Library/LaunchAgents/ai.coditect.context-indexer.plist

# Verify
launchctl list | grep coditect

"Database errors"

Reinitialize the database:

# Reinitialize ADR-118 Four-Tier databases
rm ~/PROJECTS/.coditect-data/context-storage/*.db
python3 ~/.coditect/scripts/context-db.py --init

Uninstalling CODITECT

If you need to remove CODITECT:

# Stop services first
launchctl unload ~/Library/LaunchAgents/ai.coditect.context-watcher.plist 2>/dev/null
launchctl unload ~/Library/LaunchAgents/ai.coditect.context-indexer.plist 2>/dev/null

# Remove service files
rm -f ~/Library/LaunchAgents/ai.coditect.context-*.plist

# Remove symlinks
rm -f ~/PROJECTS/.coditect
rm -f ~/PROJECTS/.claude
rm -f ~/.coditect

# Remove installation (this deletes core AND products)
rm -rf ~/Library/Application\ Support/CODITECT/

# Remove user data (optional - preserves your session history if skipped)
# rm -rf ~/PROJECTS/.coditect-data/

# Remove Claude Code config (optional - removes hooks too)
rm -f ~/.claude/statusline-*.sh ~/.claude/statusline-*.json

# Remove license record
rm -f ~/.coditect-license-accepted

Getting Help

Documentation: See the docs/ folder in your installation
Report issues: github.com/coditect-ai/coditect-core/issues

Installation complete. You are ready to use CODITECT.

Script Version: 3.0.0 | Build: 2026-02-12T19:30:00Z | Guide Version: 6.0.0 | Last Updated: February 12, 2026

Before You Begin​

GitHub Setup (First-Time Users)​

GitHub Step 1: Create a GitHub Account​

GitHub Step 2: Install GitHub CLI​

GitHub Step 3: Authenticate with GitHub​

GitHub Step 4: Set Up SSH Keys (Recommended)​

GitHub Step 5: Configure Git Protocol (Optional)​

GitHub Setup Complete​

Step 1: Open Terminal​

Step 2: Create Your Projects Folder​

Step 3: Download CODITECT​

Step 4: Run the Installation Script​

What Happens During Installation​

Phase 1: License Agreement​

Phase 2: Prerequisite Checks​

Phase 3: VS Code Installation (Optional)​

Phase 4: Detecting Existing Installations​

Phase 5: Installation Plan​

Phase 6: Installation Progress (19 Steps)​

Step 1 of 19: Clone Repository​

Step 2 of 19: Select Optional Products (NEW in v3.0.0)​

Step 3 of 19: Create Symlinks​

Step 4 of 19: Configure Claude Code​

Step 5 of 19: Initialize Databases​

Step 6 of 19: Generate Machine ID​

Step 7 of 19: Migrate Session Logs​

Step 8 of 19: Setup Python Environment​

Step 9 of 19: Configure Statusline​

Step 10 of 19: Install Context Watcher​

Step 11 of 19: Configure Backup​

Step 12 of 19: Initialize Licensing​

Step 13 of 19: Initialize Platform Database​

Step 14 of 19: Initialize Platform-Index Database​

Step 15 of 19: Initialize Projects Database​

Step 16 of 19: Configure MoE Tools​

Step 17 of 19: Install Selected Products (NEW in v3.0.0)​

Step 18 of 19: Setup User Component Directories (NEW in v3.0.0)​

Step 19 of 19: Apply Framework Protection​

Phase 7: Verification​

Phase 8: Installation Complete​

Step 5: Verify Your Installation​

Step 6: Start Using CODITECT​

Activate the Environment​

Basic Commands​

What Gets Deployed​

Background Services​

Service Architecture​

Verify Services Are Running​

Service Management​

File Locations​

Complete File Inventory​

Troubleshooting​

"Python version too old"​

"Git not found"​

"Permission denied"​

"Symlink broken"​

"Services not running"​

"Database errors"​

Uninstalling CODITECT​

Getting Help​

Related Documentation​

Before You Begin

GitHub Setup (First-Time Users)

GitHub Step 1: Create a GitHub Account

GitHub Step 2: Install GitHub CLI

GitHub Step 3: Authenticate with GitHub

GitHub Step 4: Set Up SSH Keys (Recommended)

GitHub Step 5: Configure Git Protocol (Optional)

GitHub Setup Complete

Step 1: Open Terminal

Step 2: Create Your Projects Folder

Step 3: Download CODITECT

Step 4: Run the Installation Script

What Happens During Installation

Phase 1: License Agreement

Phase 2: Prerequisite Checks

Phase 3: VS Code Installation (Optional)

Phase 4: Detecting Existing Installations

Phase 5: Installation Plan

Phase 6: Installation Progress (19 Steps)

Step 1 of 19: Clone Repository

Step 2 of 19: Select Optional Products (NEW in v3.0.0)

Step 3 of 19: Create Symlinks

Step 4 of 19: Configure Claude Code

Step 5 of 19: Initialize Databases

Step 6 of 19: Generate Machine ID

Step 7 of 19: Migrate Session Logs

Step 8 of 19: Setup Python Environment

Step 9 of 19: Configure Statusline

Step 10 of 19: Install Context Watcher

Step 11 of 19: Configure Backup

Step 12 of 19: Initialize Licensing

Step 13 of 19: Initialize Platform Database

Step 14 of 19: Initialize Platform-Index Database

Step 15 of 19: Initialize Projects Database

Step 16 of 19: Configure MoE Tools

Step 17 of 19: Install Selected Products (NEW in v3.0.0)

Step 18 of 19: Setup User Component Directories (NEW in v3.0.0)

Step 19 of 19: Apply Framework Protection

Phase 7: Verification

Phase 8: Installation Complete

Step 5: Verify Your Installation

Step 6: Start Using CODITECT

Activate the Environment

Basic Commands

What Gets Deployed

Background Services

Service Architecture

Verify Services Are Running

Service Management

File Locations

Complete File Inventory

Troubleshooting

"Python version too old"

"Git not found"

"Permission denied"

"Symlink broken"

"Services not running"

"Database errors"

Uninstalling CODITECT

Getting Help

Related Documentation