Skip to content

Instantly share code, notes, and snippets.

@martinschenk
Created September 27, 2025 01:32
Show Gist options
  • Select an option

  • Save martinschenk/6928c5f53d6e9b60ee10dc27db8e6d0f to your computer and use it in GitHub Desktop.

Select an option

Save martinschenk/6928c5f53d6e9b60ee10dc27db8e6d0f to your computer and use it in GitHub Desktop.
AI-Powered GitHub Issue Creator - Convert natural language ideas to professional GitHub issues using OpenAI. Supports multilingual input (German, French, Spanish, etc.) with automatic English translation. Smart label detection and priority assessment.

AI-Powered GitHub Issue Creator

A smart command-line tool that converts natural language ideas into professional GitHub issues using OpenAI's GPT models.

πŸš€ Features

  • πŸ€– AI-Powered: OpenAI automatically analyzes your input
  • 🌍 Multilingual: Input in German, French, Spanish - outputs in English
  • 🏷️ Smart Labels: AI automatically assigns appropriate labels
  • ⚑ Priority Detection: Automatic priority assessment (low/medium/high/critical)
  • πŸ’¬ Natural Input: No quotes needed, all special characters supported
  • 🎯 Project-Aware: Only works within Git repositories

πŸ“‹ Quick Setup

1. Prerequisites

Install required tools:

# macOS
brew install gh jq

# Ubuntu/Debian
sudo apt install gh jq

# Verify installation
gh --version
jq --version

2. GitHub Authentication

gh auth login

3. OpenAI API Key Setup

Choose one method:

Option A: Environment Variable (Recommended)

export OPENAI_API_KEY="sk-your-api-key-here"
# Add to ~/.bashrc or ~/.zshrc for persistence
echo 'export OPENAI_API_KEY="sk-your-api-key-here"' >> ~/.bashrc

Option B: Project .env File

echo 'OPENAI_API_KEY=sk-your-api-key-here' > .env

Option C: Global Config File

echo 'sk-your-api-key-here' > ~/.openai_api_key

Get your API key from: https://platform.openai.com/api-keys

4. Install Script

Save the script as todo in your project directory:

# Download script
curl -o todo https://gist.github.com/your-username/gist-id/raw/ai-github-todo-creator.sh

# Make executable
chmod +x todo

# Optional: Create alias for convenience
echo "alias todo='noglob ./todo'" >> ~/.bashrc
source ~/.bashrc

🎯 Usage

Basic Usage

# Simple ideas (no quotes needed!)
todo Memory system should auto-backup to cloud
todo Voice input would be cool with hotkey
todo Performance optimization for large datasets

# Bug reports
todo Bug: Special characters not saving correctly
todo Crash when uploading files over 10MB
todo Login fails with 2FA enabled

# With special characters (all supported!)
todo Can we add auto-save? That would be awesome!
todo Export feature: CSV/JSON formats needed {urgent}
todo API timeout issues @high-traffic endpoints

Multilingual Input

# German
todo Speicher-System sollte automatisch sichern
todo Bug: Umlaute werden nicht richtig gespeichert

# French
todo Système de sauvegarde automatique serait pratique
todo Erreur: Les caractères spéciaux ne fonctionnent pas

# Spanish
todo Sistema de respaldo automΓ‘tico serΓ­a ΓΊtil
todo Error: Los acentos no se guardan correctamente

βš™οΈ Configuration & Customization

GitHub Labels Setup

Create recommended labels for better AI categorization:

# Priority labels
gh label create "priority-high" --color "ff0000" --description "High priority issue"
gh label create "priority-medium" --color "ffaa00" --description "Medium priority issue"
gh label create "priority-low" --color "00ff00" --description "Low priority issue"
gh label create "priority-critical" --color "800000" --description "Critical priority issue"

# Feature labels
gh label create "feature-request" --color "a2eeef" --description "New feature request"
gh label create "ui-ux" --color "ff7f00" --description "User interface improvements"
gh label create "performance" --color "ffeb3b" --description "Performance related issues"
gh label create "security" --color "e91e63" --description "Security related issues"

# Technical labels
gh label create "api" --color "0366d6" --description "API related issues"
gh label create "frontend" --color "bfdadc" --description "Frontend related issues"
gh label create "backend" --color "c2e0c6" --description "Backend related issues"
gh label create "mobile" --color "f9d0c4" --description "Mobile related issues"
gh label create "testing" --color "d4c5f9" --description "Testing related issues"

Customize AI Prompt

Edit the script to customize AI behavior for your project:

# Find this section in the script and modify:
"Suggest appropriate labels from: bug, enhancement, documentation, question, priority-high, priority-medium, priority-low, priority-critical, feature-request, ui-ux, performance, security, api, frontend, backend, mobile, testing"

# Example for web project:
"Suggest appropriate labels from: bug, enhancement, frontend, backend, api, database, security, ui-ux, performance, responsive-design, seo"

# Example for mobile app:
"Suggest appropriate labels from: bug, enhancement, ios, android, ui-ux, performance, crash, feature-request, accessibility, testing"

Project-Specific Installation

For multiple projects, create project-specific versions:

# Copy script to each project
cp todo ~/project1/todo
cp todo ~/project2/todo

# Or create global installation
sudo cp todo /usr/local/bin/todo
# Then use from any git repository

πŸ”§ Advanced Configuration

Custom API Key Locations

Modify the script to support custom API key locations:

# Add custom location after line ~70:
elif [ -f "/path/to/your/custom/config" ]; then
    API_KEY=$(cat "/path/to/your/custom/config" | tr -d '\n')

Change OpenAI Model

Edit the API call to use different models:

# Find this line and change the model:
"model": "gpt-4o-mini",

# Options:
"model": "gpt-4o",           # More powerful, more expensive
"model": "gpt-4o-mini",      # Good balance (default)
"model": "gpt-3.5-turbo",    # Faster, cheaper

Customize Output Format

Modify the AI prompt to change issue structure:

# Find the JSON format section and customize:
{
  \"title\": \"Clear issue title\",
  \"body\": \"## Problem\\n\\nWhat's wrong\\n\\n## Solution\\n\\nHow to fix\\n\\n## Acceptance Criteria\\n\\n- [ ] Criterion 1\\n- [ ] Criterion 2\",
  \"labels\": [\"label1\", \"label2\"],
  \"type\": \"bug|enhancement|documentation|question\",
  \"priority\": \"low|medium|high|critical\"
}

πŸ› οΈ Troubleshooting

Common Issues

Error: Not in git repository

# Solution: Run from within a Git repository
cd /path/to/your/project
git init  # if not a git repo yet

Error: GitHub CLI not installed

# macOS
brew install gh

# Ubuntu/Debian
curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg
echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
sudo apt update && sudo apt install gh

Error: OpenAI API key not found

# Check your setup:
echo $OPENAI_API_KEY
cat .env | grep OPENAI
cat ~/.openai_api_key

# Verify API key format (should start with 'sk-')

Error: Label not found

# Create missing labels manually:
gh label create "priority-high" --color "ff0000" --description "High priority"

# Or remove labels from the AI suggestion list in the script

Debug Mode

Add debug output to the script:

# Add after line ~80:
echo "DEBUG: API Key length: ${#API_KEY}"
echo "DEBUG: User input: $USER_INPUT"
echo "DEBUG: API Response: $RESPONSE"

πŸ“Š Managing Issues

View Issues

# List all open issues
gh issue list

# Filter by labels
gh issue list --label bug
gh issue list --label priority-high
gh issue list --label enhancement

# View specific issue
gh issue view 42

Issue Workflow

# Assign issue
gh issue edit 42 --add-assignee username

# Add labels
gh issue edit 42 --add-label "in-progress"

# Close issue
gh issue close 42 --comment "Fixed in commit abc123"

# Reopen issue
gh issue reopen 42

🎯 Best Practices

Writing Good Input

Good Examples:

todo User authentication should support 2FA for better security
todo Performance issue: App becomes slow with 1000+ items
todo Export functionality needed for data backup purposes
todo Bug: Special characters break the search function

Avoid:

todo fix thing          # Too vague
todo add stuff          # Not descriptive
todo urgent!!!          # No context

Label Organization

Priority System:

  • priority-critical: Security vulnerabilities, data loss, app crashes
  • priority-high: Major features, significant bugs affecting many users
  • priority-medium: Minor features, small bugs, improvements
  • priority-low: Nice-to-have features, cosmetic issues

Type System:

  • bug: Something is broken
  • enhancement: Improve existing functionality
  • feature-request: Completely new functionality
  • documentation: Docs related
  • question: Need clarification

Workflow Integration

Link Issues to Code:

# In commit messages:
git commit -m "Fix login bug - fixes #42"
git commit -m "Add export feature - closes #38"

# In pull requests:
# "This PR implements the export feature requested in #38"

πŸ“ˆ Analytics & Metrics

Track your project's progress:

# Issue statistics
gh issue list --state all | wc -l     # Total issues
gh issue list --state open | wc -l    # Open issues
gh issue list --state closed | wc -l  # Closed issues

# Label distribution
gh issue list --json labels --jq '.[].labels[].name' | sort | uniq -c | sort -nr

🀝 Team Usage

For team projects:

  1. Share the script with team members
  2. Standardize labels across the project
  3. Create issue templates for consistency
  4. Use milestones for sprint planning
  5. Set up notifications for new issues

πŸ“„ License

MIT License - Feel free to modify and distribute.

πŸ™‹ Support


Created with ❀️ by the AI Chat Terminal Team

#!/bin/bash
# AI-Powered GitHub Issue Creator
# Converts natural language input to professional GitHub issues using OpenAI
#
# Usage: todo Your idea or bug description here (no quotes needed!)
# Requirements: gh CLI, OpenAI API key, jq
# Author: AI Chat Terminal Team
# License: MIT
set -e
# Colors for output
RED='\033[0;31m'
GREEN='\033[0;32m'
YELLOW='\033[1;33m'
BLUE='\033[0;34m'
RESET='\033[0m'
# Check if we're in a git repository
if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
echo -e "${RED}Error: Must be run inside a git repository${RESET}"
exit 1
fi
# Check if gh CLI is available
if ! command -v gh &> /dev/null; then
echo -e "${RED}Error: GitHub CLI (gh) is not installed${RESET}"
echo "Install with: brew install gh (macOS) or see https://cli.github.com/"
exit 1
fi
# Check if jq is available
if ! command -v jq &> /dev/null; then
echo -e "${RED}Error: jq is not installed${RESET}"
echo "Install with: brew install jq (macOS) or apt install jq (Linux)"
exit 1
fi
# Check if authenticated with GitHub
if ! gh auth status >/dev/null 2>&1; then
echo -e "${RED}Error: Not authenticated with GitHub${RESET}"
echo "Run: gh auth login"
exit 1
fi
# Get user input (everything after the command)
USER_INPUT="$*"
if [ -z "$USER_INPUT" ]; then
echo -e "${RED}Error: Please provide an idea or bug report${RESET}"
echo "Usage: todo Your idea or bug description here"
echo "Example: todo Memory system should auto-backup to cloud"
exit 1
fi
# OpenAI API Key Configuration
# Option 1: Environment variable
if [ -n "$OPENAI_API_KEY" ]; then
API_KEY="$OPENAI_API_KEY"
# Option 2: From .env file in current directory
elif [ -f ".env" ] && grep -q "OPENAI_API_KEY" ".env"; then
source ".env"
API_KEY="$OPENAI_API_KEY"
# Option 3: From global config file
elif [ -f "$HOME/.openai_api_key" ]; then
API_KEY=$(cat "$HOME/.openai_api_key" | tr -d '\n')
# Option 4: From AI Chat Terminal (if available)
elif [ -f "$HOME/.aichat/.env" ]; then
source "$HOME/.aichat/.env"
API_KEY="$OPENAI_API_KEY"
else
echo -e "${RED}Error: OpenAI API key not found${RESET}"
echo ""
echo "Please set your OpenAI API key using one of these methods:"
echo "1. Environment variable: export OPENAI_API_KEY='sk-...'"
echo "2. Create .env file: echo 'OPENAI_API_KEY=sk-...' > .env"
echo "3. Global file: echo 'sk-...' > ~/.openai_api_key"
echo ""
echo "Get your API key from: https://platform.openai.com/api-keys"
exit 1
fi
if [ -z "$API_KEY" ]; then
echo -e "${RED}Error: OpenAI API key is empty${RESET}"
exit 1
fi
echo -e "${BLUE}πŸ€– Analyzing your input with AI...${RESET}"
# Create AI prompt for analysis
AI_PROMPT="You are a GitHub issue assistant. Analyze the following user input and create a professional GitHub issue.
Instructions:
1. If the input is in German, French, Spanish, or another language, translate to English
2. Determine the issue type: bug, enhancement, documentation, or question
3. Assess priority: low, medium, high, or critical
4. Create a clear, professional title (max 50 characters)
5. Write a detailed body with Description, Use Case, and Technical Details if applicable
6. Suggest appropriate labels from: bug, enhancement, documentation, question, priority-high, priority-medium, priority-low, priority-critical, feature-request, ui-ux, performance, security, api, frontend, backend, mobile, testing
User input: \"$USER_INPUT\"
Respond ONLY with valid JSON in this exact format:
{
\"title\": \"Clear issue title\",
\"body\": \"## Description\\n\\nDetailed description here\\n\\n## Use Case\\n\\nWhy this matters\\n\\n## Technical Details\\n\\nImplementation notes if applicable\",
\"labels\": [\"label1\", \"label2\", \"label3\"],
\"type\": \"bug|enhancement|documentation|question\",
\"priority\": \"low|medium|high|critical\"
}"
# Call OpenAI API
RESPONSE=$(curl -s -X POST "https://api.openai.com/v1/chat/completions" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d "{
\"model\": \"gpt-4o-mini\",
\"messages\": [
{
\"role\": \"system\",
\"content\": \"You are a helpful assistant that creates GitHub issues. Always respond with valid JSON only.\"
},
{
\"role\": \"user\",
\"content\": $(echo "$AI_PROMPT" | jq -R -s .)
}
],
\"temperature\": 0.3,
\"max_tokens\": 800
}")
# Check if API call was successful
if [ $? -ne 0 ]; then
echo -e "${RED}Error: Failed to call OpenAI API${RESET}"
exit 1
fi
# Check for API errors
if echo "$RESPONSE" | jq -e '.error' >/dev/null 2>&1; then
ERROR_MSG=$(echo "$RESPONSE" | jq -r '.error.message')
echo -e "${RED}OpenAI API Error: $ERROR_MSG${RESET}"
exit 1
fi
# Extract the content from the API response
AI_CONTENT=$(echo "$RESPONSE" | jq -r '.choices[0].message.content // empty')
if [ -z "$AI_CONTENT" ]; then
echo -e "${RED}Error: No response from OpenAI API${RESET}"
echo "API Response: $RESPONSE"
exit 1
fi
# Parse the AI response JSON
TITLE=$(echo "$AI_CONTENT" | jq -r '.title // empty')
BODY=$(echo "$AI_CONTENT" | jq -r '.body // empty')
LABELS=$(echo "$AI_CONTENT" | jq -r '.labels[]? // empty' | tr '\n' ',' | sed 's/,$//')
TYPE=$(echo "$AI_CONTENT" | jq -r '.type // "enhancement"')
PRIORITY=$(echo "$AI_CONTENT" | jq -r '.priority // "medium"')
# Validate required fields
if [ -z "$TITLE" ] || [ -z "$BODY" ]; then
echo -e "${RED}Error: AI failed to generate proper issue format${RESET}"
echo "AI Response: $AI_CONTENT"
exit 1
fi
# Display what will be created
echo -e "${YELLOW}πŸ“ Creating GitHub issue:${RESET}"
echo -e "${GREEN}Title:${RESET} $TITLE"
echo -e "${GREEN}Type:${RESET} $TYPE"
echo -e "${GREEN}Priority:${RESET} $PRIORITY"
echo -e "${GREEN}Labels:${RESET} $LABELS"
echo ""
# Create the GitHub issue
if [ -n "$LABELS" ]; then
ISSUE_URL=$(gh issue create --title "$TITLE" --body "$BODY" --label "$LABELS" 2>/dev/null)
else
ISSUE_URL=$(gh issue create --title "$TITLE" --body "$BODY" 2>/dev/null)
fi
# Check if issue creation was successful
if [ $? -eq 0 ] && [ -n "$ISSUE_URL" ]; then
echo -e "${GREEN}βœ… Issue created successfully!${RESET}"
echo -e "${BLUE}πŸ”— $ISSUE_URL${RESET}"
# Extract issue number from URL
ISSUE_NUMBER=$(echo "$ISSUE_URL" | grep -o '[0-9]\+$')
echo -e "${YELLOW}πŸ’‘ You can view it with: gh issue view $ISSUE_NUMBER${RESET}"
else
echo -e "${RED}❌ Failed to create GitHub issue${RESET}"
echo "This might be because some labels don't exist yet."
echo "Create missing labels with: gh label create \"label-name\" --color \"ff0000\""
exit 1
fi
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment