AI Code Guardian 🛡️

A Claude plugin that watches your back while you code. It catches security vulnerabilities, code quality issues, and potential bugs in real-time - before they become problems.

Why Guardian?

We've all been there - writing code quickly with AI assistance, only to realize later there's a SQL injection vulnerability or a hardcoded API key. Guardian acts as your safety net, analyzing code as you write it and providing immediate feedback right in Claude.

Features

• Real-time Protection - Analyzes code as you write, not after
• Security First - Catches OWASP Top 10 vulnerabilities
• Quality Insights - Identifies complexity, duplication, and code smells
• Non-intrusive - Gentle suggestions that don't interrupt your flow
• Fast - Sub-2ms analysis won't slow you down
• Multi-language - Supports JavaScript, TypeScript, and Python

Installation

Quick Install (NPM)

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

# Run directly as CLI
ccg analyze myfile.js

# Or use full name
claude-code-guardian analyze myfile.js

As a Claude Plugin (Recommended)

Option 1: Via NPM

# Install the package
npm install -g claude-code-guardian

# Find where NPM installed it
npm list -g claude-code-guardian --depth=0

# Load in Claude (Mac/Linux)
claude --plugin-dir $(npm root -g)/claude-code-guardian

# Load in Claude (Windows)
claude --plugin-dir %APPDATA%\npm\node_modules\claude-code-guardian

Option 2: Via GitHub

# Clone the repository
git clone https://github.com/vivekspatil/ai-code-guardian.git
cd ai-code-guardian

# Install and build
npm install
npm run build

# Load in Claude
claude --plugin-dir .

Quick Start

Once installed, just start coding! Guardian works automatically. But here are the basics:

/guardian                    # Check status
/guardian-watch on           # Enable real-time monitoring
/guardian-analyze file.js    # Analyze specific file
/guardian-report             # See session summary

That's it! Guardian will now watch your code and alert you to issues.

What It Catches

Security Issues

• SQL injection vulnerabilities
• Cross-site scripting (XSS) risks
• Hardcoded passwords and API keys
• Command injection risks
• Path traversal attempts

Code Quality

• Functions that are too complex
• Deeply nested code
• Code duplication
• Poor naming conventions
• Missing error handling

Example Feedback

🔴 CRITICAL: SQL Injection Vulnerability
   Line 23: db.query("SELECT * FROM users WHERE id = " + userId)

   Consider using parameterized queries:
   db.query("SELECT * FROM users WHERE id = ?", [userId])

Configuration

Guardian works out of the box, but you can customize it:

/guardian-config set watchMode summary    # Less verbose
/guardian-config disable todo-comments    # Allow TODOs

Settings persist in .guardian-config.json in your project.

Manual Testing Guide

Before each release, we manually verify:

Core Functionality Tests

1. Plugin Loading

   claude --plugin-dir .
   /guardian
   # ✓ Should display version and status

2. Code Analysis

   /guardian-analyze tests/fixtures/vulnerable.js
   # ✓ Should find SQL injection, XSS, hardcoded secrets
   # ✓ Should complete in <50ms

3. Real-time Monitoring

   /guardian-watch on
   # Write code with issues
   # ✓ Should show warnings immediately
   # ✓ Should not interrupt workflow

4. Session Tracking

   /guardian-report
   # ✓ Should show all issues found
   # ✓ Should display session statistics
   # ✓ Should calculate quality score

5. Configuration

   /guardian-config show
   /guardian-config set watchMode detailed
   # ✓ Should persist settings
   # ✓ Should apply immediately

Edge Cases Tested

• Large files (1000+ lines)
• Rapid consecutive edits
• Multiple file types in one session
• Invalid syntax in code
• Concurrent operations
• Session recovery after restart

Performance Benchmarks

• Analysis: <2ms average (target: <50ms) ✅
• Plugin overhead: <10ms ✅
• Memory usage: <10MB ✅
• All 124 core tests passing ✅

Development

Project Structure

ai-code-guardian/
├── src/
│   ├── analyzer/      # Core analysis engine
│   ├── plugin/        # Claude plugin integration
│   ├── parser/        # AST parsing with tree-sitter
│   └── rules/         # Security and quality rules
├── skills/            # Claude skill definitions
├── hooks/             # Real-time interception
└── tests/            # Test suite (124 tests)

Testing

npm test              # Run test suite
npm run test:watch    # Watch mode
npm run build        # Build for production

Contributing

We'd love your help! Check out CONTRIBUTING.md for guidelines.

About TODO Detection

You might notice Guardian flags TODO comments. This is intentional - it encourages completing tasks rather than accumulating technical debt. You can disable this:

/guardian-config disable todo-comments

Performance

Guardian is designed to be invisible:

• 1.46ms average analysis time
• <10MB memory footprint
• Zero external dependencies in runtime
• Async non-blocking architecture

Roadmap

• [ ] Support for more languages (Go, Rust, Java)
• [ ] AI-powered fix suggestions
• [ ] Team sharing and rule sets
• [ ] IDE extensions
• [ ] Custom rule creation

License

MIT - See LICENSE for details.

Support

• 📖 Usage Guide
• 🐛 Report Issues
• 💬 Discussions

Acknowledgments

Built with ❤️ for the Claude community.

Remember: Guardian is your coding companion, not a replacement for security reviews. Always conduct thorough testing and security audits for production code.

Happy coding with confidence! 🚀