incize/README.md

AI Commit Copilot for Power Developers

# Incize — AI Commit Copilot for Power Developers

> **Surgical, developer-first AI-enhanced Git assistant for high-agency devs**

Insize analyzes your Git commits with AI to provide intelligent summaries, risk assessments, changelogs, and test suggestions — delivered through a fast, precise CLI.

## 🚀 Features (v0.2.0)

- **Real AI Integration**: Claude 3.5 Sonnet & GPT-4o support
- **Git Hook Integration**: Automatic pre/post-commit analysis
- **Commit Message Suggestions**: AI-powered commit message generation
- **Export Formats**: JSON, Markdown, and HTML output
- **Offline Mode**: Works without internet using mock AI
- **Focus Analysis**: Security, performance, quality, and testing focus
- **Silent Mode**: Perfect for CI/CD pipelines
- **Configuration Management**: Persistent API keys and settings

## 📦 Installation

### Prerequisites
- Node.js 18+ 
- Git repository

### Quick Install (NPX)
```bash
# Run directly without installation
npx incize@latest analyze

# Or install globally
npm install -g incize
```

### Manual Install
```bash
# Clone and install
git clone <repository-url>
cd incize
npm install
npm run build

# Link globally
npm link
```

## 🛠️ Usage

### Quick Start
```bash
# First time setup
incize config --set-keys --anthropic-key YOUR_ANTHROPIC_KEY --openai-key YOUR_OPENAI_KEY

# Analyze staged changes
incize analyze

# Get commit message suggestions
incize suggest --emoji

# Install git hooks for automatic analysis
incize hook --install
```

### Core Commands

#### `incize analyze` - Analyze staged changes
```bash
# Basic analysis
incize analyze

# Offline mode (no API calls)
incize analyze --offline

# Focus on specific areas
incize analyze --focus security
incize analyze --focus performance
incize analyze --focus quality
incize analyze --focus testing

# Use specific AI model
incize analyze --model claude-3-5-sonnet
incize analyze --model gpt-4o
incize analyze --model mock

# Silent mode for CI/CD
incize analyze --silent

# Export results
incize analyze | incize export --format json
```

#### `incize suggest` - Generate commit messages
```bash
# Get suggestions
incize suggest

# Conventional format
incize suggest --conventional

# With emojis
incize suggest --emoji

# Multiple suggestions
incize suggest --count 5
```

#### `incize config` - Manage configuration
```bash
# Show current config
incize config --show

# Set API keys
incize config --set-keys --anthropic-key sk-ant-api03-...
incize config --set-keys --openai-key sk-...

# Set individual keys
incize config --anthropic-key sk-ant-api03-...
incize config --openai-key sk-...

# Change default model
incize config --model claude-3-5-sonnet
```

#### `incize hook` - Manage git hooks
```bash
# Install hooks
incize hook --install

# Check status
incize hook --status

# Uninstall hooks
incize hook --uninstall
```

#### `incize export` - Export analysis
```bash
# Export as JSON
incize export --format json

# Export as Markdown
incize export --format markdown

# Export as HTML
incize export --format html

# Include diff in export
incize export --format markdown --include-diff
```

### Advanced Usage

#### CI/CD Integration
```bash
# In your CI pipeline
incize analyze --silent --focus security
if [ $? -eq 0 ]; then
    echo "✅ Analysis passed"
else
    echo "❌ Analysis failed"
    exit 1
fi
```

#### Batch Analysis
```bash
# Analyze multiple commits
for commit in $(git log --oneline -10 | cut -d' ' -f1); do
    git checkout $commit
    incize analyze --silent
done
```

#### Custom Configuration
```bash
# Set custom risk threshold
incize config --risk-threshold 75

# Enable telemetry
incize config --telemetry true

# Set default focus
incize config --default-focus security
```

## 📊 Output Examples

### Standard Analysis
```
🔍 Incize Analysis
──────────────────────────────────────────────────

📝 Commit Details
  Hash: a1b2c3d4
  Author: John Doe
  Branch: feature/auth
  Message: Add user authentication system
  Date: 2024-01-15T10:30:00Z

📊 Changes Summary
  Files: 3
  Additions: +45
  Deletions: -12
  Total: 57
  Languages: TypeScript, JavaScript

🤖 AI Analysis
──────────────────────────────

📋 Summary:
  Added comprehensive user authentication system with JWT tokens,
  password hashing, and session management.

⚠️  Risk Assessment:
  Score: 35/100
  Level: MEDIUM
  ████████░░░░░░░░░░░░

💡 Suggestions:
  1. Add rate limiting for login attempts
  2. Consider implementing 2FA
  3. Add input validation for email format
  4. Include password strength requirements

📝 Changelog Entry:
  feat: Add user authentication system with JWT and session management

🧪 Test Suggestions:
  1. Add unit tests for authentication service
  2. Include integration tests for login/logout flow
  3. Test password reset functionality
  4. Add security tests for JWT token validation

🎯 Confidence: 85%
```

### Export Example (JSON)
```json
{
  "analysis": {
    "riskScore": 35,
    "riskLevel": "medium",
    "summary": "Added comprehensive user authentication system...",
    "suggestions": [
      "Add rate limiting for login attempts",
      "Consider implementing 2FA"
    ],
    "changelog": "feat: Add user authentication system",
    "testSuggestions": [
      "Add unit tests for authentication service"
    ],
    "confidence": 0.85
  },
  "metadata": {
    "timestamp": "2024-01-15T10:30:00Z",
    "commit": "a1b2c3d4",
    "author": "John Doe",
    "branch": "feature/auth"
  }
}
```

## 🔧 Configuration

### API Keys Setup
```bash
# Get your API keys from:
# Anthropic: https://console.anthropic.com/
# OpenAI: https://platform.openai.com/api-keys

# Set both keys at once
incize config --set-keys --anthropic-key sk-ant-api03-... --openai-key sk-...

# Or set individually
incize config --anthropic-key sk-ant-api03-...
incize config --openai-key sk-...
```

### Configuration File
Located at `~/.incize/config.json`:
```json
{
  "anthropicApiKey": "sk-ant-api03-...",
  "openaiApiKey": "sk-...",
  "defaultModel": "claude-3-5-sonnet",
  "telemetryEnabled": true,
  "riskThreshold": 50,
  "defaultFocus": "quality"
}
```

## 🚨 Troubleshooting

### Common Issues

#### "Not in a Git repository"
```bash
# Make sure you're in a git repository
git init
# or
cd /path/to/your/git/repo
```

#### "Invalid API key format"
```bash
# Check your API key format
# Anthropic: sk-ant-api03-[40+ characters]
# OpenAI: sk-[48 characters]

incize config --show
```

#### "Analysis failed - API error"
```bash
# Try offline mode
incize analyze --offline

# Check your API keys
incize config --show

# Test with mock model
incize analyze --model mock
```

#### "Git hooks not working"
```bash
# Reinstall hooks
incize hook --uninstall
incize hook --install

# Check hook status
incize hook --status

# Verify hook files exist
ls -la .git/hooks/
```

### Performance Issues
```bash
# Use silent mode for faster output
incize analyze --silent

# Use offline mode for instant results
incize analyze --offline

# Use mock model for testing
incize analyze --model mock
```

## 🏗️ Development

### Project Structure
```
src/
├── cli/           # CLI entry point and commands
├── core/          # Core business logic
│   ├── ai/        # AI services and prompt formatting
│   ├── config/    # Configuration management
│   ├── git/       # Git operations and hooks
│   └── output/    # Export and rendering
├── types/         # TypeScript interfaces
└── utils/         # Shared utilities
```

### Development Commands
```bash
# Install dependencies
npm install

# Development mode (watch for changes)
npm run dev

# Build for production
npm run build

# Run tests
npm test

# Type checking
npm run type-check

# Linting
npm run lint
```

## 🎯 Best Practices

### For Developers
1. **Use Git Hooks**: Install hooks for automatic analysis
2. **Set API Keys**: Configure real AI models for better insights
3. **Review Suggestions**: Always consider AI suggestions
4. **Export Results**: Use exports for documentation
5. **Silent Mode**: Use `--silent` in CI/CD pipelines

### For Teams
1. **Standardize Configuration**: Use consistent settings across team
2. **Document Analysis**: Export and share analysis results
3. **Set Risk Thresholds**: Agree on acceptable risk levels
4. **Regular Reviews**: Use analysis for code reviews

### For CI/CD
1. **Pre-commit Hooks**: Catch issues before they're committed
2. **Silent Mode**: Use `--silent` to avoid verbose output
3. **Focus Areas**: Use `--focus security` for security-critical repos
4. **Export Results**: Save analysis for later review

## 🚧 Roadmap

### v0.3 — Enhanced Features
- [ ] Historical analysis and trends
- [ ] Batch repository analysis
- [ ] Team collaboration features
- [ ] Custom rule definitions

### v0.4 — Advanced Integration
- [ ] GitHub Actions integration
- [ ] GitLab CI integration
- [ ] Slack/Discord notifications
- [ ] Custom export templates

## 🤝 Contributing

This is a closed-source project. For internal development:

1. Follow TypeScript strict mode
2. Write tests for new features
3. Ensure offline mode functionality
4. Maintain <30s setup time
5. Keep output actionable and clear

## 📄 License

UNLICENSED - Closed source project

## 🎯 Success Metrics

- ✅ CLI detects commits and renders AI-enhanced summary + score
- ✅ Works without online mode
- ✅ Setup in <30s
- ✅ Output is actionable and clear
- ✅ Zero bloat, maximum precision
- ✅ Production-ready error handling
- ✅ Comprehensive documentation

---

**Built for high-agency devs who want clarity, speed, and control — without bloat or ceremony.**