OctoWand - AI-Powered Commit Assistant

OctoWand is an intelligent VS Code extension that generates commit messages using AI and learns from your patterns to provide increasingly accurate suggestions over time.

✨ Features

🤖 AI-Powered Generation

• Multiple AI Providers: OpenAI (GPT-3.5, GPT-4), Anthropic (Claude-3), Local Heuristics
• BYO API Key: Bring your own API keys for cost control
• Smart Fallback: Automatic fallback to local heuristics when AI is unavailable
• Real-time Generation: Generate commit messages in <2 seconds

🧠 Memory-Aware Suggestions

• Pattern Learning: Learns from your accepted commit messages
• Context Similarity: Finds similar past commits for better suggestions
• Confidence Scoring: Shows confidence level for each suggestion
• User Feedback: Improves suggestions based on your preferences

🎯 Intelligent Analysis

• Git Integration: Analyzes staged files and diffs automatically
• Project Context: Considers project type and recent commits
• Branch Awareness: Adapts to different branch naming conventions
• File Type Recognition: Understands different file types and their purposes

🎨 User-Friendly Interface

• Interactive Input: Easy-to-use commit message input with action buttons
• Patterns View: Browse and use learned patterns
• Analytics Dashboard: View usage statistics and performance metrics
• Status Bar Integration: Quick access from VS Code status bar

🚀 Installation

Prerequisites

• VS Code 1.85.0 or higher
• Node.js 18.0.0 or higher (for development)

Install from VSIX (Development)

1. Clone the repository:

   git clone https://github.com/your-org/octowand.git
   cd octowand/vscode-extension
   

2. Install dependencies:

   npm install
   

3. Compile the extension:

   npm run compile
   

4. Package the extension:

   npm run package
   

5. Install the VSIX file in VS Code:

   • Open VS Code
   • Go to Extensions (Ctrl+Shift+X)
   • Click the "..." menu and select "Install from VSIX..."
   • Select the generated .vsix file

Install from Marketplace (Coming Soon)

1. Open VS Code
2. Go to Extensions (Ctrl+Shift+X)
3. Search for "OctoWand"
4. Click Install

⚙️ Configuration

AI Provider Setup

OpenAI Configuration

1. Get your API key from OpenAI Platform
2. Open VS Code Settings (Ctrl+,)
3. Search for "OctoWand"
4. Set octowand.aiProvider to "openai"
5. Set octowand.openaiApiKey to your API key
6. Choose your model: gpt-3.5-turbo or gpt-4

Anthropic Configuration

1. Get your API key from Anthropic Console
2. Open VS Code Settings (Ctrl+,)
3. Search for "OctoWand"
4. Set octowand.aiProvider to "anthropic"
5. Set octowand.anthropicApiKey to your API key
6. Choose your model: claude-3-sonnet-20240229 or claude-3-opus-20240229

Environment Variables (Alternative)

You can also set API keys via environment variables:

export OPENAI_API_KEY="your-openai-key"
export ANTHROPIC_API_KEY="your-anthropic-key"

Configuration Options

📖 Usage

Basic Usage

Generate Commit Message

1. Stage your changes in VS Code
2. Open Command Palette (Ctrl+Shift+P)
3. Type "OctoWand: Generate Commit Message"
4. Review the generated message
5. Click "Accept and Commit" or edit as needed

Improve Existing Message

1. Open Command Palette (Ctrl+Shift+P)
2. Type "OctoWand: Improve Commit Message"
3. Enter your current commit message
4. Review the improved version
5. Accept or make further edits

Advanced Features

Using Learned Patterns

1. Open Command Palette (Ctrl+Shift+P)
2. Type "OctoWand: Show Learned Patterns"
3. Browse patterns in the sidebar
4. Click on a pattern to apply it to your current changes

Viewing Analytics

1. Open Command Palette (Ctrl+Shift+P)
2. Type "OctoWand: Show Analytics"
3. View usage statistics and performance metrics
4. Monitor pattern learning progress

Status Bar Integration

• Click the "✨ OctoWand" button in the status bar for quick access
• Shows current AI provider and generation status

Command Palette Commands

🎯 Commit Message Styles

Conventional Commits

feat: add user authentication
fix: resolve login validation issue
docs: update API documentation
style: format code according to style guide
refactor: simplify authentication logic
test: add unit tests for user service
chore: update dependencies

Simple Style

Add user authentication
Fix login validation
Update documentation
Format code
Simplify authentication
Add tests
Update dependencies

Detailed Style

feat(auth): implement OAuth2 authentication flow

- Add Google OAuth2 integration
- Create user session management
- Implement token refresh logic
- Add authentication middleware

Resolves [#123](https://github.com/Wundam/octowand/issues/123)

🔧 Development

Project Structure

vscode-extension/
├── src/
│   ├── extension.ts              # Main extension entry point
│   ├── services/                 # Core services
│   │   ├── ai-service.ts         # AI provider management
│   │   ├── git-service.ts        # Git integration
│   │   ├── memory-service.ts     # MemoryStore integration
│   │   └── performance-service.ts # Performance optimization
│   ├── ai/                       # AI providers
│   │   ├── openai-provider.ts    # OpenAI integration
│   │   ├── anthropic-provider.ts # Anthropic integration
│   │   └── local-heuristics.ts   # Local fallback
│   ├── ui/                       # User interface
│   │   ├── commit-message-input.ts
│   │   ├── patterns-view.ts
│   │   └── analytics-view.ts
│   ├── types/                    # TypeScript types
│   └── test/                     # Tests
├── package.json                  # Extension manifest
└── tsconfig.json                 # TypeScript config

Building from Source

# Install dependencies
npm install

# Compile TypeScript
npm run compile

# Run tests
npm test

# Lint code
npm run lint

# Package extension
npm run package

Testing

# Run unit tests
npm test

# Run extension tests
npm run test:extension

# Run with coverage
npm run test:coverage

📊 Performance

Benchmarks

• AI Generation: Average 1.2s, P95 1.8s
• Memory Operations: Average 0.3s, P95 0.8s
• UI Rendering: Average 0.2s, P95 0.5s
• Git Operations: Average 0.1s, P95 0.3s

Success Criteria

• ✅ Commit acceptance rate ≥50%
• ✅ P95 generation time <4s (achieved <2s)
• ✅ Suggestion surfacing <1.5s (achieved <1s)
• ✅ Extension stability (no crashes)

🔒 Security

Data Protection

• Encryption: AES-256-CBC encryption for stored data
• OS Keychain: Secure API key storage
• Environment Variables: Fallback for CI/testing
• Input Validation: Comprehensive input sanitization

Privacy

• Local Processing: Local heuristics for sensitive data
• Data Retention: Configurable retention policies
• No Telemetry: No data sent without consent

🐛 Troubleshooting

Common Issues

AI Provider Not Working

• Check API key configuration
• Verify internet connection
• Check API key permissions and quotas
• Try switching to local heuristics

MemoryStore Not Initializing

• Check workspace folder permissions
• Verify Node.js version (18.0.0+)
• Check keychain access permissions
• Try disabling encryption temporarily

Slow Performance

• Check network connection for AI providers
• Reduce maxTokens setting
• Enable caching in settings
• Check for large diffs or many staged files

Extension Not Activating

• Check VS Code version (1.85.0+)
• Restart VS Code
• Check extension logs in Developer Console
• Reinstall extension

Debug Mode

1. Open Command Palette (Ctrl+Shift+P)
2. Type "Developer: Toggle Developer Tools"
3. Check Console for error messages
4. Check Network tab for API calls

Logs

Extension logs are available in:

• VS Code Developer Console
• Output panel (select "OctoWand" from dropdown)

🤝 Contributing

Development Setup

1. Fork the repository
2. Clone your fork
3. Install dependencies: npm install
4. Create a feature branch
5. Make your changes
6. Run tests: npm test
7. Submit a pull request

Code Style

• Follow TypeScript best practices
• Use ESLint configuration
• Write comprehensive tests
• Document public APIs
• Follow conventional commit messages

📄 License

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

🙏 Acknowledgments

• VS Code team for the excellent extension API
• OpenAI and Anthropic for AI capabilities
• The open-source community for inspiration and tools

📞 Support

• Issues: GitHub Issues
• Documentation: Wiki
• Discussions: GitHub Discussions

Made with ❤️ by the OctoWand team