npm package: @subclaude/cli
Description: AI Code Quality Guardian CLI - Intelligent auditing layer that enforces opinionated best practices and prevents vibe coding anti-patterns across all languages and frameworks in real-time
Author: SubClaude Team
Latest version: 1.0.0

# SubClaude CLI

[![npm version](https://badge.fury.io/js/%40subclaude%2Fcli.svg)](https://badge.fury.io/js/%40subclaude%2Fcli)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

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

```bash
npm install -g @subclaude/cli
```

### Local Installation

```bash
npm install @subclaude/cli
```

### Development Installation

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

## 🎯 Quick Start

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

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

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

```bash
# 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](LICENSE) file for details.

## 🔗 Links

- [Documentation](https://docs.subclaude.dev)
- [API Reference](https://api.subclaude.dev)
- [Discord Community](https://discord.gg/subclaude)
- [GitHub Repository](https://github.com/subclaude/subclaude)

## 🆘 Support

- 📧 Email: team@subclaude.dev
- 💬 Discord: [discord.gg/subclaude](https://discord.gg/subclaude)
- 🐛 Issues: [GitHub Issues](https://github.com/subclaude/subclaude/issues)

---

**Built with ❤️ by the SubClaude Team**