Spellbook is a powerful, cross-platform desktop application for clustering, automating, and managing all your utility scripts—supercharged with AI.
Easily organize and execute a variety of scripts in seamless clusters, automate complex workflows with a single click, and use natural language to create new automations with Google Gemini.

• Cluster scripts with ease: Select, group, and run multiple scripts in a sequence or batch. No more manual copy-paste or script juggling—Spellbook lets you automate entire workflows using your existing utilities.
• AI-driven automation: Use natural language to describe what you want to automate, and let Gemini suggest, combine, or even generate scripts for you.
• Accessible & organized: Your scripts are always at your fingertips—tag, search, and manage them with a sleek visual interface.

• Script Library: Organize, tag, and search your scripts in one place
• AI-Powered Chat: Generate, cluster, and automate scripts using natural language
• Script Clustering: Select and run batches or sequences of scripts with a single click
• Desktop Native: Electron-powered, cross-platform app
• One-Click Execution: Run scripts with custom parameters and drag-n-drop files
• Agentic Automations: Let Gemini intelligently combine and automate your scripts
• Hot Reload: Rapid development via Docker Compose
• Secure: Environment-based secrets, safe script handling

spurhacks-25-proj/
├── backend/            # FastAPI backend (Python)
│   ├── app/
│   ├── requirements.txt
│   └── Dockerfile
├── frontend/           # (Optional: legacy frontend)
├── electron-frontend/  # Main desktop UI (React + Electron)
│   ├── src/
│   │   ├── components/
│   │   ├── index.html
│   │   └── index.css
│   ├── tailwind.config.js
│   ├── vite.config.js
│   └── preload.js
├── docker-compose.yml         # Production orchestration
├── docker-compose.dev.yml     # Development (hot reload)
└── README.md

• Docker & Docker Compose
• Node.js (for local frontend development)
• Google Gemini API Key

# Set your Google Gemini API key
export GOOGLE_API_KEY="your-api-key-here"

# Start all services (backend, frontend, MongoDB)
docker-compose -f docker-compose.dev.yml up

• Backend: http://localhost:8000
• Frontend: http://localhost:5173
• MongoDB: localhost:27017

docker-compose up --build

• Backend: http://localhost:8000
• Frontend: http://localhost
• MongoDB: localhost:27017

docker-compose down             # Stop all services
docker-compose down -v          # Stop and remove volumes (reset DB)
docker-compose logs -f [name]   # View logs for a service
docker-compose build [name]     # Rebuild a specific service
docker-compose exec backend bash  # Shell into backend container
docker-compose exec frontend sh   # Shell into frontend container

• Port conflicts: Ensure ports 80, 8000, 5173, 27017 are free.
• CORS issues: Adjust allowed origins in backend/app/main.py if needed.
• DB connection: Let MongoDB fully start before backend connects (handled by Docker Compose).
• Frontend API: Uses relative /api paths in production, absolute URLs in dev.

• Google Gemini
• FastAPI, React, Electron, Tailwind, MongoDB, Docker