Code Automation 🚀

Universal anti-compaction system with perfect recovery capabilities for Claude Code projects

⚠️ Note: This package is specifically designed for Claude Code AI assistant sessions and will not work with other AI tools (ChatGPT, Copilot, Cursor, etc.).

🌟 Latest Features (v3.0.6)

🐛 FIXED: Critical Installation Bug (v3.0.6)

• ✅ Complete File Installation - Fixed missing anti-truncation-guard.js file during installation
• 🛠️ All NPM Scripts Work - Users can now run all automation commands without module errors
• 🎯 Immediate Fix - Resolves "Cannot find module" error for automation:guard command

🐛 FIXED: Installation Issues (v3.0.2)

• ✅ Reliable Installation - Fixed critical bug where automation files weren't copied
• 🔍 Enhanced Error Reporting - Clear feedback when installation fails
• 📊 Detailed Logging - See exactly what's happening during installation
• ⚡ Fail-Fast Behavior - Installation stops immediately with helpful error messages

🔒 Enterprise Security (v3.0.0)

• 🛡️ SecureProcessManager - Enterprise-grade process security system
• ⚔️ Command Injection Prevention - Blocks dangerous shell patterns (;, &&, ||, |, etc.)
• 📊 Resource Limits - Process count (5 max), memory (512MB), timeout (2min) enforcement
• 🔐 Process Isolation - Secure project-level process management
• 🎯 Command Whitelisting - Only allow safe npm, git, node operations
• 📱 Verbose Mode - --verbose flag for detailed operation feedback

🧠 Core Features

• 🛡️ Anti-Truncation Guard - Prevents context truncation in real-time
• 🔍 Compaction Risk Analyzer - Predicts and prevents compaction events
• ⚡ Live Preservation Engine - Continuous context monitoring
• 🎯 Advanced Recovery System - Comprehensive project reconstruction
• 📊 Development Session Tracker - Maintains session continuity
• 🧠 Enhanced Context Analysis - Deep project understanding

🎯 The Problem This Solves

Context Loss is the #1 problem when working with Claude Code:

• ❌ Long sessions lose context due to token limits
• ❌ Complex projects get "compacted" and lose detail
• ❌ Recovery is manual and error-prone
• ❌ Progress gets lost between sessions

✅ The Solution

Code Automation provides:

• ✅ Fixed critical installation bug - All automation files now install correctly (v3.0.6)
• ✅ Fixed installation issues - Reliable file copying and clear error messages (v3.0.2)
• ✅ Enterprise-grade security - Process isolation, command validation, resource limits
• ✅ Automatic context preservation every 30 minutes
• ✅ Advanced project recovery from any state
• ✅ Real-time compaction protection
• ✅ Professional user experience with verbose feedback
• ✅ Zero-configuration setup
• ✅ Reliable automation

🚀 Quick Start

Installation

# Global installation (recommended)
npm install -g claude-code-automation

# ⚠️ IMPORTANT: NPM doesn't show post-install messages for global packages
# Run this command immediately after install:
welcome

# Or get detailed help
code-automation help

# Or local installation
npm install claude-code-automation --save-dev

Setup Your Project

# Navigate to your project
cd your-project

# Install automation system
claude-code-automation install

# Start protection immediately (with verbose feedback)
code-automation --verbose preserve

# Or use npm scripts
npm run automation:preserve

📋 Available Commands

CLI Commands (Global)

claude-code-automation install              # Setup in current project
code-automation --verbose preserve  # Preserve current context (with detailed feedback)
code-automation --verbose recover   # Recover from backup (with detailed feedback)
code-automation --verbose analyze   # Analyze project state (with detailed feedback)
preserve                            # Quick preserve (silent)
recover                             # Quick recover (silent)
analyze                             # Quick analyze (silent)
inject                              # Inject into existing project

🔒 Security Options

code-automation --verbose [command]  # Enable detailed security feedback
code-automation --quiet [command]    # Suppress non-essential output

NPM Scripts (Project)

npm run automation:preserve  # Preserve current state
npm run automation:recover   # Recover from latest backup
npm run automation:analyze   # Analyze project health
npm run automation:daily     # Run full automation cycle
npm run automation:guard     # Start anti-truncation guard

🔧 Core Features

🛡️ Anti-Truncation Guard

Prevents context loss before it happens:

npm run automation:guard

• Monitors token usage in real-time
• Triggers preservation before limits
• Maintains conversation continuity

🔍 Compaction Risk Analyzer

Predicts when compaction will occur:

• Analyzes conversation patterns
• Calculates risk scores
• Proactive preservation triggers

⚡ Live Preservation Engine

Continuous background protection:

• Auto-saves every 30 minutes
• Incremental state updates
• Zero performance impact

🎯 Advanced Recovery System

Comprehensive project restoration:

recover
# Attempts to restore project state

• Reconstructs complete project state
• Restores all decisions and context
• Maintains development history

🔒 Enterprise Security (v3.0.0)

🛡️ SecureProcessManager

• Process Isolation: Each project runs in isolated context
• Resource Limits: Max 5 processes, 512MB memory, 2-minute timeouts
• Command Whitelisting: Only npm, yarn, pnpm, node, git allowed
• Input Sanitization: Blocks dangerous patterns: ;, &&, ||, |, \``, $, >, <, &`

⚔️ Security Features

# Secure command execution with validation
code-automation --verbose preserve  # Shows security decisions

# Process resource monitoring
code-automation analyze             # Displays security status

# Safe automation without global process hijacking
npm run automation:daily           # Uses secure process management

🔐 What's Protected

• ✅ Command Injection Prevention - All user input validated
• ✅ Process Resource Limits - Prevents system overload
• ✅ Path Traversal Protection - Secure file operations only
• ✅ Process Cleanup - Automatic resource cleanup on exit
• ✅ Timeout Enforcement - No runaway processes

🚨 Breaking Changes in v3.0.0

• All process execution now goes through SecureProcessManager
• Stricter command validation may block some edge cases
• Process limits enforced (upgrade from unlimited processes)
• More restrictive input validation for enhanced security

📊 Usage Examples

Basic Project Setup

# Install globally
npm install -g claude-code-automation

# Setup new project
mkdir my-claude-project
cd my-claude-project
claude-code-automation install

# Start development with protection
npm run automation:preserve

Recovering Lost Context

# If you lose context during development
recover

# Or use NPM script
npm run automation:recover

# Verify recovery
npm run automation:analyze

Continuous Protection

# Start anti-truncation guard
npm run automation:guard

# Run daily maintenance
npm run automation:daily

# Check project health
npm run automation:analyze

🏗️ Architecture

Core Components

• Context Preservation Engine - State capture and storage
• Auto Recovery System - Intelligent project reconstruction
• Live Preservation Engine - Real-time monitoring
• Anti-Truncation Guard - Proactive protection
• Compaction Risk Analyzer - Predictive analysis
• Development Session Tracker - Session continuity

File Structure

your-project/
├── scripts/automation/           # Automation scripts
├── docs/automation/             # Generated documentation
├── docs/state/                  # Project state snapshots
├── docs/recovery/               # Recovery instructions
└── package.json                 # Updated with scripts

⚙️ Configuration

Configuration is automatic, but can be customized:

{
  "version": "1.0.0",
  "enabled": true,
  "features": {
    "contextPreservation": true,
    "antiTruncation": true,
    "livePreservation": true,
    "perfectRecovery": true,
    "riskAnalysis": true,
    "sessionTracking": true
  },
  "settings": {
    "preservationInterval": 1800000,
    "maxBackups": 50,
    "compressionEnabled": true,
    "verboseLogging": false
  }
}

🧪 Testing

# Test installation
npm test

# Verify integrity
npm run verify

# Test recovery system
code-automation recover --verify

📈 Benefits

For Developers

• ✅ Never lose progress again
• ✅ Seamless session continuity
• ✅ Instant project recovery
• ✅ Zero maintenance required

For Teams

• ✅ Consistent project state
• ✅ Reliable handoffs
• ✅ Automated documentation
• ✅ Reduced onboarding time

🔄 Upgrading

# Upgrade globally
npm install -g claude-code-automation@latest

# Update existing projects
cd your-project
claude-code-automation install

Latest features are automatically enabled!

🐛 Troubleshooting

Common Issues

Installation fails (Fixed in v3.0.6):

# v3.0.6+ ensures all automation files are copied during installation
# v3.0.2+ provides clear error messages if installation fails
claude-code-automation install

# If you see "Failed to copy automation files":
# 1. Check npm permissions
# 2. Try reinstalling the package
npm uninstall -g claude-code-automation
npm install -g claude-code-automation

# Alternative: Use npx
npx claude-claude-code-automation install

Files not copied to .automation/ directory:

# v3.0.2+ shows detailed logging during installation
# Look for these messages:
# ✅ Copied: context-preservation.js
# ✅ All 4 automation files copied successfully

# If files are missing, check:
ls -la .automation/
# Should contain: context-preservation.js, auto-recovery.js, etc.

Recovery doesn't work:

# Verify backup exists
ls docs/state/

# Force recovery
recover --force

# Check integrity
npm run verify

Context still lost:

# Enable verbose logging
npm run automation:preserve -- --verbose

# Check risk analysis
npm run automation:analyze

📚 Advanced Usage

Custom Preservation Intervals

// In your project
const preservation = require('claude-code-automation');
preservation.setInterval(15 * 60 * 1000); // 15 minutes

Integration with CI/CD

# .github/workflows/preserve.yml
name: Context Preservation
on: [push, pull_request]
jobs:
  preserve:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - run: npm install -g claude-code-automation
      - run: preserve

🤝 Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Submit a pull request

📄 License

MIT License - see LICENSE