/backup - Backup Context and Claude Config

Backup context database, unified messages, and Claude global config files to GCS.

System Prompt

EXECUTION DIRECTIVE: When the user invokes /backup, execute the backup script immediately:

cd ~/.coditect && ./scripts/backup-context-db.sh [OPTIONS]

---

Usage

/backup                    # Run full backup to GCS
/backup --dry-run          # Preview what would be uploaded
/backup --status           # Show backup status and recent backups
/backup --restore latest   # Restore from latest backup
/backup --restore 2026-01-15  # Restore from specific date
/backup --project PILOT    # Backup scoped to PILOT project (ADR-159)
/backup --tenant avivatec  # Backup scoped to avivatec tenant (ADR-159)

What Gets Backed Up

Context Storage Files

File	Description
org.db	SQLite org database (Tier 2: decisions, skill_learnings, error_solutions)
sessions.db	SQLite sessions database (Tier 3: messages, tool_analytics, token_economics)
context.db	Legacy SQLite database (deprecated, kept for backward compatibility)
unified_messages.jsonl	Unified session messages
unified_hashes.json	Content hashes for deduplication
unified_stats.json	Processing statistics

Claude Global Config Files (~/.claude/)

File	Description
settings.json	Claude Code settings
settings.local.json	Local/machine-specific settings
statusline-config.json	Statusline configuration

Backup Location

# Global (default)
gs://{PROJECT_ID}-context-backups/coditect-core/daily/YYYY-MM-DD/HH-MM-SS/

# Project-scoped (--project PILOT)
gs://{PROJECT_ID}-context-backups/coditect-core/projects/PILOT/daily/YYYY-MM-DD/HH-MM-SS/

# Tenant-scoped (--tenant avivatec)
gs://{PROJECT_ID}-context-backups/coditect-core/tenants/avivatec/daily/YYYY-MM-DD/HH-MM-SS/

Each backup contains:

├── org.db.gz
├── sessions.db.gz
├── context.db.gz (legacy)
├── unified_messages.jsonl.gz
├── unified_hashes.json.gz
├── unified_stats.json.gz
└── claude-config/
    ├── settings.json.gz
    ├── settings.local.json.gz
    └── statusline-config.json.gz

Multi-Tenant Scope (ADR-159)

Flag	Effect	GCS Path
(none)	Global backup	.../coditect-core/daily/...
--project PILOT	Project-scoped	.../projects/PILOT/daily/...
--tenant avivatec	Tenant-scoped	.../tenants/avivatec/daily/...

Environment variables CODITECT_PROJECT and CODITECT_TENANT can be used instead of flags.

Features

• SQLite Snapshot - Safe backup even during active database use
• Gzip Compression - ~75% size reduction, faster uploads
• Parallel-Safe - No file locking issues
• Claude Config - Preserves your Claude Code settings

Prerequisites

• gcloud CLI installed and authenticated
• gsutil available
• sqlite3 for database snapshots

First-Time Setup

./scripts/backup-context-db.sh --setup  # Creates GCS bucket

Examples

# Preview backup
/backup --dry-run

# Run backup
/backup

# Check status
/backup --status

# Restore latest
/backup --restore latest

# Project-scoped backup (ADR-159)
/backup --project PILOT

# Tenant-scoped backup (ADR-159)
/backup --tenant avivatec

# Full sync (backup + pull + merge)
./scripts/backup-context-db.sh --sync

Related Commands

Command	Purpose
/cx	Extract and process context
/cxq	Query context database
/export	Export session to text

---

Script: backup-context-db.sh ADR: Context backup architecture, ADR-159 (Multi-Tenant Command Architecture) Version: 1.1.0