{"id":31830762,"url":"https://github.com/gemini-cli-extensions/nanobanana","last_synced_at":"2026-01-17T13:04:47.262Z","repository":{"id":317700365,"uuid":"1060400667","full_name":"gemini-cli-extensions/nanobanana","owner":"gemini-cli-extensions","description":null,"archived":false,"fork":false,"pushed_at":"2025-11-20T17:31:15.000Z","size":118,"stargazers_count":465,"open_issues_count":12,"forks_count":40,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-11-20T19:20:20.572Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gemini-cli-extensions.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"docs/contributing.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T21:08:55.000Z","updated_at":"2025-11-20T17:29:50.000Z","dependencies_parsed_at":"2025-10-02T15:08:45.053Z","dependency_job_id":"5d23a925-ab40-47a1-ac43-d7700e88f71d","html_url":"https://github.com/gemini-cli-extensions/nanobanana","commit_stats":null,"previous_names":["gemini-cli-extensions/nanobanana"],"tags_count":12,"template":false,"template_full_name":null,"purl":"pkg:github/gemini-cli-extensions/nanobanana","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemini-cli-extensions%2Fnanobanana","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemini-cli-extensions%2Fnanobanana/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemini-cli-extensions%2Fnanobanana/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemini-cli-extensions%2Fnanobanana/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gemini-cli-extensions","download_url":"https://codeload.github.com/gemini-cli-extensions/nanobanana/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gemini-cli-extensions%2Fnanobanana/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28508943,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T11:50:55.898Z","status":"ssl_error","status_checked_at":"2026-01-17T11:50:55.569Z","response_time":85,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-10-11T21:26:06.348Z","updated_at":"2026-01-17T13:04:47.251Z","avatar_url":"https://github.com/gemini-cli-extensions.png","language":"TypeScript","funding_links":[],"categories":["Image Generation \u0026 Rendering","AI and Agents"],"sub_categories":[],"readme":"\u003e [!NOTE]  \n\u003e Nano Banana Pro (`gemini-3-pro-image-preview`) is now supported in this extension (v1.0.10+)!\n\u003e\n\u003e Set the `NANOBANANA_MODEL` environment variable to `gemini-3-pro-image-preview` to use it.\n\n# Nano Banana - Gemini CLI Extension\n\nA professional Gemini CLI extension for generating and manipulating images using the Nano Banana models.\n\n## ✨ Features\n\n- **🎨 Text-to-Image Generation**: Create stunning images from descriptive prompts\n- **✏️ Image Editing**: Modify existing images with natural language instructions\n- **🔧 Image Restoration**: Restore and enhance old or damaged photos\n- **📁 Smart File Management**: User-friendly filenames with automatic duplicate prevention\n\n## 📋 Prerequisites\n\n1. **Gemini CLI** installed and configured\n2. **Node.js 20+** and npm\n3. **API Key**: Set one of these environment variables:\n   - `NANOBANANA_GEMINI_API_KEY` (recommended for Gemini API key users who\n     normally authenticate to Gemini CLI using the \"Login with Google\" option)\n   - `NANOBANANA_GOOGLE_API_KEY` (recommended for Vertex API key users who\n     normally authenticate to Gemini CLI using the \"Login with Google\" option)\n   - `GEMINI_API_KEY` (fallback)\n   - `GOOGLE_API_KEY` (fallback)\n\nFor authentication setup, see the [official Gemini CLI documentation](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/authentication.md).\n\n### Key Components\n\n- **`index.ts`**: MCP server using `@modelcontextprotocol/sdk` for professional protocol handling\n- **`imageGenerator.ts`**: Handles all Gemini API interactions and response processing\n- **`fileHandler.ts`**: Manages file I/O, smart filename generation, and file searching\n- **`types.ts`**: Shared TypeScript interfaces for type safety\n\n## 🍌 Model Selection\n\nThere are two different Nano Banana models supported by this extension:\n\n- `gemini-2.5-flash-image` (default)\n- `gemini-3-pro-image-preview` (Nano Banana Pro)\n\nThe `gemini-2.5-flash-image` model is the default model.\n\nTo use the new Gemini 3 Pro powered model set the `NANOBANANA_MODEL` environment variable to `gemini-3-pro-image-preview`.\n\n```bash\nexport NANOBANANA_MODEL=gemini-3-pro-image-preview\n```\n\n## 🚀 Installation\n\n### 1. Install Extension\n\nInstall the extension using the `gemini extensions install` command:\n\n```bash\ngemini extensions install https://github.com/gemini-cli-extensions/nanobanana\n```\n\n### 2. Activate\n\nRestart the Gemini CLI. The following commands will be available:\n\n- `/generate` - Single or multiple image generation with style/variation options\n- `/edit` - Image editing\n- `/restore` - Image restoration\n- `/icon` - Generate app icons, favicons, and UI elements in multiple sizes\n- `/pattern` - Generate seamless patterns and textures for backgrounds\n- `/story` - Generate sequential images that tell a visual story or process\n- `/diagram` - Generate technical diagrams, flowcharts, and architectural mockups\n- `/nanobanana` - Natural language interface\n\n## 💡 Usage\n\nThe extension provides multiple command options for different use cases:\n\n### 🎯 Specific Commands (Recommended)\n\n**Generate Images:**\n\n```bash\n# Single image\n/generate \"a watercolor painting of a fox in a snowy forest\"\n\n# Multiple variations with preview\n/generate \"sunset over mountains\" --count=3 --preview\n\n# Style variations\n/generate \"mountain landscape\" --styles=\"watercolor,oil-painting\" --count=4\n\n# Specific variations with auto-preview\n/generate \"coffee shop interior\" --variations=\"lighting,mood\" --preview\n```\n\n**Edit Images:**\n\n```bash\n/edit my_photo.png \"add sunglasses to the person\"\n/edit portrait.jpg \"change background to a beach scene\" --preview\n```\n\n**Restore Images:**\n\n```bash\n/restore old_family_photo.jpg \"remove scratches and improve clarity\"\n/restore damaged_photo.png \"enhance colors and fix tears\" --preview\n```\n\n**Generate Icons:**\n\n```bash\n# App icon in multiple sizes\n/icon \"coffee cup logo\" --sizes=\"64,128,256\" --type=\"app-icon\" --preview\n\n# Favicon set\n/icon \"company logo\" --type=\"favicon\" --sizes=\"16,32,64\"\n\n# UI elements\n/icon \"settings gear icon\" --type=\"ui-element\" --style=\"minimal\"\n```\n\n**Create Patterns:**\n\n```bash\n# Seamless pattern\n/pattern \"geometric triangles\" --type=\"seamless\" --style=\"geometric\" --preview\n\n# Background texture\n/pattern \"wood grain texture\" --type=\"texture\" --colors=\"mono\"\n\n# Wallpaper pattern\n/pattern \"floral design\" --type=\"wallpaper\" --density=\"sparse\"\n```\n\n**Generate Stories:**\n\n```bash\n# Visual story sequence\n/story \"a seed growing into a tree\" --steps=4 --type=\"process\" --preview\n\n# Step-by-step tutorial\n/story \"how to make coffee\" --steps=6 --type=\"tutorial\"\n\n# Timeline visualization\n/story \"evolution of smartphones\" --steps=5 --type=\"timeline\"\n```\n\n**Create Diagrams:**\n\n```bash\n# System flowchart\n/diagram \"user login process\" --type=\"flowchart\" --style=\"professional\" --preview\n\n# Architecture diagram\n/diagram \"microservices architecture\" --type=\"architecture\" --complexity=\"detailed\"\n\n# Database schema\n/diagram \"e-commerce database design\" --type=\"database\" --layout=\"hierarchical\"\n```\n\n### 🌟 Natural Language Command (Flexible)\n\n**Open-ended prompts:**\n\n```bash\n/nanobanana create a logo for my tech startup\n/nanobanana I need 5 different versions of a cat illustration in various art styles\n/nanobanana fix the lighting in sunset.jpg and make it more vibrant\n```\n\n## 🎨 Advanced Generation Options\n\nThe `/generate` command supports advanced options for creating multiple variations with different styles and parameters.\n\n### Generation Options\n\n**`--count=N`** - Number of variations (1-8, default: 1)\n**`--styles=\"style1,style2\"`** - Comma-separated artistic styles\n**`--variations=\"var1,var2\"`** - Specific variation types  \n**`--format=grid|separate`** - Output format (default: separate)\n**`--seed=123`** - Seed for reproducible variations\n**`--preview`** - Automatically open generated images in default viewer\n\n### Available Styles\n\n- `photorealistic` - Photographic quality images\n- `watercolor` - Watercolor painting style\n- `oil-painting` - Oil painting technique\n- `sketch` - Hand-drawn sketch style\n- `pixel-art` - Retro pixel art style\n- `anime` - Anime/manga art style\n- `vintage` - Vintage/retro aesthetic\n- `modern` - Contemporary/modern style\n- `abstract` - Abstract art style\n- `minimalist` - Clean, minimal design\n\n### Available Variations\n\n- `lighting` - Different lighting conditions (dramatic, soft)\n- `angle` - Various viewing angles (above, close-up)\n- `color-palette` - Different color schemes (warm, cool)\n- `composition` - Different layouts (centered, rule-of-thirds)\n- `mood` - Various emotional tones (cheerful, dramatic)\n- `season` - Different seasons (spring, winter)\n- `time-of-day` - Different times (sunrise, sunset)\n\n### Advanced Examples\n\n**Style Variations:**\n\n```bash\n/generate \"mountain landscape\" --styles=\"watercolor,oil-painting,sketch,photorealistic\"\n# Creates the same mountain scene in 4 different artistic styles\n```\n\n**Multiple Variations:**\n\n```bash\n/generate \"cozy coffee shop\" --variations=\"lighting,mood\" --count=4\n# Generates: dramatic lighting, soft lighting, cheerful mood, dramatic mood versions\n```\n\n**Combined Options:**\n\n```bash\n/generate \"friendly robot character\" --styles=\"anime,minimalist\" --variations=\"color-palette\"\n# Creates anime and minimalist versions with different color palettes\n```\n\n**Simple Multiple Generation:**\n\n```bash\n/generate \"tech startup logo\" --count=6\n# Generates 6 different interpretations of the same prompt\n```\n\n## 🎯 Icon Generation\n\nThe `/icon` command specializes in creating app icons, favicons, and UI elements with proper sizing and formatting.\n\n### Icon Options\n\n**`--sizes=\"16,32,64\"`** - Array of icon sizes in pixels (common: 16, 32, 64, 128, 256, 512, 1024)\n**`--type=\"app-icon|favicon|ui-element\"`** - Icon type (default: app-icon)\n**`--style=\"flat|skeuomorphic|minimal|modern\"`** - Visual style (default: modern)\n**`--format=\"png|jpeg\"`** - Output format (default: png)\n**`--background=\"transparent|white|black|color\"`** - Background type (default: transparent)\n**`--corners=\"rounded|sharp\"`** - Corner style for app icons (default: rounded)\n\n### Icon Examples\n\n```bash\n# Complete app icon set\n/icon \"productivity app with checklist\" --sizes=\"64,128,256,512\" --corners=\"rounded\"\n\n# Website favicon package\n/icon \"mountain logo\" --type=\"favicon\" --sizes=\"16,32,64\" --format=\"png\"\n\n# UI element set\n/icon \"notification bell\" --type=\"ui-element\" --style=\"flat\" --background=\"transparent\"\n```\n\n## 🎨 Pattern \u0026 Texture Generation\n\nThe `/pattern` command creates seamless patterns and textures perfect for backgrounds and design elements.\n\n### Pattern Options\n\n**`--size=\"256x256\"`** - Pattern tile size (common: 128x128, 256x256, 512x512)\n**`--type=\"seamless|texture|wallpaper\"`** - Pattern type (default: seamless)\n**`--style=\"geometric|organic|abstract|floral|tech\"`** - Pattern style (default: abstract)\n**`--density=\"sparse|medium|dense\"`** - Element density (default: medium)\n**`--colors=\"mono|duotone|colorful\"`** - Color scheme (default: colorful)\n**`--repeat=\"tile|mirror\"`** - Tiling method for seamless patterns (default: tile)\n\n### Pattern Examples\n\n```bash\n# Website background pattern\n/pattern \"subtle geometric hexagons\" --type=\"seamless\" --colors=\"duotone\" --density=\"sparse\"\n\n# Material texture\n/pattern \"brushed metal surface\" --type=\"texture\" --style=\"tech\" --colors=\"mono\"\n\n# Decorative wallpaper\n/pattern \"art deco design\" --type=\"wallpaper\" --style=\"geometric\" --size=\"512x512\"\n```\n\n## 📖 Visual Storytelling\n\nThe `/story` command generates sequential images that tell a visual story or demonstrate a step-by-step process.\n\n### Story Options\n\n**`--steps=N`** - Number of sequential images (2-8, default: 4)\n**`--type=\"story|process|tutorial|timeline\"`** - Sequence type (default: story)\n**`--style=\"consistent|evolving\"`** - Visual consistency across frames (default: consistent)\n**`--layout=\"separate|grid|comic\"`** - Output layout (default: separate)\n**`--transition=\"smooth|dramatic|fade\"`** - Transition style between steps (default: smooth)\n**`--format=\"storyboard|individual\"`** - Output format (default: individual)\n\n### Story Examples\n\n```bash\n# Product development process\n/story \"idea to launched product\" --steps=5 --type=\"process\" --style=\"consistent\"\n\n# Educational tutorial\n/story \"git workflow tutorial\" --steps=6 --type=\"tutorial\" --layout=\"comic\"\n\n# Brand evolution timeline\n/story \"company logo evolution\" --steps=4 --type=\"timeline\" --transition=\"smooth\"\n```\n\n## 📊 Technical Diagrams\n\nThe `/diagram` command generates professional technical diagrams, flowcharts, and architectural mockups from simple text descriptions.\n\n### Diagram Options\n\n**`--type=\"flowchart|architecture|network|database|wireframe|mindmap|sequence\"`** - Diagram type (default: flowchart)\n**`--style=\"professional|clean|hand-drawn|technical\"`** - Visual style (default: professional)\n**`--layout=\"horizontal|vertical|hierarchical|circular\"`** - Layout orientation (default: hierarchical)\n**`--complexity=\"simple|detailed|comprehensive\"`** - Level of detail (default: detailed)\n**`--colors=\"mono|accent|categorical\"`** - Color scheme (default: accent)\n**`--annotations=\"minimal|detailed\"`** - Label and annotation level (default: detailed)\n\n### Diagram Types \u0026 Use Cases\n\n- **flowchart**: Process flows, decision trees, workflows\n- **architecture**: System architecture, microservices, infrastructure\n- **network**: Network topology, server configurations\n- **database**: Database schemas, entity relationships\n- **wireframe**: UI/UX mockups, page layouts\n- **mindmap**: Concept maps, idea hierarchies\n- **sequence**: Sequence diagrams, API interactions\n\n### Diagram Examples\n\n```bash\n# Development workflow\n/diagram \"CI/CD pipeline with testing stages\" --type=\"flowchart\" --complexity=\"detailed\"\n\n# System design\n/diagram \"chat application architecture\" --type=\"architecture\" --style=\"technical\"\n\n# API documentation\n/diagram \"REST API authentication flow\" --type=\"sequence\" --layout=\"vertical\"\n\n# Database design\n/diagram \"social media database schema\" --type=\"database\" --annotations=\"detailed\"\n```\n\n## 📁 File Management\n\n### Smart Filename Generation\n\nImages are saved with user-friendly names based on your prompts:\n\n- `\"sunset over mountains\"` → `sunset_over_mountains.png`\n- `\"abstract art piece\"` → `abstract_art_piece.png`\n\n### Automatic Duplicate Prevention\n\nIf a file already exists, a counter is automatically added:\n\n- `sunset_over_mountains.png`\n- `sunset_over_mountains_1.png`\n- `sunset_over_mountains_2.png`\n\n### File Search Locations\n\nFor editing/restoration, the extension searches for input images in:\n\n1. Current working directory\n2. `./images/` subdirectory\n3. `./input/` subdirectory\n4. `./nanobanana-output/` subdirectory\n5. `~/Downloads/`\n6. `~/Desktop/`\n\n### Output Directory\n\nGenerated images are saved to `./nanobanana-output/` which is created automatically.\n\n## 🛠️ Development\n\n### Build Commands\n\n```bash\n# Build the MCP server\nnpm run build\n\n# Install MCP server dependencies\nnpm run install-deps\n\n# Development mode with file watching\nnpm run dev\n```\n\n### MCP Server Commands\n\n```bash\n# Build MCP server directly\ncd mcp-server \u0026\u0026 npm run build\n\n# Start server standalone (for testing)\ncd mcp-server \u0026\u0026 npm start\n\n# Development mode with TypeScript watching\ncd mcp-server \u0026\u0026 npm run dev\n```\n\n## 🔧 Technical Details\n\n### MCP Server Protocol\n\nThe extension uses the official Model Context Protocol (MCP) SDK for robust client-server communication:\n\n- **Protocol**: JSON-RPC over stdio\n- **SDK**: `@modelcontextprotocol/sdk`\n- **Tools**: `generate_image`, `edit_image`, `restore_image`\n\n### API Integration\n\n- **Model**: `gemini-2.5-flash-image`\n- **SDK**: `@google/genai`\n- **Response Handling**: Multiple fallback locations for image data detection\n\n### Error Handling\n\n- Comprehensive error messages with debugging information\n- Graceful fallbacks for API response parsing\n- File validation and search path reporting\n\n## 🐛 Troubleshooting\n\n### Common Issues\n\n1. **\"Command not recognized\"**: Ensure extension is in `~/.gemini/extensions/nanobanana-extension/` and Gemini CLI is restarted\n\n2. **\"No API key found\"**: Set `GEMINI_API_KEY` environment variable:\n\n   ```bash\n   export GEMINI_API_KEY=\"your-api-key-here\"\n   ```\n\n3. **\"Build failed\"**: Ensure Node.js 18+ is installed and run:\n\n   ```bash\n   npm run install-deps \u0026\u0026 npm run build\n   ```\n\n4. **\"Image not found\"**: Check that input files are in one of the searched directories (see File Search Locations above)\n\n### Debug Mode\n\nThe MCP server includes detailed debug logging that appears in the Gemini CLI console to help diagnose issues.\n\n## 📄 Legal\n\n- **License**: [Apache License 2.0](LICENSE)\n- **Security**: [Security Policy](SECURITY.md)\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes in the modular architecture\n4. Run `npm run build` to ensure compilation\n5. Test with the Gemini CLI\n6. Submit a pull request\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemini-cli-extensions%2Fnanobanana","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgemini-cli-extensions%2Fnanobanana","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgemini-cli-extensions%2Fnanobanana/lists"}