🤖 CreateFix AI

A floating AI-powered code assistant that lives on your desktop.
Select any code or error → press a hotkey → get an instant fix. Without leaving your editor.

---

✨ What It Does

CreateFix AI is a lightweight floating desktop overlay for developers. It sits silently on your screen as a small 🤖 bubble. When you encounter a bug or confusing code:

1. Select the code or error message in any app
2. Press Ctrl+Space (or click the robot icon)
3. The widget instantly copies your selection, sends it to Google's Gemini AI, and displays a clear explanation + fix — all without you switching windows

---

📸 Preview

Collapsed	Expanded (Result)
60×60 floating icon bubble	370×430 dark card with AI response
Click or Ctrl+Space to trigger	Drag header to reposition

---

🚀 Getting Started

Prerequisites

• Python 3.10+
• A Google Gemini API key — get one free at Google AI Studio

Installation

# 1. Clone the repository
git clone https://github.com/yourusername/createfix-ai.git
cd createfix-ai

# 2. Create and activate a virtual environment
python -m venv .venv
.venv\Scripts\activate        # Windows
# source .venv/bin/activate   # macOS / Linux

# 3. Install dependencies
pip install -r requirements.txt

Configuration

Option A — Environment variable (recommended):

# Windows (PowerShell)
$env:GEMINI_API_KEY = "your_api_key_here"
python main.py

# macOS / Linux
export GEMINI_API_KEY="your_api_key_here"
python main.py

Option B — Edit directly in automation.py:

API_KEY = os.environ.get("GEMINI_API_KEY", "paste_your_key_here")

Run

python main.py

The 🤖 bubble will appear in the top-left corner of your screen. Drag it anywhere you like.

---

🎮 Usage

Action	Trigger
Analyze selected code/error	Click the 🤖 icon or press Ctrl+Space
Dismiss the result card	Click ✕ in the header
Reposition the widget	Drag the header bar

How it works under the hood

You select code
    → Ctrl+Space pressed
        → Widget hides (restores focus to your app)
        → Simulates Ctrl+C to copy your selection
        → Widget reappears with "Analyzing..." status
        → Background thread calls Gemini API
        → Result displayed in scrollable card

---

🗂️ Project Structure

createfix-ai/
│
├── main.py           # Entry point — launches the widget and registers hotkey
├── ui_widget.py      # FloatingWidget (CustomTkinter UI, all visual logic)
├── automation.py     # AI API client, clipboard/keyboard automation, threading
├── requirements.txt  # Python dependencies
└── README.md

Key components

File	Responsibility
main.py	Initializes FloatingWidget, registers Ctrl+Space global hotkey
ui_widget.py	FloatingWidget — collapsed bubble ↔ expanded card transitions, drag, UI callbacks
automation.py	AutomationHandler — clipboard ops, Gemini API calls, retry/throttle logic · AnalysisThread — background worker

---

🧠 AI & Error Handling

Model fallback chain

Requests are attempted in order:

gemini-2.0-flash  →  gemini-2.0-flash-lite  →  gemini-2.5-flash

If one model returns a 404, the next is tried automatically.

Rate limit handling

• Throttle: minimum 10 seconds between API calls to stay within the free tier (15 RPM limit)
• Auto-retry: on a 429 error, waits RATE_LIMIT_WAIT seconds with a live countdown, then retries (up to MAX_RETRIES attempts)
• Quota exhausted: if all retries fail, shows a clear message with a link to check your Google Cloud quotas
• Timeout safety net: if no response arrives within 120 seconds, the widget shows a timeout error instead of hanging forever

Key constants in automation.py:

RATE_LIMIT_WAIT = 15   # seconds to wait between retries
MAX_RETRIES     = 2    # maximum retry attempts on rate limit

---

📦 Dependencies

Package	Purpose
customtkinter	Modern themed Tkinter UI
google-genai	Official Google Generative AI SDK
keyboard	Global hotkey listener (Ctrl+Space)
pyautogui	Keyboard simulation (copy command)
pyperclip	Cross-platform clipboard read/write
pillow	Image support for CustomTkinter

Install all at once:

pip install -r requirements.txt

---

⚙️ Customization

All tuneable values are at the top of their respective files:

automation.py — AI behavior:

RATE_LIMIT_WAIT = 15       # Retry wait in seconds
MAX_RETRIES     = 2        # Max retries on 429

ui_widget.py — Colors & fonts:

BG_DARK      = "#0f0f1a"   # Window background
ACCENT_BLUE  = "#4f8ef7"   # Primary accent
ACCENT_PURPLE= "#9b59f7"   # Secondary accent

main.py — Hotkey:

keyboard.add_hotkey('ctrl+space', app.trigger_from_hotkey)

Change 'ctrl+space' to any combination supported by the keyboard library.

---

🔐 Security Note

Your API key grants access to your Google Cloud quota. Never commit it to version control.
Use the GEMINI_API_KEY environment variable in production.

Add to .gitignore if you hardcode the key during development:

# Prevent accidental key exposure
automation.py

---

🛠️ Troubleshooting

Symptom	Likely cause	Fix
⏳ Rate limited	Free tier 429 error	Wait the countdown, or upgrade API plan
❌ Quota exhausted	Daily free limit hit	Check Google Cloud Quotas
Widget doesn't copy text	App focus issue	Ensure text is selected before triggering
KeyboardInterrupt on exit	Normal	Just close the terminal window
Blank result / no response	Empty clipboard	Select some text first

---

🗺️ Roadmap

• System tray icon support
• Configurable prompt templates (explain / fix / review modes)
• Response history (last N analyses)
• Settings GUI panel
• macOS & Linux packaging

---

📄 License

MIT © 2025 — free to use, modify, and distribute.

---

Built with 💙 using Python, CustomTkinter, and Google Gemini