AI Website Builder Agent 🌐

An intelligent AI agent powered by Google's Gemini API that can build complete websites based on natural language descriptions.

Created by Sanjay Sikdar.

Key Features Covered ✨

• Natural Language Interface — Just describe what you want, and the agent builds it.
• Command Execution System (⚙️) — Secure shell/terminal command execution with safety filters, validation and a 30-second timeout. (Exposed via the executeCommand tool.)
• File Operations (📁) — Read, write, and list files using modern fs/promises APIs (readFile, writeFile, listFiles).
• Persistent Chat Memory (📚) — Keeps conversational context for up to 20 messages with automatic trimming to stay within token limits.
• Modify Existing Components (🧱) — Edit HTML, CSS, or JS parts dynamically without breaking the overall document structure.
• Smart Code Generation — Produces clean, modern, responsive website scaffolds and component code.
• Rate Limiting + Retry Logic (⏳) — Built-in 2s delay between API calls plus automatic retries with exponential backoff (e.g., 5s, 15s, 30s), up to 3 retries for quota errors.
• Error Handling (🔒) — Robust handling with smart fallbacks for timeouts, authentication issues and other common failures.
• Image Placeholder Management (🖼️) — Uses services like picsum.photos and dummyimage.com for image placeholders during scaffolding.
• Cross-Platform Support (🖥️) — Works on Windows, macOS, and Linux (handles path and shell differences).
• Enhanced UX — Beautiful console output with emojis, progress indicators and clear retry/error messages.
• Security Features — Blocks dangerous commands and enforces command validation policies.

Installation 📦

# Install dependencies
npm install

Configuration ⚙️

1. Get your Google Gemini API key from Google AI Studio

2. Set as environment variable (recommended):

   # Linux/Mac
   export GEMINI_API_KEY=your_key_here
   
   # Windows PowerShell
   $env:GEMINI_API_KEY="your_key_here"
   
   # Windows CMD
   set GEMINI_API_KEY=your_key_here

Usage 🚀

npm start

Example Prompts:

• "Create a personal portfolio website with a hero section and contact form"
• "Build a landing page for a restaurant with a menu section"
• "Make a simple blog layout with header, main content area, and footer"
• "Create a modern website for a tech startup"

Commands:

• Type your request to create a website
• Type exit or quit to close the agent
• Type clear or reset to clear conversation history

Rate Limiting 🚦

The agent includes automatic rate limiting to prevent API quota issues:

• 2-second delay between API calls
• Automatic retry with exponential backoff (5s, 15s, 30s)
• Up to 3 retries on rate limit errors

If You Hit Rate Limits:

1. Wait 5-10 minutes and try again
2. Get a fresh API key from Google AI Studio
3. Switch to Gemini 1.5 Flash (more stable, higher limits)
4. Clear history frequently with clear command

See TROUBLESHOOTING.md for detailed solutions.

Available Tools 🛠️

The agent has access to these tools:

1. executeCommand: Run terminal/shell commands
2. readFile: Read file contents
3. writeFile: Create or update files (preferred for multi-line content)
4. listFiles: Explore directory structures

Security 🔒

The agent includes basic security features:

• Blocks dangerous commands (rm -rf /, format, shutdown, etc.)
• 30-second timeout for commands
• Command validation

Architecture 🏗️

• Model: Google Gemini 2.5 Flash - can be changed to 1.5 Flash
• Function Calling: Uses Gemini's function calling for tool execution
• History Management: Maintains conversation context with automatic trimming
• Iteration Limit: Maximum 15 tool calls per request to prevent infinite loops
• Rate Limiting: 2s delay between calls with retry logic

API Quota Limits 📊

Free Tier (Google AI Studio):

• Gemini 1.5 Flash: 15 requests/min, 1,500 requests/day
• Gemini 2.5 Flash: More restrictive (experimental)

Recommendations:

• Use gemini-1.5-flash for stability
• Clear history after each project
• Wait between requests
• Consider paid tier for heavy usage

Improvements Over Original 🚀

1. New Tools: Added readFile, writeFile, and listFiles for better file management
2. Better Code Generation: Uses writeFile instead of echo for cleaner multi-line content
3. Enhanced System Prompt: More detailed instructions and best practices
4. Security: Command validation and dangerous command blocking
5. UX: Beautiful console output with emojis and clear formatting
6. Error Handling: Specific error messages for different error types
7. API Key Management: Uses environment variables
8. Conversation Management: History trimming and reset capability
9. Iteration Limits: Prevents infinite loops
10. Rate Limiting: Automatic retry with exponential backoff to handle quota limits

Tips 💡

• Be specific about what you want in your website
• The agent works step-by-step, executing one action at a time
• You can ask for modifications after the initial build
• The agent follows modern web development best practices
• If you hit rate limits, switch to gemini-1.5-flash model

Troubleshooting 🔧

See TROUBLESHOOTING.md for detailed solutions to common issues:

• Error 429: Resource Exhausted
• Invalid API Key
• Maximum Iterations Reached
• Rate limiting configuration

License

MIT