GBAI - Git Branch AI

CLI tool that auto-generates branch names from GitHub issues using AI

📦 Installation

npm install -g gbai

🚀 Quick Start

Basic Usage

# Using full GitHub URL
gbai https://github.com/owner/repo/issues/123

# Using issue number (requires origin setup)
gbai 123
gbai '#123'  # Hash format (must be quoted)

# After that, it auto creates your branch using the suggested name!

First-Time Setup

# Set your AI provider
gbai set-provider gemini

# Set your model
gbai set-model gemini-2.5-flash

# Set repository origin (for short issue references)
gbai set-origin owner/repo

✨ Features

🤖 Multiple AI Providers

• OpenAI - GPT models (gpt-5, gpt-4o, etc.)
• Google Gemini - Latest Gemini models
• Anthropic Claude - Claude 3.5 Sonnet and others
• Ollama - Local models

🎯 Smart Pattern Detection

• Automatically detects existing branch naming patterns from your repository
• Supports manual pattern creation with helpful examples
• AI-powered pattern suggestions based on repository analysis

🔧 Flexible Issue References

• Full URLs: https://github.com/owner/repo/issues/123
• Issue numbers: 123 (requires repository origin)
• Hash format: #123 (must be quoted: '#123')

⚙️ Configuration Management

• Global settings: AI provider and model (stored in ~/.config/gbai/)
• Local settings: Branch patterns and repository origin (stored in ./.gbai/)
• Automatic git origin detection when using issue numbers

🛠️ Commands

Core Commands

gbai <issue-reference>    # Generate branch from issue
gbai config              # Show current configuration

Configuration Commands

gbai set-provider <provider>    # Set AI provider (openai, gemini, claude, ollama)
gbai set-model <model>         # Set AI model
gbai set-pattern <pattern>     # Set branch naming pattern
gbai set-origin <origin>       # Set repository origin

📋 Examples

Setting up OpenAI

export OPENAI_API_KEY="your-api-key" # Or set it up in your shell config file
gbai set-provider openai
gbai set-model gpt-4.1

Setting up repository origin

# Various formats supported
gbai set-origin owner/repo
gbai set-origin https://github.com/owner/repo
gbai set-origin git@github.com:owner/repo.git

Pattern Creation Workflow

gbai https://github.com/owner/repo/issues/123

# First time - you'll see:
# 🎯 It appears that this is your first time running `gbai` in this project
# Would you like to have AI suggest branch naming patterns for you? Or create your pattern manually?
# 
# Options:
# - AI Suggest Patterns - Let AI analyze existing branches
# - Create Pattern Manually - Define your own pattern

Manual Pattern Examples

gbai set-pattern "feature/ISSUE_ID-DESCRIPTION"  # → feature/123-add-login
gbai set-pattern "ISSUE_ID-TYPE-DESCRIPTION"     # → 123-feature-add-login  
gbai set-pattern "TYPE/DESCRIPTION"              # → feature/add-login
gbai set-pattern "TYPE-DESCRIPTION-ISSUE_ID"     # → feature-add-login-123

🔑 Environment Variables

Required API Keys

# For OpenAI
export OPENAI_API_KEY="your-openai-api-key"

# For Google Gemini  
export GEMINI_API_KEY="your-gemini-api-key"

# For Anthropic Claude
export CLAUDE_API_KEY="your-claude-api-key"

# Ollama requires no API key (local)

📁 Configuration Files

Global Configuration (~/.config/gbai/config.json)

{
  "provider": "openai",
  "model": "gpt-4.1"
}

Local Configuration (./.gbai/config.json)

{
  "pattern": "feature/ISSUE_ID-DESCRIPTION",
  "origin": "owner/repo"
}

🎨 Pattern Variables

Use these placeholders in your branch patterns:

• ISSUE_ID - GitHub issue number
• DESCRIPTION - AI-generated description from issue title
• TYPE - Auto-detected type (feature, fix, etc.)

🔄 How It Works

1. Issue Analysis: Fetches GitHub issue details (title, description, labels)
2. Pattern Detection: First run analyzes repository branches or allows manual pattern creation
3. AI Generation: Uses your chosen AI provider to generate branch name following the pattern
4. Branch Creation: Creates and checks out the new branch
5. Configuration Persistence: Saves settings for future use

🤔 Why?

Branch names are annoying to author sometimes.

🚨 Common Gotchas

Shell Comments with Hash Symbol

# ❌ This won't work (shell treats # as comment)
gbai #123

# ✅ Use quotes instead  
gbai '#123'

# ✅ Or use without hash
gbai 123

Missing Repository Origin

# Error: No repository origin configured
gbai set-origin owner/repo

# Or use full URL instead
gbai https://github.com/owner/repo/issues/123

Provider/Model Mismatch

When changing providers, models are automatically reset to avoid incompatibilities:

gbai set-provider openai
# 🔄 Model reset due to provider change
gbai set-model gpt-4.1  # Set compatible model

🤝 Contributing

1. Fork the repository
2. Create a feature branch: (For existing issues, use gbai '#123' 😉)
3. Make your changes
4. Submit a pull request

📄 License

MIT License - see LICENSE for details.

🔗 Links

• Repository: https://github.com/that-one-arab/gbai
• Issues: https://github.com/that-one-arab/gbai/issues
• NPM Package: https://www.npmjs.com/package/gbai

---

Made with ❤️ by Muhammed Aldulaimi