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)

$3

- ✅ 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

$3

- ✅ 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

$3

- 🛡️ 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

$3

- 🛡️ 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

$3

``bash


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
`

$3

`bash


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

$3

`bash
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
`

$3

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

$3

`bash
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

$3

Prevents context loss before it happens:
`bash
npm run automation:guard
`
- Monitors token usage in real-time
- Triggers preservation before limits
- Maintains conversation continuity

$3

Predicts when compaction will occur:
- Analyzes conversation patterns
- Calculates risk scores
- Proactive preservation triggers

$3

Continuous background protection:
- Auto-saves every 30 minutes
- Incremental state updates
- Zero performance impact

$3

Comprehensive project restoration:
`bash
recover

Attempts to restore project state

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

🔒 Enterprise Security (v3.0.0)

$3

- 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: ;, &&, ||, |, \`, $, >, <, &

$3

`bash

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
`

$3

- ✅ 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

$3

- 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

$3

`bash

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
`

$3

`bash

If you lose context during development

recover

Or use NPM script

npm run automation:recover

Verify recovery

npm run automation:analyze
`

$3

`bash

Start anti-truncation guard

npm run automation:guard

Run daily maintenance

npm run automation:daily

Check project health

npm run automation:analyze
`

🏗️ Architecture

$3

- 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

$3

`
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:

`json
{
"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

`bash


Test installation

npm test

Verify integrity

npm run verify

Test recovery system

code-automation recover --verify
`

📈 Benefits

$3

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

$3

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

🔄 Upgrading

`bash


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

$3

Installation fails (Fixed in v3.0.6):
`bash


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:
`bash


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:
`bash


Verify backup exists

ls docs/state/

Force recovery

recover --force

Check integrity

npm run verify
`

Context still lost:
`bash


Enable verbose logging

npm run automation:preserve -- --verbose

Check risk analysis

npm run automation:analyze
`

📚 Advanced Usage

$3

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

$3

`yaml

.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