User Quick Start Guide

Complete CODITECT installation in 20 minutes. This guide mirrors CODITECT-CORE-INITIAL-SETUP.py v2.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 H.P.009-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 H.P.007-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 H.P.009-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, H.P.009-CONFIGure Git to use SSH by default:

gh H.P.009-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 H.P.009-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 H.P.002-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/H.P.004-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
  • Create symlink ~/PROJECTS/.coditect -> protected location
  • Create symlink ~/PROJECTS/.claude -> .coditect
  • Create backward compat symlink ~/.coditect -> protected location
  • Configure H.P.005-HOOKS
  • Initialize context database
  • Generate unique machine identifier
  • Set up Python virtual environment
  • Configure statusline
  • Install context services (watcher + indexer)
  • Initialize licensing

PROTECTED LOCATION:
  /Users/YOU/Library/Application Support/CODITECT/
  (Hidden from Finder, safe from accidental modification)

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

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

Phase 6: Installation Progress (10 Steps)

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

Step 1 of 10: Clone Repository

[1/10] 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 10: Create Symlinks

[2/10] 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 3 of 10: Configure Claude Code

[3/10] Configuring Claude Code
       ✓ Configured Claude Code H.P.005-HOOKS

What happens:

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

Hooks H.P.009-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 4 of 10: Initialize Database

[4/10] Initializing context database
       ✓ Initialized database with 8 tables
       ✓ 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 database with FTS5 full-text search
Creates 8 tables with indexes and triggers

Database tables created:

Table	Purpose
`messages`	Session messages with full-text search
`sessions`	Session metadata (start, end, tokens)
`decisions`	Architectural decisions extracted
`patterns`	Code patterns and solutions
`errors`	Error-solution pairs
`skill_learnings`	Accumulated skill improvements
`sync_queue`	Offline sync queue for cloud
`migrations`	Schema version tracking

Files created (ADR-118 Four-Tier):

~/PROJECTS/.coditect-data/context-storage/org.db - Tier 2: CRITICAL (decisions, learnings)
~/PROJECTS/.coditect-data/context-storage/sessions.db - Tier 3: Messages, activities
~/PROJECTS/.coditect-data/context-storage/platform.db - Tier 1: Component index
~/PROJECTS/.coditect-data/context-storage/exports-pending/ - Pending exports
~/PROJECTS/.coditect-data/context-storage/exports-archive/ - Processed exports
~/.coditect/logs/ - Service logs directory

Step 5 of 10: Generate Machine ID

[5/10] 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
Creates session-logs-cache/ for logs from other machines

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 6 of 10: Migrate Session Logs

[6/10] 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
Preserves original creation dates

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

Step 7 of 10: Setup Python Environment

[7/10] 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 8 of 10: Configure Statusline

[8/10] 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-H.P.009-CONFIG.json - Section H.P.009-CONFIGuration
Enables all 7 statusline sections by default

Statusline sections:

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

Example statusline:

─[📁:myproject]─[⎇:main✓↑1]─[🤖:Opus 42%]─[⚙:🐍venv ⬢22.1]─[💻:🔋85%]─[👤:you@mac 14:23]─

Files created:

~/.claude/statusline-command.sh - Statusline generation script
~/.claude/statusline-H.P.009-CONFIG.json - Section toggle H.P.009-CONFIGuration

Step 9 of 10: Install Context Services

[9/10] Installing context services
       ✓ Installed codi-watcher 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 binary (Rust)
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
~/Library/LaunchAgents/ai.coditect.context-watcher.plist - Watcher service H.P.009-CONFIG
~/Library/LaunchAgents/ai.coditect.context-indexer.plist - Indexer service H.P.009-CONFIG

Step 10 of 10: Initialize Licensing

[10/10] Initializing licensing
        ✓ Created licensing directory
        ✓ Created license H.P.008-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

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
✓ Database initialized (8 tables)
✓ Claude Code H.P.005-HOOKS H.P.009-CONFIGured
✓ Python virtual environment ready
✓ Directory H.P.001-AGENTS/ (152 items)
✓ Directory H.P.002-COMMANDS/ (184 items)
✓ Directory H.P.003-SKILLS/ (221 items)
✓ Machine ID: a1b2c3d4... (your-mac)
✓ Statusline H.P.009-CONFIGured (7/7 sections enabled)
✓ Context watcher binary installed
✓ Context watcher service running
✓ Context indexer service installed (runs every 15 min)
✓ Logs directory created
✓ Licensing directory initialized

All items should show green checkmarks (✓).

Phase 8: Installation Complete

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

✓ CODITECT Core v2.0.0 has been successfully installed!

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

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

Next Steps:

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

2. Start your AI-powered workflow:
   /orient

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/H.P.004-SCRIPTS/CODITECT-CORE-INITIAL-SETUP.py --verify-only

You should see all green checkmarks (✓).

Manual verification H.P.002-COMMANDS:

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

# Check databases (ADR-118 Four-Tier)
sqlite3 ~/PROJECTS/.coditect-data/context-storage/sessions.db ".tables"  # Tier 3: messages
sqlite3 ~/PROJECTS/.coditect-data/context-storage/org.db ".tables"       # Tier 2: decisions

# 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

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 databases     │  │
│  └──────────┬──────────┘           └────────────┬────────────┘  │
│             │                                    │               │
│             └────────────────┬───────────────────┘               │
│                              ▼                                   │
│              ┌───────────────────────────────────┐               │
│              │   ADR-118 Four-Tier Architecture  │               │
│              │   • org.db: decisions, learnings  │               │
│              │   • sessions.db: messages (FTS5)  │               │
│              │   • 74K+ messages indexed         │               │
│              └───────────────────────────────────┘               │
│                              │                                   │
│                              ▼                                   │
│                    /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 ~/.coditect/logs/context-watcher.log
tail -20 ~/.coditect/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/org.db`	Tier 2: Decisions, learnings (CRITICAL)
`~/PROJECTS/.coditect-data/context-storage/sessions.db`	Tier 3: Messages, search index
`~/.coditect/logs/context-watcher.log`	Watcher logs
`~/.coditect/logs/context-indexer.log`	Indexer logs
`~/Library/LaunchAgents/ai.coditect.context-watcher.plist`	macOS service H.P.009-CONFIG
`~/Library/LaunchAgents/ai.coditect.context-indexer.plist`	macOS service H.P.009-CONFIG

Complete File Inventory

After installation, these files and directories exist:

~/Library/Application Support/CODITECT/
└── core/                              # Protected installation (git repo)
    ├── H.P.001-AGENTS/                        # 152 AI H.P.001-AGENTS
    ├── H.P.002-COMMANDS/                      # 184 slash H.P.002-COMMANDS
    ├── H.P.003-SKILLS/                        # 221 reusable H.P.003-SKILLS
    ├── H.P.004-SCRIPTS/                       # Automation H.P.004-SCRIPTS
    │   └── services/                  # launchd plist H.P.008-TEMPLATES
    ├── H.P.005-HOOKS/                         # Event triggers
    ├── bin/                           # Binary executables
    │   └── codi-watcher               # Context watcher daemon
    ├── logs/                          # Service logs
    │   ├── context-watcher.log
    │   └── context-indexer.log
    ├── licensing/                     # License files
    │   ├── license.json.template
    │   └── validation-cache.json
    ├── context-storage/               # Database and exports (ADR-118)
    │   ├── org.db                     # Tier 2: decisions, learnings (CRITICAL)
    │   ├── sessions.db                # Tier 3: messages, activities
    │   ├── platform.db                # Tier 1: component index
    │   ├── exports-pending/
    │   └── exports-archive/
    ├── session-logs/                  # Machine-specific logs
    ├── session-logs-cache/            # Logs from other machines
    ├── machine-id.json                # Hardware identifier
    ├── .venv/                         # Python virtual environment
    └── H.P.009-CONFIG/                        # Configuration files

~/PROJECTS/
├── .coditect -> ~/Library/.../core/   # Primary symlink
└── .claude -> .coditect               # Compatibility symlink

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

~/.claude/
├── settings.json                      # Claude Code settings (H.P.005-HOOKS)
├── statusline-command.sh              # Statusline script
└── statusline-H.P.009-CONFIG.json             # Statusline H.P.009-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 databases (ADR-118 Four-Tier):

# Reinitialize sessions.db (Tier 3 - regenerable from exports)
rm ~/PROJECTS/.coditect-data/context-storage/sessions.db
python3 ~/.coditect/scripts/context-query.py --init

# WARNING: org.db contains IRREPLACEABLE data (decisions, learnings)
# Only reinitialize if you have a backup or are starting fresh:
# rm ~/PROJECTS/.coditect-data/context-storage/org.db

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 all data)
rm -rf ~/Library/Application\ Support/CODITECT/

# Remove Claude Code H.P.009-CONFIG (optional - removes H.P.005-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: 2.0.0 | Build: 2026-01-13T20:29:01Z | Guide Version: 5.0.0 | Last Updated: January 13, 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 (10 Steps)​

Step 1 of 10: Clone Repository​

Step 2 of 10: Create Symlinks​

Step 3 of 10: Configure Claude Code​

Step 4 of 10: Initialize Database​

Step 5 of 10: Generate Machine ID​

Step 6 of 10: Migrate Session Logs​

Step 7 of 10: Setup Python Environment​

Step 8 of 10: Configure Statusline​

Step 9 of 10: Install Context Services​

Step 10 of 10: Initialize Licensing​

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 (10 Steps)

Step 1 of 10: Clone Repository

Step 2 of 10: Create Symlinks

Step 3 of 10: Configure Claude Code

Step 4 of 10: Initialize Database

Step 5 of 10: Generate Machine ID

Step 6 of 10: Migrate Session Logs

Step 7 of 10: Setup Python Environment

Step 8 of 10: Configure Statusline

Step 9 of 10: Install Context Services

Step 10 of 10: Initialize Licensing

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