Skip to main content

ADR-066: Context Automation Services

Status​

Accepted | January 12, 2026

Context​

Claude Code sessions accumulate context (tokens) over time, eventually reaching the context limit (~200K tokens). When this happens, the session must be exported and context cleared to continue working. Previously, users had to manually:

  1. Monitor context percentage
  2. Run /export when threshold reached
  3. Run /cx to process exports into the database
  4. Archive processed files

This manual process was error-prone and often resulted in lost context when users forgot to export before hitting limits.

Decision​

Implement two complementary background services for complete context automation:

  1. codi-watcher - Real-time monitoring that triggers exports when context threshold is reached
  2. context-indexer - Scheduled service that extracts and indexes messages for /cxq searchability

Two-Service Architecture​

┌─────────────────────────────────────────────────────────────────────────────┐
│                     CODITECT Context Automation                              │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                              │
│  ┌─────────────────────────────┐    ┌─────────────────────────────────────┐ │
│  │     codi-watcher            │    │     context-indexer                 │ │
│  │  (Real-time Monitoring)     │    │  (Scheduled Processing)            │ │
│  ├─────────────────────────────┤    ├─────────────────────────────────────┤ │
│  │ • Watches JSONL files       │    │ • Runs every 15 minutes            │ │
│  │ • Counts tokens per session │    │ • Extracts from all sessions       │ │
│  │ • Triggers at 75% threshold │    │ • Builds FTS5 search index         │ │
│  │ • Runs /cx after export     │    │ • Updates context.db               │ │
│  └──────────────┬──────────────┘    └──────────────┬──────────────────────┘ │
│                 │                                   │                        │
│                 ▼                                   ▼                        │
│  ┌──────────────────────────────────────────────────────────────────────┐   │
│  │                    context-storage/context.db                         │   │
│  │                    (SQLite with FTS5 + Analytics)                     │   │
│  └──────────────────────────────────────────────────────────────────────┘   │
│                                    │                                         │
│                                    ▼                                         │
│                           /cxq "search query"                                │
│                                                                              │
└─────────────────────────────────────────────────────────────────────────────┘

Service 1: codi-watcher (Real-time Export)​

Architecture​

┌─────────────────────────────────────────────────────────────────────┐
│                    Context Watcher Service                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────────┐   │
│  │  File Watcher │───▶│ Token Counter │───▶│ Export Trigger    │   │
│  │  (notify-rs)  │    │ (per session) │    │ (threshold-based) │   │
│  └───────────────┘    └───────────────┘    └───────────────────┘   │
│         │                                           │               │
│         │                                           ▼               │
│         │                                  ┌───────────────────┐   │
│         │                                  │ /cx Processing    │   │
│         │                                  │ (Python extractor)│   │
│         │                                  └───────────────────┘   │
│         │                                           │               │
│         ▼                                           ▼               │
│  ┌───────────────┐    ┌───────────────┐    ┌───────────────────┐   │
│  │   Process     │───▶│    Session    │───▶│    State          │   │
│  │   Detector    │    │   Correlator  │    │    Manager        │   │
│  └───────────────┘    └───────────────┘    └───────────────────┘   │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Components​

  1. File Watcher (notify-rs)

    • Watches ~/.claude/projects/ for JSONL file changes
    • Triggers token counting on file modification events
    • 10-second timeout fallback for missed events

  2. Token Counter

    • Parses JSONL session files for token usage
    • Fields: cache_read_input_tokens, cache_creation_input_tokens, input_tokens, output_tokens
    • Calculates percentage against 200K limit

  3. Export Trigger

    • Triggers when context >= threshold (default 75%)
    • Warning at max threshold (default 95%)
    • Cooldown between exports (default 10 minutes per session)

  4. Process Detector

    • Detects running Claude processes via pgrep -x claude
    • Maps process cwd to session folders via lsof -p PID | grep cwd
    • Updates state every 30 seconds (configurable via --process-interval)

  5. /cx Processing

    • Calls Python unified-message-extractor.py for each export
    • Extracts messages and inserts into SQLite database
    • Archives processed files

  6. State Manager

    • Persists to ~/PROJECTS/.coditect-data/context-storage/context-watcher-state.json
    • Tracks: cooldowns, exports triggered, active processes, last check

Binary Naming Workaround (CRITICAL)​

Binary name: codi-watcher (NOT coditect-context-watch)

Claude Code shell integration automatically backgrounds any command containing "context-watch" in the binary name. This causes the binary to hang on startup when run from launchd, creating zombie processes in "UE" (Uninterruptible + Exit) state.

Symptoms of incorrect naming:

  • Service shows exit status -9 (SIGKILL) in launchctl list
  • Binary hangs when run manually (appears to run in background)
  • Zombie processes accumulate that cannot be killed

Solution: The binary is renamed to codi-watcher to avoid triggering this shell integration behavior.

# CORRECT - works
~/.coditect/bin/codi-watcher --version

# INCORRECT - will hang
~/.coditect/bin/coditect-context-watch --version  # DO NOT USE

File Locations​

PathPurpose
~/.coditect/bin/codi-watcherBinary executable
~/.coditect/tools/context-watcher/Source code
~/PROJECTS/.coditect-data/context-storage/context-watcher-state.jsonState file
~/PROJECTS/.coditect-data/context-storage/exports-pending/Pending exports
~/PROJECTS/.coditect-data/context-storage/exports-archive/Processed exports
~/.coditect/logs/context-watcher.logcodi-watcher logs
~/.coditect/logs/context-indexer.logcontext-indexer logs
~/Library/LaunchAgents/ai.coditect.context-watcher.plistcodi-watcher launchd service
~/Library/LaunchAgents/ai.coditect.context-indexer.plistcontext-indexer launchd service

CLI Options​

codi-watcher [OPTIONS]

Options:
  -t, --threshold <N>         Export threshold percentage (default: 75)
      --max-threshold <N>     Warning threshold percentage (default: 95)
      --process-interval <N>  Process detection interval in seconds (default: 30)
      --cooldown <N>          Export cooldown in minutes (default: 10)
      --projects-dir <PATH>   Custom projects directory
      --dry-run               Preview mode (no exports)
      --no-notify             Disable desktop notifications
  -v, --verbose               Debug logging
      --status                Show current status and exit

Process Detection Flow​

1. pgrep -x claude
   └── Returns PIDs: 196, 19559, 28943

2. lsof -p 196,19559,28943 | grep cwd
   └── Returns working directories for each PID

3. Map cwd → session folder
   /Users/hal/PROJECTS/foo
   → ~/.claude/projects/-Users-hal-PROJECTS-foo/

4. Find active session file
   → c641f73a-e4ae-4969-a889-00f5c55e2b0b.jsonl

Service Management (macOS)​

# Start
launchctl load ~/Library/LaunchAgents/ai.coditect.context-watcher.plist

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

# Status
launchctl list | grep coditect

# Logs
tail -f ~/.coditect/logs/context-watcher.log

Service 2: context-indexer (Scheduled Extraction & Indexing)​

The context-indexer runs on a fixed schedule to ensure the context database is always up-to-date and searchable via /cxq.

Purpose​

While codi-watcher handles real-time exports when thresholds are reached, context-indexer ensures:

  1. Regular extraction - All JSONL sessions are processed into the unified message store
  2. FTS5 indexing - Messages are indexed for full-text search
  3. Analytics updates - Token economics and tool analytics are current
  4. Searchability - /cxq queries return recent messages within 15 minutes

Architecture​

┌─────────────────────────────────────────────────────────────────┐
│                    Context Indexer Service                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌─────────────────┐    ┌─────────────────┐    ┌─────────────┐  │
│  │  launchd Timer  │───▶│  Message        │───▶│  FTS5       │  │
│  │  (every 15 min) │    │  Extractor      │    │  Indexer    │  │
│  └─────────────────┘    └─────────────────┘    └─────────────┘  │
│                                │                      │          │
│                                ▼                      ▼          │
│                    unified_messages.jsonl      context.db        │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

File Locations​

PathPurpose
~/Library/LaunchAgents/ai.coditect.context-indexer.plistmacOS launchd service
~/.coditect/logs/context-indexer.logService logs
~/PROJECTS/.coditect-data/context-storage/unified_messages.jsonlExtracted messages
~/PROJECTS/.coditect-data/context-storage/context.dbSQLite database with FTS5

Configuration​

SettingValueDescription
Interval900 seconds (15 min)Time between runs
RunAtLoadtrueStart immediately on load
OperationsExtract → IndexTwo-phase processing

launchd Plist​

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>ai.coditect.context-indexer</string>
    <key>ProgramArguments</key>
    <array>
        <string>/bin/bash</string>
        <string>-c</string>
        <string>cd ~/.coditect && python3 scripts/unified-message-extractor.py --no-index 2>&1 | head -50 >> logs/context-indexer.log && python3 scripts/context-db.py --index >> logs/context-indexer.log 2>&1</string>
    </array>
    <key>StartInterval</key>
    <integer>900</integer>
    <key>RunAtLoad</key>
    <true/>
    <key>StandardOutPath</key>
    <string>~/.coditect/logs/context-indexer.log</string>
    <key>StandardErrorPath</key>
    <string>~/.coditect/logs/context-indexer.log</string>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:/opt/homebrew/bin</string>
    </dict>
</dict>
</plist>

Service Management​

# Start
launchctl load ~/Library/LaunchAgents/ai.coditect.context-indexer.plist

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

# Status (both services)
launchctl list | grep coditect

# Logs
tail -f ~/.coditect/logs/context-indexer.log

# Manual run
cd ~/.coditect && python3 scripts/unified-message-extractor.py && python3 scripts/context-db.py --index

Combined Service Management​

Check Both Services​

# Status of all CODITECT services
launchctl list | grep coditect

# Expected output:
# PID    Status  Label
# 12345  0       ai.coditect.context-indexer
# 67890  0       ai.coditect.context-watcher

Start/Stop All​

# Start both services
launchctl load ~/Library/LaunchAgents/ai.coditect.context-watcher.plist
launchctl load ~/Library/LaunchAgents/ai.coditect.context-indexer.plist

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

View All Logs​

# Combined log view
tail -f ~/.coditect/logs/context-watcher.log ~/.coditect/logs/context-indexer.log

Consequences​

Positive​

  • Automatic context preservation: No more lost context from forgotten exports
  • Proactive monitoring: Exports triggered before hitting limits
  • Always-searchable context: Messages indexed within 15 minutes of creation
  • Process awareness: Tracks which Claude sessions are actively running
  • Unified /cx processing: Automatic message extraction to database
  • Desktop notifications: Optional alerts when exports occur
  • Zero manual intervention: Both services run automatically in background

Negative​

  • Background resource usage: Continuous file watching and periodic process detection
  • Dependency on Python: /cx processing requires Python extractor script
  • macOS-focused: launchd integration is macOS-specific (Linux uses systemd)
  • Periodic CPU spikes: Indexer processes all 1600+ session files every 15 minutes

Neutral​

  • State file dependency: Requires persistent state for cooldown tracking
  • Binary distribution: Must rebuild and reinstall after code changes
  • Two services to manage: Slightly more complex than single service

Implementation​

  • Source: coditect-core/tools/context-watcher/src/main.rs
  • Library: coditect-core/codanna/src/watcher/context_watcher.rs
  • Python extractor: ~/.coditect/scripts/unified-message-extractor.py

Build and Deployment​

Build Process​

The codi-watcher binary is built using Cargo and released via GitHub Actions.

Local Development Build​

cd ~/.coditect/tools/context-watcher

# Debug build
cargo build

# Release build (optimized)
cargo build --release

# Binary location
./target/release/codi-watcher --version

GitHub Actions Release Workflow​

Workflow: .github/workflows/release-codi-watcher.yml

Triggers:

  • Push tag codi-watcher-v* (e.g., codi-watcher-v0.3.0)
  • Manual workflow dispatch with version input

Build Matrix:

TargetOS RunnerArtifact Name
aarch64-apple-darwinmacos-latestcodi-watcher-darwin-arm64
x86_64-apple-darwinmacos-15-intelcodi-watcher-darwin-x86_64
x86_64-unknown-linux-gnuubuntu-latestcodi-watcher-linux-x86_64

Release Process:

# 1. Bump version in Cargo.toml
vim tools/context-watcher/Cargo.toml
# Change: version = "0.3.0" → "0.4.0"

# 2. Commit and push
git add -A && git commit -m "chore: bump codi-watcher to v0.4.0"
git push origin main

# 3. Create and push tag
git tag codi-watcher-v0.4.0
git push origin codi-watcher-v0.4.0

# 4. GitHub Actions automatically:
#    - Builds for all 3 platforms (darwin-arm64, darwin-x86_64, linux-x86_64)
#    - Creates SHA256 checksums for each binary
#    - Creates GitHub Release with binaries (private repo)
#    - Authenticates to GCS using GCS_SA_KEY secret
#    - Uploads binaries to gs://coditect-dist/codi-watcher/v{VERSION}/
#    - Verifies public access to uploaded binaries

Required GitHub Secret:

SecretPurposePermissions
GCS_SA_KEYService account JSON keyStorage Object Admin on gs://coditect-dist/

Create Service Account:

# Create service account
gcloud iam service-accounts create codi-watcher-release \
  --display-name="codi-watcher Release CI" \
  --project=coditect-citus-prod

# Grant Storage Object Admin on bucket
gsutil iam ch \
  serviceAccount:codi-watcher-release@coditect-citus-prod.iam.gserviceaccount.com:objectAdmin \
  gs://coditect-dist

# Create and download key
gcloud iam service-accounts keys create key.json \
  --iam-account=codi-watcher-release@coditect-citus-prod.iam.gserviceaccount.com

# Add to GitHub secrets as GCS_SA_KEY (paste entire JSON content)

Binary Distribution​

Distribution Channels​

┌─────────────────────────────────────────────────────────────────────────┐
│                     Binary Distribution Architecture                     │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────┐     ┌────────────────────┐     ┌────────────────┐  │
│  │  GitHub Actions │────▶│  GitHub Releases   │────▶│  GCS Upload    │  │
│  │  (Build)        │     │  (Private Repo)    │     │  (Automated)   │  │
│  └─────────────────┘     └────────────────────┘     └────────┬───────┘  │
│                                                               │          │
│                                                               ▼          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                  GCS Bucket (Public Distribution)                    ││
│  │                  gs://coditect-dist/codi-watcher/                    ││
│  │                                                                      ││
│  │  URL Pattern:                                                        ││
│  │  https://storage.googleapis.com/coditect-dist/codi-watcher/v{VER}/  ││
│  │                                                                      ││
│  │  ┌──────────────────┐ ┌──────────────────┐ ┌──────────────────┐    ││
│  │  │ darwin-arm64     │ │ darwin-x86_64    │ │ linux-x86_64     │    ││
│  │  │ + .sha256        │ │ + .sha256        │ │ + .sha256        │    ││
│  │  └──────────────────┘ └──────────────────┘ └──────────────────┘    ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                   │                                      │
│                                   ▼                                      │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                     Installation Script                              ││
│  │                     CODITECT-CORE-INITIAL-SETUP.py                   ││
│  │                                                                      ││
│  │  1. Detect platform (darwin/linux, arm64/x86_64)                    ││
│  │  2. Download from GCS public URL                                    ││
│  │  3. Verify SHA256 checksum                                          ││
│  │  4. Install to ~/.coditect/bin/codi-watcher                         ││
│  │  5. Configure launchd service                                       ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

1. GCS Bucket (Primary - Public)​

Bucket: gs://coditect-dist Project: coditect-citus-prod Access: Public read (no authentication required)

Live URLs (v0.3.0):

PlatformDownload URL
macOS ARM64https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-darwin-arm64
macOS x86_64https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-darwin-x86_64
Linux x86_64https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-linux-x86_64

Checksum Verification:

# Download and verify
curl -sL "https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-darwin-arm64.sha256"
shasum -a 256 codi-watcher-darwin-arm64

Structure:

gs://coditect-dist/
└── codi-watcher/
    └── v0.3.0/
        ├── codi-watcher-darwin-arm64        (2.9 MB)
        ├── codi-watcher-darwin-arm64.sha256
        ├── codi-watcher-darwin-x86_64       (3.0 MB)
        ├── codi-watcher-darwin-x86_64.sha256
        ├── codi-watcher-linux-x86_64
        └── codi-watcher-linux-x86_64.sha256

Benefits:

  • Public access - no authentication required
  • Fast downloads via Google's CDN
  • Automatic upload from GitHub Actions
  • Checksum verification for integrity

2. GitHub Releases (Internal - Private Repo)​

URL: https://github.com/coditect-ai/coditect-core/releases Access: Private (requires authentication)

The GitHub repo is private, so releases are only accessible to authenticated users. GCS is used for public distribution.

Used as fallback when:

  • User has GitHub authentication configured
  • GCS bucket temporarily unavailable
  • Development/testing scenarios

Installation Script​

Script: ~/.coditect/scripts/install-context-watcher.py

Installation Flow​

┌─────────────────────────────────────────────────────────────────────────┐
│                     Installation Flow                                    │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  1. Detect Platform                                                      │
│     ├── platform.system() → darwin/linux                                 │
│     └── platform.machine() → arm64/x86_64                                │
│                                                                          │
│  2. Select Artifact                                                      │
│     ├── darwin + arm64 → codi-watcher-darwin-arm64                       │
│     ├── darwin + x86_64 → codi-watcher-darwin-x86_64                     │
│     └── linux + x86_64 → codi-watcher-linux-x86_64                       │
│                                                                          │
│  3. Download Binary (Priority Order)                                     │
│     ├── a) API → Signed GCS URL (requires machine-id.json)               │
│     ├── b) gh CLI → GitHub Release (handles auth/redirects)              │
│     └── c) curl -L → GitHub Release (follows redirects)                  │
│                                                                          │
│  4. Verify Checksum                                                      │
│     └── SHA256 verification against .sha256 file                         │
│                                                                          │
│  5. macOS Code Signing                                                   │
│     └── codesign --force --sign - (ad-hoc re-signing required)           │
│                                                                          │
│  6. Install Service                                                      │
│     ├── macOS: launchctl load ~/Library/LaunchAgents/...plist            │
│     └── Linux: systemctl --user enable/start                             │
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Usage​

# Standard installation (uses API → GCS → GitHub fallback)
python3 ~/.coditect/scripts/install-context-watcher.py

# Force re-download (even if binary exists)
python3 ~/.coditect/scripts/install-context-watcher.py --download

# GitHub-only (bypass API, direct from releases)
python3 ~/.coditect/scripts/install-context-watcher.py --github

# Check service status
python3 ~/.coditect/scripts/install-context-watcher.py --status

# Uninstall
python3 ~/.coditect/scripts/install-context-watcher.py --uninstall

macOS Code Signing​

Critical: macOS invalidates ad-hoc code signatures when binaries are copied. The binary must be re-signed after installation.

Symptoms of invalid signature:

  • Binary killed with SIGKILL on launch
  • Crash report shows Code Signature Invalid
  • Taskgated rejection in system logs

Solution (automatic in install script):

codesign --force --sign - ~/.coditect/bin/codi-watcher

This creates a new ad-hoc signature that macOS accepts for local execution.

Public Distribution URLs​

CODITECT Framework Installation​

ResourcePublic URL
Bootstrap Scripthttps://storage.googleapis.com/coditect-dist/install.py
Quick Start Guidehttps://storage.googleapis.com/coditect-dist/docs/USER-QUICK-START.md

Installation Command:

curl -sL https://storage.googleapis.com/coditect-dist/install.py | python3

codi-watcher Binary Distribution​

PlatformDownload URL
macOS ARM64https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-darwin-arm64
macOS x86_64https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-darwin-x86_64
Linux x86_64https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-linux-x86_64

Checksum Verification:

# Download checksum
curl -sL "https://storage.googleapis.com/coditect-dist/codi-watcher/v0.3.0/codi-watcher-darwin-arm64.sha256"

# Verify binary
shasum -a 256 codi-watcher-darwin-arm64

GCS Bucket Structure​

gs://coditect-dist/
├── install.py                           # Bootstrap installer
├── docs/
│   └── USER-QUICK-START.md              # Installation guide
└── codi-watcher/
    └── v0.3.0/
        ├── codi-watcher-darwin-arm64    # macOS Apple Silicon
        ├── codi-watcher-darwin-arm64.sha256
        ├── codi-watcher-darwin-x86_64   # macOS Intel
        ├── codi-watcher-darwin-x86_64.sha256
        ├── codi-watcher-linux-x86_64    # Linux
        └── codi-watcher-linux-x86_64.sha256

Update Mechanism​

CODITECT installations need a reliable update mechanism to receive bug fixes and new features. The update system uses version tracking and GCS distribution.

Version Architecture​

┌─────────────────────────────────────────────────────────────────────────┐
│                     CODITECT Update Architecture                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                        /orient (Session Start)                       ││
│  │                                                                      ││
│  │  1. Read ~/.coditect/VERSION (local installed version)              ││
│  │  2. Fetch gs://coditect-dist/version.json (latest available)        ││
│  │  3. Compare versions                                                 ││
│  │  4. Display notification if update available                         ││
│  │     "⚠ Update available: v1.0.0 → v1.1.0. Run /update"              ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                           /update Command                            ││
│  │                                                                      ││
│  │  1. Verify target is protected location (not submodule)             ││
│  │  2. git fetch origin main                                           ││
│  │  3. Show changelog (commits since current version)                  ││
│  │  4. git pull --rebase origin main                                   ││
│  │  5. pip install -r requirements.txt (if changed)                    ││
│  │  6. Update ~/.coditect/VERSION                                      ││
│  │  7. "✓ Updated to v1.1.0"                                           ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

Version Files​

FileLocationPurpose
VERSION~/.coditect/VERSIONLocal installed version (e.g., 1.0.0)
version.jsongs://coditect-dist/version.jsonLatest available version info

version.json Format:

{
  "latest": "1.0.0",
  "released": "2026-01-12",
  "changelog": "https://github.com/coditect-ai/coditect-core/releases/tag/v1.0.0",
  "min_supported": "1.0.0",
  "update_message": "Initial release"
}

Update Safety​

Key Design Principle: Updates ONLY affect the protected installation location.

~/.coditect → ~/Library/Application Support/CODITECT/core/
              ↑
              └── git pull updates THIS location only

Developer Safety: The update script detects if it's running in a git submodule and aborts:

This appears to be a development submodule.
Use 'git pull' directly instead of /update.

Update Command​

Script: ~/.coditect/scripts/update-coditect.py

# Check for updates (dry run)
/update --check

# Update to latest
/update

# Force update (skip confirmation)
/update --yes

Version Check in /orient​

The /orient command checks for updates on session start with rate limiting:

  1. Check ~/PROJECTS/.coditect-data/context-storage/version-check.json for cached result
  2. If cache expired (>24 hours), fetch gs://coditect-dist/version.json
  3. Compare with local ~/.coditect/VERSION
  4. Display notification if update available

Cache File: ~/PROJECTS/.coditect-data/context-storage/version-check.json

{
  "checked_at": "2026-01-12T20:00:00Z",
  "latest": "1.1.0",
  "current": "1.0.0",
  "update_available": true
}

GCS Version Distribution​

URL: https://storage.googleapis.com/coditect-dist/version.json

Updated on each release via GitHub Actions workflow.

Release Process​

# 1. Bump version
echo "1.1.0" > VERSION
git add VERSION && git commit -m "chore: bump version to 1.1.0"

# 2. Create tag
git tag v1.1.0
git push origin main --tags

# 3. GitHub Actions automatically:
#    - Updates gs://coditect-dist/version.json
#    - Creates GitHub Release

Removal Mechanism​

CODITECT provides a clean uninstall process that safely removes all installation components while optionally preserving user data.

Uninstall Architecture​

┌─────────────────────────────────────────────────────────────────────────┐
│                     CODITECT Uninstall Process                           │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                        /uninstall Command                            ││
│  │                                                                      ││
│  │  1. Stop background services (codi-watcher daemon)                  ││
│  │  2. Remove symlinks (~/.coditect, ~/PROJECTS/.coditect, .claude)    ││
│  │  3. Clean Claude Code settings (statusLine, hooks)                  ││
│  │  4. Remove launchd plist (macOS)                                    ││
│  │  5. Remove protected installation directory                         ││
│  │     Optional: --keep-data preserves context-storage/, session-logs/ ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
│  ┌─────────────────────────────────────────────────────────────────────┐│
│  │                    Components Removed                                ││
│  │                                                                      ││
│  │  Symlinks:                                                           ││
│  │    ~/.coditect → (removed)                                          ││
│  │    ~/PROJECTS/.coditect → (removed)                                 ││
│  │    ~/PROJECTS/.claude → (removed)                                   ││
│  │                                                                      ││
│  │  Protected Directory:                                                ││
│  │    macOS: ~/Library/Application Support/CODITECT/core/ → (removed) ││
│  │    Linux: ~/.local/share/coditect/core/ → (removed)                ││
│  │                                                                      ││
│  │  Services:                                                           ││
│  │    ai.coditect.context-watcher.plist → (unloaded, removed)         ││
│  │                                                                      ││
│  │  Settings:                                                           ││
│  │    ~/.claude/settings.json → (CODITECT entries cleaned)            ││
│  └─────────────────────────────────────────────────────────────────────┘│
│                                                                          │
└─────────────────────────────────────────────────────────────────────────┘

User Data Preservation​

By default, all user data is deleted. The --keep-data flag preserves:

DirectoryContentsSize
context-storage/context.db, exports, checkpoints5-50 MB
session-logs/Machine-specific session exports1-20 MB
logs/Application logs1-5 MB
# Complete removal (data deleted)
/uninstall

# Preserve user data
/uninstall --keep-data

Uninstall Safety​

Key Safety Features:

  1. Confirmation required - Interactive prompt unless --yes passed
  2. Data warning - Warns about permanent data deletion
  3. Backup offer - Offers to backup user data to Desktop before removal
  4. Dry run mode - --dry-run previews all changes without removing anything
  5. Submodule protection - Won't uninstall from development submodules

Uninstall Command​

Script: ~/.coditect/scripts/uninstall-coditect.py

# Interactive uninstall
/uninstall

# Skip confirmation
/uninstall --yes

# Preserve user data
/uninstall --keep-data

# Preview without removing
/uninstall --dry-run

Claude Code Settings Cleanup​

The uninstall process cleans CODITECT entries from ~/.claude/settings.json:

// Before uninstall
{
  "statusLine": {"command": "/Users/you/.claude/statusline-command.sh"},
  "hooks": ["~/.coditect/hooks/session-retrospective.py"]
}

// After uninstall
{
  // statusLine removed (references CODITECT)
  // hooks array cleaned of CODITECT entries
}

Reinstallation​

After uninstalling, users can reinstall:

# Quick install
curl -fsSL https://coditect.ai/install | python3

# Or manual install
cd ~/PROJECTS
git clone https://github.com/coditect-ai/coditect-core.git
python3 coditect-core/scripts/CODITECT-CORE-INITIAL-SETUP.py

References​