keep-codex-fast-maintenance

Skill by ara.so — Codex Skills collection.

A backup-first maintenance skill for keeping local Codex state fast, clean, and recoverable. When Codex starts feeling heavy after weeks of chats, terminals, logs, worktrees, and project history, this gives you a calm way to inspect what's going on and reduce local drag without losing context.

Core Principle

Make handoffs first. Archive, don't delete. Apply changes only when you are ready.

All operations are read-only by default. Nothing is mutated until you explicitly use --apply.

Installation

Clone or copy this repository into your Codex skills directory:

cd ~/.codex/skills  # or your Codex skills path
git clone https://github.com/vibeforge1111/keep-codex-fast.git

Or ask Codex directly:

Install the keep-codex-fast skill from https://github.com/vibeforge1111/keep-codex-fast

Three Modes

1. Inspect (default): Report-only, no writes, privacy-safe
2. Maintain: Backs up, archives old sessions, moves stale worktrees, rotates logs, prunes dead config
3. Repair (optional): Only with --repair-thread-metadata-bloat flag; trims oversized SQLite title/preview metadata after backup

Key Commands

Inspect Mode (Read-Only)

Basic inspection report:

python scripts/keep_codex_fast.py

Detailed inspection with thread IDs, titles, and paths:

python scripts/keep_codex_fast.py --details

Backup Mode

Create backups only without changing local state:

python scripts/keep_codex_fast.py --backup-only

Important: Backup folders contain private local Codex metadata. Keep them on your machine and do not share publicly.

Maintenance Mode

Apply core maintenance (archives sessions, moves worktrees, rotates logs):

python scripts/keep_codex_fast.py --apply

Customize retention periods:

python scripts/keep_codex_fast.py --apply \
  --archive-older-than-days 10 \
  --worktree-older-than-days 7

Wait for Codex to exit before applying:

python scripts/keep_codex_fast.py --apply --wait-for-codex-exit

Repair Thread Metadata Bloat (Advanced)

Only use when the report shows unusually large title/preview metadata:

python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat

This trims oversized SQLite title/preview fields that can slow chat navigation. The actual conversation transcript remains intact.

Handoffs First: Create Continuity Documents

Before archiving any important active chats, create handoff documents. These let you archive heavy chat history and start fresh threads without losing context.

Paste this into each active repo chat you want to preserve:

Create a comprehensive handoff document for this repo/session before I archive Codex history.

Include:
- repo/path and branch
- current goal
- what we already completed
- files touched or investigated
- commands/tests already run
- known errors, warnings, or failing checks
- open decisions
- constraints, user preferences, and do-not-touch areas
- the next 3-7 concrete steps

Also include a reactivation prompt I can paste into a fresh Codex chat so it can continue from this handoff without relying on the old chat context.

Save the handoff in a sensible repo-local place like docs/codex-handoffs/YYYY-MM-DD-topic.md unless this repo already has a better handoff location.

Common Usage Patterns

Pattern 1: Safe Inspection and Maintenance

Use $keep-codex-fast to inspect my Codex local state and recommend a safe maintenance plan.

After reviewing the report:

Use $keep-codex-fast to apply safe Codex maintenance.

Before changing anything, confirm that important active repo chats have handoff docs or do not need them.

Then back up first, archive instead of deleting, move stale worktrees, rotate large logs, prune dead config references, and verify the result.

If Codex is currently running, do not mutate local state. Tell me to close Codex first.

Pattern 2: Weekly Maintenance Reminder

Use $keep-codex-fast to create a recurring Codex maintenance reminder.

Schedule it weekly if I use Codex heavily, or biweekly if that seems safer.

The reminder should:
- run the keep-codex-fast report first
- never pass --apply or run mutating maintenance automatically
- never archive, move, prune, rotate, normalize, delete, or mutate local Codex state
- remind me to create comprehensive handoff docs and reactivation prompts for active repo chats before any manual apply
- summarize active session size, archived session size, extended path candidates, old session candidates, worktree candidates, log size, and top Node/dev processes
- report heavy Node/dev processes without killing them
- tell me that manual apply should only happen after I confirm handoffs exist or are not needed and Codex is closed

Pattern 3: Backup Before Major Changes

# Create backup snapshot before applying any changes
python scripts/keep_codex_fast.py --backup-only

# Review what will change
python scripts/keep_codex_fast.py --details

# Apply changes with custom retention
python scripts/keep_codex_fast.py --apply \
  --archive-older-than-days 14 \
  --worktree-older-than-days 10

What Gets Maintained

Active Sessions

• Default retention: 7 days
• Non-pinned sessions older than threshold are archived
• Pinned sessions are never archived
• Archives stored in timestamped backup folders

Worktrees

• Default retention: 7 days
• Stale worktrees moved to archive location
• Active worktrees preserved
• Worktree references updated in config

Logs

• Large logs_2.sqlite* files rotated
• Old logs compressed and archived
• Current logs preserved at manageable size

Config

• Dead/temporary project entries pruned
• Windows extended paths (\\?\C:\...) normalized
• Invalid references cleaned up

Thread Metadata (Optional)

• Only with --repair-thread-metadata-bloat
• Trims oversized title/preview fields in state_5.sqlite
• Conversation transcripts remain intact
• Repair manifest created for restore capability

Configuration

The script uses sensible defaults. Override via command-line flags:

# Default thresholds
ARCHIVE_OLDER_THAN_DAYS = 7
WORKTREE_OLDER_THAN_DAYS = 7
LOG_SIZE_THRESHOLD_MB = 100

# Override example
python scripts/keep_codex_fast.py --apply \
  --archive-older-than-days 14 \
  --worktree-older-than-days 10

Real Code Example: Custom Maintenance Script

#!/usr/bin/env python3
"""
Custom Codex maintenance wrapper
"""
import subprocess
import sys
from pathlib import Path
from datetime import datetime

def run_maintenance(dry_run=True):
    """Run Codex maintenance with custom settings"""
    
    # Create timestamped log
    log_dir = Path.home() / ".codex" / "maintenance-logs"
    log_dir.mkdir(exist_ok=True)
    log_file = log_dir / f"maintenance-{datetime.now():%Y%m%d-%H%M%S}.log"
    
    # Build command
    cmd = [
        sys.executable,
        "scripts/keep_codex_fast.py",
    ]
    
    if not dry_run:
        cmd.append("--apply")
        cmd.extend([
            "--archive-older-than-days", "14",
            "--worktree-older-than-days", "10",
        ])
    else:
        cmd.append("--details")
    
    # Run with logging
    print(f"Running maintenance (dry_run={dry_run})...")
    print(f"Logging to: {log_file}")
    
    with open(log_file, "w") as f:
        result = subprocess.run(
            cmd,
            stdout=subprocess.PIPE,
            stderr=subprocess.STDOUT,
            text=True
        )
        f.write(result.stdout)
        print(result.stdout)
    
    return result.returncode == 0

if __name__ == "__main__":
    # First inspect
    print("=== INSPECTION PHASE ===")
    if not run_maintenance(dry_run=True):
        sys.exit(1)
    
    # Confirm before applying
    response = input("\nApply maintenance changes? (yes/no): ")
    if response.lower() == "yes":
        print("\n=== MAINTENANCE PHASE ===")
        run_maintenance(dry_run=False)
    else:
        print("Maintenance cancelled.")

Troubleshooting

"Codex is currently running"

Close Codex before applying changes:

# Wait for Codex to exit automatically
python scripts/keep_codex_fast.py --apply --wait-for-codex-exit

# Or manually close Codex first

Backup folders growing large

Backups contain full session data and metadata. Clean old backups manually:

# List backups
ls -lh ~/.codex/backups/  # or wherever backups are stored

# Remove old backups (review first!)
find ~/.codex/backups -type d -mtime +30 -exec rm -rf {} +

Thread metadata repair needed

When the report shows large title/preview metadata:

Warning: Found threads with title/preview metadata > 10KB
Consider using --repair-thread-metadata-bloat

Apply the repair:

python scripts/keep_codex_fast.py --apply --repair-thread-metadata-bloat

Keep the repair manifest private. It contains the original full title/preview text.

Restore from backup

If you need to restore state after applying changes:

1. Locate the backup folder (timestamped in output)
2. Follow instructions in restore-instructions.txt within backup
3. For thread metadata repairs, use restore-thread-metadata.py

Process reporting without killing

The script reports heavy Node/dev processes but never kills them:

# Just inspect processes
python scripts/keep_codex_fast.py --details

You decide whether to stop processes manually.

Mental Model

• Chats are for execution
• Handoff docs are for memory
• Archives are for history
• Fresh threads are for speed

Safety Guarantees

1. Read-only by default: No writes without --apply
2. Backup first: All changes create timestamped backups
3. Archive, don't delete: Sessions and worktrees moved, not removed
4. Restore artifacts: Every change includes restore instructions
5. Handoff prompts: Preserve context before archiving
6. Process detection: Warns when Codex is running, never force-kills

Advanced: Direct Script Integration

from pathlib import Path
import sys

# Add keep-codex-fast to path
skill_path = Path(__file__).parent / "keep-codex-fast"
sys.path.insert(0, str(skill_path / "scripts"))

from keep_codex_fast import (
    inspect_codex_state,
    create_backup,
    apply_maintenance,
)

# Use as library
state = inspect_codex_state()
print(f"Active sessions: {state['active_session_count']}")
print(f"Total size: {state['total_size_mb']:.1f}MB")

# Create backup before custom operation
backup_path = create_backup()
print(f"Backup created: {backup_path}")

When to Use This Skill

• Codex feels slower after weeks of heavy use
• Many long chat threads accumulated
• Working across multiple repos and worktrees
• Frequent terminal/dev server usage
• Want safe, reversible maintenance
• Need to reduce local state without losing context