kg6-codex/setup-guide.md

A modular, open-source AI Developer Assistant for automating and improving the software development lifecycle

# AI Developer Assistant - Usage Guide

## Quick Setup

### Step 1: Environment Setup
```bash
# Set your Gemini API key
export GEMINI_API_KEY="sk-your-api-key-here"

# Set Gemini as your LLM provider
export LLM_PROVIDER="gemini"
export LLM_MODEL="gemini-2.0-flash"
```

### Step 2: Build the Project
```bash
npm run build
```

### Step 3: Test the Installation
```bash
# Test basic functionality
npm run dev -- --help
```

## Core Commands

### 1. **Code Review** - Analyze your code for issues
```bash
# Review staged changes
ai-dev review --staged

# Review specific files
ai-dev review --file-patterns "src/**/*.ts"

# Review with verbose output
ai-dev review --verbose

# Review and post to GitHub PR
ai-dev review --post-github --github-owner your-org --github-repo your-repo --pr 123
```

### 2. **Code Explanation** - Understand what your code does
```bash
# Explain your last commit
ai-dev explain

# Explain with detailed analysis
ai-dev explain --level detailed --include-examples

# Explain specific files
ai-dev explain --file-patterns "src/utils/**/*.ts"
```

### 3. **Commit Message Generation** - Auto-generate commit messages
```bash
# Generate commit message for staged changes
ai-dev commit-msg --staged

# Generate with conventional commit format
ai-dev commit-msg --style conventional --include-body

# Generate with specific length
ai-dev commit-msg --max-length 100
```

### 4. **Security Scanning** - Find vulnerabilities
```bash
# Basic security scan
ai-dev security-scan

# Scan with specific severity levels
ai-dev security-scan --severity high,critical

# Scan including dependencies
ai-dev security-scan --include-dependencies
```

### 5. **Test Generation** - Create test cases
```bash
# Generate test suggestions
ai-dev test-suggest

# Generate for specific framework
ai-dev test-suggest --framework jest --type unit

# Generate with coverage target
ai-dev test-suggest --coverage-target 80
```

### 6. **Documentation Generation** - Create docs
```bash
# Generate documentation
ai-dev docs

# Generate API documentation
ai-dev docs --format jsdoc --include-examples

# Generate for specific files
ai-dev docs --file-patterns "src/api/**/*.ts"
```

### 7. **Refactoring Suggestions** - Improve code quality
```bash
# Get refactoring suggestions
ai-dev refactor

# Focus on specific areas
ai-dev refactor --focus performance

# Filter by severity
ai-dev refactor --severity high
```

### 8. **PR Summary** - Summarize pull request changes
```bash
# Summarize PR
ai-dev pr-summary --pr 123

# Include metrics
ai-dev pr-summary --include-metrics
```

### 9. **Developer Mentorship** - Get learning feedback
```bash
# Get mentorship feedback
ai-dev mentor

# Specify experience level
ai-dev mentor --level intermediate

# Focus on specific areas
ai-dev mentor --focus clean-code
```

## Configuration Options

### Environment Variables
```bash
# LLM Configuration
LLM_PROVIDER=gemini
LLM_MODEL=gemini-2.0-flash
LLM_TEMPERATURE=0.7
LLM_MAX_TOKENS=2000

# Gemini Configuration
GEMINI_API_KEY=your-gemini-api-key

# Output Configuration
AI_DEV_OUTPUT_FORMAT=console
AI_DEV_VERBOSE=true
AI_DEV_COLORIZE=true
```

### Configuration File (ai-dev.config.yaml)
```yaml
llm:
  provider: "gemini"
  model: "gemini-2.0-flash"
  temperature: 0.7
  maxTokens: 2000

gemini:
  apiKey: "${GEMINI_API_KEY}"
  model: "gemini-2.0-flash"

output:
  format: "console"
  colorize: true
  verbose: false
```

## Common Workflows

### Daily Development Workflow
```bash
# 1. Make your changes
git add .

# 2. Review your changes
ai-dev review --staged

# 3. Generate commit message
ai-dev commit-msg --staged --style conventional

# 4. Commit with the generated message
git commit -m "$(ai-dev commit-msg --staged)"
```

### Pull Request Workflow
```bash
# 1. Create PR and get PR number
# 2. Review with GitHub integration
ai-dev review --post-github --github-owner your-org --github-repo your-repo --pr 123

# 3. Generate PR summary
ai-dev pr-summary --pr 123
```

### Security Review Workflow
```bash
# 1. Full security scan
ai-dev security-scan --include-dependencies

# 2. Generate security report
ai-dev security-scan --format markdown --output-path security-report.md
```

### Documentation Workflow
```bash
# 1. Generate documentation for new code
ai-dev docs --format markdown --include-examples

# 2. Generate API documentation
ai-dev docs --format jsdoc --target "src/api/**/*.ts"
```

## Real Examples

### Example 1: Review a JavaScript Function
```bash
# Create a test file
echo 'function calculateTotal(items) {
  let total = 0;
  for (let i = 0; i <= items.length; i++) {
    total += items[i].price;
  }
  return total;
}' > test.js

# Review the code
ai-dev review --file-patterns "test.js"
```

### Example 2: Explain TypeScript Code
```bash
# Create a TypeScript file
echo 'interface User {
  id: string;
  name: string;
}

class UserService {
  private users: User[] = [];
  
  addUser(user: User): void {
    this.users.push(user);
  }
}' > user-service.ts

# Explain the code
ai-dev explain --file-patterns "user-service.ts" --level detailed
```

### Example 3: Generate Tests
```bash
# Generate tests for your code
ai-dev test-suggest --framework jest --type unit --file-patterns "src/**/*.ts"
```

## Output Formats

### Console Output (Default)
```bash
ai-dev review
```

### Markdown Output
```bash
ai-dev review --format markdown --output-path review.md
```

### JSON Output
```bash
ai-dev review --format json --output-path review.json
```

### File Output
```bash
ai-dev review --format file --output-path review.txt
```

## Troubleshooting

### Common Issues

**"No LLM provider available"**
```bash
# Check your configuration
ai-dev config validate

# Test Gemini connection
ai-dev config test --provider gemini
```

**"Git repository not found"**
```bash
# Make sure you're in a git repository
git status

# Initialize if needed
git init
```

**"Permission denied" errors**
```bash
# Make sure the binary is executable
chmod +x node_modules/.bin/ai-dev

# Or use npm/npx
npx ai-dev review
```

### Getting Help
```bash
# Get help for any command
ai-dev <command> --help

# List all available commands
ai-dev --help

# Check version and configuration
ai-dev version
ai-dev config show
```

## Success! 

You're now ready to use AI Developer Assistant with Gemini! The platform provides:

- **AI-powered code review** with detailed feedback
- **Code explanation** in plain English
- **Automated commit messages** following conventions
- **Security scanning** for vulnerabilities
- **Test generation** with multiple frameworks
- **Documentation creation** in various formats
- **Refactoring suggestions** for better code quality
- **PR summaries** for team collaboration
- **Developer mentorship** for learning and growth

Start with `ai-dev review` to analyze your code and explore the other commands as needed!