SubClaude CLI

AI Code Quality Guardian CLI - An intelligent auditing layer that enforces opinionated best practices and prevents vibe coding anti-patterns across all languages and frameworks in real-time.

🚀 Features

• Real-time Hook Processing: Integrates seamlessly with Claude Code through pre/post tool execution hooks
• 20+ Specialized Behaviours: Security, governance, quality, and content validation modules
• Three-Level Evaluation Architecture: Fast pattern matching → Complex AST analysis → LLM reasoning
• SQLite Database: Complete audit trails with Drizzle ORM for data persistence
• Type-Safe Operations: Full TypeScript support with Zod validation throughout
• Modern CLI Interface: Built with React Ink for rich terminal interactions

📦 Installation

Global Installation

npm install -g @subclaude/cli

Local Installation

npm install @subclaude/cli

Development Installation

git clone https://github.com/subclaude/subclaude.git
cd subclaude/cli
npm install
npm run deploy:global

🎯 Quick Start

# Initialize SubClaude in your project
subclaude init

# Validate current working directory
subclaude validate

# Start Claude Code integration server
subclaude studio

# List all available behaviours
subclaude behaviour list

# Query audit database
subclaude query hooks --limit 10

🔧 Configuration

Create a .subclaude.json file in your project root:

{
  "enabled": true,
  "level": "warn",
  "behaviours": {
    "security": true,
    "governance": true,
    "quality": true,
    "content": false
  },
  "database": {
    "path": "~/.claude/subclaude.md.db"
  }
}

📊 Available Commands

| Command | Description | | --------------------------- | -------------------------------------------- | | subclaude init | Initialize SubClaude configuration | | subclaude validate [path] | Validate code against behaviours | | subclaude studio | Start API server for Claude Code integration | | subclaude ingest | Process hook data from Claude Code | | subclaude behaviour list | List all available validation behaviours | | subclaude query hooks | Query database with filtering options | | subclaude enable/disable | Control SubClaude functionality |

🛡️ Security Behaviours

• Secret Detection: Prevents hardcoded secrets and API keys
• Sensitive File Guard: Blocks access to sensitive system files
• Browser API Restriction: Validates browser extension security patterns
• Dependency Injection: Prevents malicious dependency injection attempts

📋 Governance Behaviours

• Batch Edit Prevention: Stops dangerous bulk file operations
• Import Alias Management: Enforces consistent import conventions
• Task Completion: Validates that development tasks are properly completed
• Repository Integrity: Ensures repository security and compliance

✨ Quality Behaviours

• Library Recommendation: Suggests modern, well-maintained libraries
• Code Style Enforcement: Applies consistent formatting and style rules
• File Heading Injection: Automatically adds file headers with metadata
• Performance Validation: Identifies performance anti-patterns

🔗 Claude Code Integration

SubClaude integrates with Claude Code through hooks for real-time validation:

1. Pre-Tool Hook: Validates tool operations before execution
2. Post-Tool Hook: Audits results and provides feedback
3. Behavior Engine: Applies validation rules and returns decisions
4. Audit Trail: Logs all operations for compliance and debugging

📊 Database & Analytics

SubClaude maintains a comprehensive audit database:

# View recent hook data
subclaude query hooks --recent

# Filter by tool type
subclaude query hooks --tool "Read" --limit 5

# Analyze behaviour results
subclaude query hooks --behaviour "security" --status "blocked"

🛠️ Development

# Development setup
git clone https://github.com/subclaude/subclaude.git
cd subclaude/cli
pnpm install

# Development mode (with tsx runtime)
pnpm dev

# Development with API server
pnpm dev:serve

# Type checking
pnpm check

# Database operations
pnpm db:studio  # Open Drizzle Studio
pnpm db:push    # Apply schema changes
pnpm db:reset   # Reset database

📝 Environment Variables

| Variable | Default | Description | | ---------------- | --------------------------- | ---------------------------------------- | | NODE_ENV | development | Environment mode | | DATABASE_URL | ~/.claude/subclaude.md.db | SQLite database path | | LOG_LEVEL | info | Logging verbosity | | CLAUDE_API_KEY | - | Claude API key (if using LLM behaviours) |

🤝 Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Links

• Documentation
• API Reference
• Discord Community
• GitHub Repository

🆘 Support

• 📧 Email: [email protected]
• 💬 Discord: discord.gg/subclaude
• 🐛 Issues: GitHub Issues

Built with ❤️ by the SubClaude Team