🛡️ Protect your local configs from AI coding assistants' well-meaning modifications
AI-Proof File Guard (ailock) is a developer-friendly CLI tool that prevents AI coding assistants (Cursor, GitHub Copilot, Claude, etc.) from accidentally modifying your local configuration files. It provides "AI can read but not write" protection for files like .env, docker-compose.yml, settings.json, and other configs you don't want AI to touch. Keep all the benefits of AI assistance while protecting your local development environment.
# Install globally via npm
npm install -g ailock
# Or run directly with npx (no installation needed)
npx ailock lock .env
# One command to protect your entire project
ailock init
✅ Complete setup! Detected Node.js project, created config, installed hooks, protected 3 files
✅ Claude Code hooks installed automatically (if detected)
# That's it! Your project is now AI-proof
# AI can still read sensitive files for context, but cannot modify them
# Level 1: Complete project setup (recommended)
ailock init # 🆕 Smart setup: config + hooks + protection
# Level 2: Manual file protection
ailock lock .env secrets.json # Lock specific files
ailock lock # Lock all configured files (includes .gitignore)
# Level 3: Advanced usage
ailock lock --no-gitignore # Exclude .gitignore integration
ailock status # Smart status (detailed in terminal, simple in CI)
ailock unlock .env # Unlock for editing
# Protect environment files during AI coding
ailock lock .env .env.local
# Protect API keys and secrets
ailock lock config/api-keys.json secrets/
# Protect production configurations
ailock lock docker-compose.prod.yml k8s/
# Protect SSH keys and certificates
ailock lock ~/.ssh/id_rsa *.pem
# Unlock when you need to edit, then re-lock
ailock unlock .env
# ... make your changes ...
ailock lock .env
# 🆕 One-Command Project Setup
ailock init # Complete security setup for your project
# 🆕 Smart .gitignore Integration (now default!)
ailock lock # Automatically includes .gitignore sensitive files
ailock lock --verbose # See exactly what's being protected
AI coding assistants (GitHub Copilot, Claude Code, Cursor Agent) with "apply changes" modes can accidentally modify sensitive files during automated refactoring or code generation, potentially causing:
But here's the critical insight: The most dangerous files are often not in version control (listed in .gitignore). Once these files are corrupted by AI tools, you can't restore them from git - they're simply lost forever.
ailock v1.1 introduces smart .gitignore integration based on a simple but powerful observation:
Files in
.gitignoreare intentionally excluded from version control, making them unrecoverable if accidentally modified.
Our design philosophy prioritizes developer experience without sacrificing security:
ailock lock --include-gitignored works immediately without setup.gitignore (.env, *.key, etc.)This approach respects the intelligence of .gitignore as a security boundary while providing the safety net that AI-assisted development demands.
ailock provides multi-layer protection:
Key benefit: AI tools can still read and analyze protected files for context, but cannot modify them.
Create a .ailock file in your project root using gitignore-style syntax:
# Environment files
.env
.env.*
!.env.example
# Configuration files
config/*.json
config/*.yaml
config/*.yml
# Security files
**/*.key
**/*.pem
**/*.p12
**/*.crt
**/secrets.json
**/credentials.json
# Deployment scripts
scripts/deploy/**
docker-compose.production.yml
Dockerfile.prod
# Service definitions
services/**/*.yaml
k8s/**/*.yaml
If no .ailock file exists, these patterns are protected by default:
.env.env.***/*.key**/*.pem**/secrets.jsonailock init🚀 Complete project security setup - one command to protect everything.
ailock init # 🆕 Smart setup: detect project + config + hooks + protection
ailock init --interactive # Use detailed wizard for custom setup
ailock init --config-only # Only create .ailock configuration file
ailock init --force # Overwrite existing configuration and hooks
🆕 v1.2: The new ailock init automatically detects your project type (Node.js, Docker, Python), creates appropriate configuration, installs Git hooks, and protects sensitive files - all in one command!
ailock lockLock files to prevent modifications.
ailock lock # 🆕 Lock files (includes .gitignore by default)
ailock lock .env secrets/* # Lock specific files/patterns
ailock lock --verbose # Show detailed output
ailock lock --dry-run # Preview changes without applying
ailock lock --no-gitignore # 🆕 Exclude .gitignore sensitive files
🆕 v1.2 Simplification: .gitignore integration is now enabled by default for the safest protection. Use --no-gitignore to disable if needed.
ailock unlockUnlock files to allow modifications.
ailock unlock # 🆕 Unlock files (includes .gitignore by default)
ailock unlock .env # Unlock specific files
ailock unlock --verbose # Show detailed output
ailock unlock --dry-run # Preview changes without applying
ailock unlock --no-gitignore # 🆕 Exclude .gitignore sensitive files
ailock statusShow current protection status with smart output detection.
ailock status # 🆕 Smart output (detailed in terminal, simple in CI)
ailock status --verbose # Force detailed information
ailock status --simple # 🆕 Force simple output for scripts
ailock status --json # JSON output for automation
🆕 v1.2 Intelligence: Automatically detects if you're in an interactive terminal and shows appropriate detail level.
ailock status-interactive (alias: dash)Launch interactive real-time status dashboard.
ailock dash # Interactive dashboard
ailock dash --verbose # Detailed dashboard view
ailock list (alias: ls)List all protected files and their status.
ailock list # Show all protected files
ailock list --long # Detailed file information
ailock list --locked-only # Show only locked files
ailock list --json # JSON output
ailock install-hooksInstall Git pre-commit hooks for protection.
ailock install-hooks # Interactive installation
ailock install-hooks --yes # Skip prompts
ailock install-hooks --force # Overwrite existing hooks
ailock generate (alias: gen)Generate integration templates for CI/CD and development environments.
ailock generate # Interactive template selection
ailock generate --list # List all available templates
ailock generate --template github-actions # Generate specific template
ailock generate --category ci-cd # Generate all CI/CD templates
ailock generate --dry-run # Preview without creating files
Available Templates:
github-actions - GitHub Actions workflow for protection validationgitlab-ci - GitLab CI/CD pipeline integrationdocker-production - Production Dockerfile with ailock integrationdevcontainer - VS Code Dev Container with ailock setupailock completionGenerate shell completion scripts for enhanced CLI experience.
ailock completion bash # Generate bash completion script
ailock completion zsh # Generate zsh completion script
ailock completion fish # Generate fish completion script
ailock completion powershell # Generate PowerShell completion script
ailock completion bash --install-instructions # Show installation instructions
ailock setup-completionInteractive setup for shell completions.
ailock setup-completion # Auto-detect shell and show setup instructions
Shell Completion Features:
ailock lock <TAB> suggests unlocked filesailock unlock <TAB> suggests locked filesailock generate <TAB> suggests available templatesInstallation Examples:
Bash:
# Add to ~/.bashrc
source <(ailock completion bash)
Zsh:
# Add to ~/.zshrc
source <(ailock completion zsh)
Fish:
# Save to completions directory
ailock completion fish > ~/.config/fish/completions/ailock.fish
PowerShell:
# Add to $PROFILE
ailock completion powershell | Out-String | Invoke-Expression
ailock works consistently across all major platforms:
| Platform | Lock Method | Immutable Support |
|---|---|---|
| Linux | chmod + chattr +i | ✅ Full support |
| macOS | chmod + chflags | ✅ Partial support |
| Windows | attrib +R + icacls | ⚠️ ACL-based |
| WSL | Hybrid detection | ⚠️ Filesystem-dependent |
Linux: Uses chattr +i for immutable files when supported by filesystem (ext2/3/4, XFS, etc.)
Windows: Falls back to icacls for advanced permission scenarios. Some operations may require administrator privileges.
WSL: Automatically detects underlying filesystem and uses appropriate locking mechanism.
# 1. Initial setup
ailock lock # Lock sensitive files
# 2. Development work
# AI tools can read locked files for context
# but cannot modify them accidentally
# 3. When you need to edit protected files
ailock unlock .env # Unlock specific file
echo "NEW_VAR=value" >> .env # Make changes
ailock lock .env # Lock again
# 4. Or unlock all, edit, then lock all
ailock unlock
# ... make changes ...
ailock lock
AILock now includes automatic Claude Code integration that prevents accidental AI modifications of protected files.
# Claude Code hooks are automatically installed during init!
ailock init
# That's it! Claude Code protection is now active
Manual installation (if needed):
# Run the interactive installer
./node_modules/ailock/hooks/install.sh
The integration uses Claude Code's PreToolUse hooks to:
ailock statusWhen Claude Code tries to modify a protected file, you'll see:
🔒 File is protected by ailock. Run 'ailock unlock config.json' to allow modifications.
# Clone and install
git clone https://github.com/your-org/ailock.git
cd ailock
npm install
# Build
npm run build
# Test
npm test
# Run locally
npm run dev lock --help
# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Run specific test file
npx vitest tests/unit/config.test.ts
ailock/
├── src/
│ ├── commands/ # CLI command implementations
│ ├── core/ # Core functionality
│ │ ├── config.ts # Configuration loading
│ │ └── platform.ts # Cross-platform file operations
│ ├── utils/ # Utility functions
│ └── index.ts # CLI entry point
├── tests/
│ ├── unit/ # Unit tests
│ └── integration/ # Integration tests
├── .ailock # Example configuration
└── README.md
All planned features have been successfully implemented and tested:
ailock init does everything automatically.gitignore integration now enabled by default.gitignoreailock v1.2.0 is now production-ready with ultimate simplification, one-command setup, smart project detection, enhanced .gitignore integration, enterprise-grade features, comprehensive testing, and battle-tested security mechanisms.
Contributions are welcome! Please read our Contributing Guide for details.
MIT License - see LICENSE file for details.
Made with ❤️ for developers who want to safely use AI coding assistants
FAQs
AI-Proof File Guard - Protect sensitive files from accidental AI modifications
The npm package ailock receives a total of 3 weekly downloads. As such, ailock popularity was classified as not popular.
We found that ailock demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Multiple high-impact npm maintainers confirm they have been targeted in the same social engineering campaign that compromised Axios.
Security News
Axios compromise traced to social engineering, showing how attacks on maintainers can bypass controls and expose the broader software supply chain.
Security News
Node.js has paused its bug bounty program after funding ended, removing payouts for vulnerability reports but keeping its security process unchanged.