Skip to content
Back to search

nanobanana

> [!NOTE] > Nano Banana 2 (gemini-3.1-flash-image-preview) is now the default model (v1.0.11+)! > > You can still use the Pro model by setting the NANOBANANAMODEL environment variable to…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/gemini-cli-extensions--nanobanana/badge.svg)](/listings/gemini-cli-extensions--nanobanana)

HTML

<a href="/listings/gemini-cli-extensions--nanobanana"><img src="/api/listings/gemini-cli-extensions--nanobanana/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install Extension

Install the extension using the `gemini extensions install` command:

gemini extensions install https://github.com/gemini-cli-extensions/nanobanana

2. Activate

Restart the Gemini CLI. The following commands will be available:

- `/generate` - Single or multiple image generation with style/variation options - `/edit` - Image editing - `/restore` - Image restoration - `/icon` - Generate app icons, favicons, and UI elements in multiple sizes - `/pattern` - Generate seamless patterns and textures for backgrounds - `/story` - Generate sequential images that tell a visual story or process - `/diagram` - Generate technical diagrams, flowcharts, and architectural mockups - `/nanobanana` - Natural language interface

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 473 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. > [!NOTE]
  2. > Nano Banana 2 (`gemini-3.1-flash-image-preview`) is now the default model (v1.0.11+)!
  3. >
  4. > You can still use the Pro model by setting the `NANOBANANA_MODEL` environment variable to `gemini-3-pro-image-preview`.
  5. # Nano Banana - Gemini CLI Extension
  6. A professional Gemini CLI extension for generating and manipulating images using the Nano Banana models.
  7. ## ✨ Features
  8. - **🎨 Text-to-Image Generation**: Create stunning images from descriptive prompts
  9. - **✏️ Image Editing**: Modify existing images with natural language instructions
  10. - **🔧 Image Restoration**: Restore and enhance old or damaged photos
  11. - **📁 Smart File Management**: User-friendly filenames with automatic duplicate prevention
  12. ## 📋 Prerequisites
  13. 1. **Gemini CLI** installed and configured
  14. 2. **Node.js 20+** and npm
  15. 3. **API Key**: Set the `NANOBANANA_API_KEY` environment variable with your Gemini API key.
  16. Get one from [Google AI Studio](https://aistudio.google.com/apikey).
  17. For authentication setup, see the [official Gemini CLI documentation](https://geminicli.com/docs/get-started/authentication/).
  18. ### Key Components
  19. - **`index.ts`**: MCP server using `@modelcontextprotocol/sdk` for professional protocol handling
  20. - **`imageGenerator.ts`**: Handles all Gemini API interactions and response processing
  21. - **`fileHandler.ts`**: Manages file I/O, smart filename generation, and file searching
  22. - **`types.ts`**: Shared TypeScript interfaces for type safety
  23. ## 🍌 Model Selection
  24. The following Nano Banana models are supported:
  25. - `gemini-3.1-flash-image-preview` (Nano Banana 2 - **default**)
  26. - `gemini-3-pro-image-preview` (Nano Banana Pro)
  27. - `gemini-2.5-flash-image` (Nano Banana v1)
  28. The `gemini-3.1-flash-image-preview` model is the default. To use a different model, set the `NANOBANANA_MODEL` environment variable:
  29. ```bash
  30. # Example: Use Nano Banana Pro
  31. export NANOBANANA_MODEL=gemini-3-pro-image-preview
  32. # Example: Use Nano Banana v1
  33. export NANOBANANA_MODEL=gemini-2.5-flash-image
  34. ```
  35. ## 🚀 Installation
  36. ### 1. Install Extension
  37. Install the extension using the `gemini extensions install` command:
  38. ```bash
  39. gemini extensions install https://github.com/gemini-cli-extensions/nanobanana
  40. ```
  41. ### 2. Activate
  42. Restart the Gemini CLI. The following commands will be available:
  43. - `/generate` - Single or multiple image generation with style/variation options
  44. - `/edit` - Image editing
  45. - `/restore` - Image restoration
  46. - `/icon` - Generate app icons, favicons, and UI elements in multiple sizes
  47. - `/pattern` - Generate seamless patterns and textures for backgrounds
  48. - `/story` - Generate sequential images that tell a visual story or process
  49. - `/diagram` - Generate technical diagrams, flowcharts, and architectural mockups
  50. - `/nanobanana` - Natural language interface
  51. ## 💡 Usage
  52. The extension provides multiple command options for different use cases:
  53. ### 🎯 Specific Commands (Recommended)
  54. **Generate Images:**
  55. ```bash
  56. # Single image
  57. /generate "a watercolor painting of a fox in a snowy forest"
  58. # Multiple variations with preview
  59. /generate "sunset over mountains" --count=3 --preview
  60. # Style variations
  61. /generate "mountain landscape" --styles="watercolor,oil-painting" --count=4
  62. # Specific variations with auto-preview
  63. /generate "coffee shop interior" --variations="lighting,mood" --preview
  64. ```
  65. **Edit Images:**
  66. ```bash
  67. /edit my_photo.png "add sunglasses to the person"
  68. /edit portrait.jpg "change background to a beach scene" --preview
  69. ```
  70. **Restore Images:**
  71. ```bash
  72. /restore old_family_photo.jpg "remove scratches and improve clarity"
  73. /restore damaged_photo.png "enhance colors and fix tears" --preview
  74. ```
  75. **Generate Icons:**
  76. ```bash
  77. # App icon in multiple sizes
  78. /icon "coffee cup logo" --sizes="64,128,256" --type="app-icon" --preview
  79. # Favicon set
  80. /icon "company logo" --type="favicon" --sizes="16,32,64"
  81. # UI elements
  82. /icon "settings gear icon" --type="ui-element" --style="minimal"
  83. ```
  84. **Create Patterns:**
  85. ```bash
  86. # Seamless pattern
  87. /pattern "geometric triangles" --type="seamless" --style="geometric" --preview
  88. # Background texture
  89. /pattern "wood grain texture" --type="texture" --colors="mono"
  90. # Wallpaper pattern
  91. /pattern "floral design" --type="wallpaper" --density="sparse"
  92. ```
  93. **Generate Stories:**
  94. ```bash
  95. # Visual story sequence
  96. /story "a seed growing into a tree" --steps=4 --type="process" --preview
  97. # Step-by-step tutorial
  98. /story "how to make coffee" --steps=6 --type="tutorial"
  99. # Timeline visualization
  100. /story "evolution of smartphones" --steps=5 --type="timeline"
  101. ```
  102. **Create Diagrams:**
  103. ```bash
  104. # System flowchart
  105. /diagram "user login process" --type="flowchart" --style="professional" --preview
  106. # Architecture diagram
  107. /diagram "microservices architecture" --type="architecture" --complexity="detailed"
  108. # Database schema
  109. /diagram "e-commerce database design" --type="database" --layout="hierarchical"
  110. ```
  111. ### 🌟 Natural Language Command (Flexible)
  112. **Open-ended prompts:**
  113. ```bash
  114. /nanobanana create a logo for my tech startup
  115. /nanobanana I need 5 different versions of a cat illustration in various art styles
  116. /nanobanana fix the lighting in sunset.jpg and make it more vibrant
  117. ```
  118. ## 🎨 Advanced Generation Options
  119. The `/generate` command supports advanced options for creating multiple variations with different styles and parameters.
  120. ### Generation Options
  121. **`--count=N`** - Number of variations (1-8, default: 1)
  122. **`--styles="style1,style2"`** - Comma-separated artistic styles
  123. **`--variations="var1,var2"`** - Specific variation types
  124. **`--format=grid|separate`** - Output format (default: separate)
  125. **`--seed=123`** - Seed for reproducible variations
  126. **`--preview`** - Automatically open generated images in default viewer
  127. ### Available Styles
  128. - `photorealistic` - Photographic quality images
  129. - `watercolor` - Watercolor painting style
  130. - `oil-painting` - Oil painting technique
  131. - `sketch` - Hand-drawn sketch style
  132. - `pixel-art` - Retro pixel art style
  133. - `anime` - Anime/manga art style
  134. - `vintage` - Vintage/retro aesthetic
  135. - `modern` - Contemporary/modern style
  136. - `abstract` - Abstract art style
  137. - `minimalist` - Clean, minimal design
  138. ### Available Variations
  139. - `lighting` - Different lighting conditions (dramatic, soft)
  140. - `angle` - Various viewing angles (above, close-up)
  141. - `color-palette` - Different color schemes (warm, cool)
  142. - `composition` - Different layouts (centered, rule-of-thirds)
  143. - `mood` - Various emotional tones (cheerful, dramatic)
  144. - `season` - Different seasons (spring, winter)
  145. - `time-of-day` - Different times (sunrise, sunset)
  146. ### Advanced Examples
  147. **Style Variations:**
  148. ```bash
  149. /generate "mountain landscape" --styles="watercolor,oil-painting,sketch,photorealistic"
  150. # Creates the same mountain scene in 4 different artistic styles
  151. ```
  152. **Multiple Variations:**
  153. ```bash
  154. /generate "cozy coffee shop" --variations="lighting,mood" --count=4
  155. # Generates: dramatic lighting, soft lighting, cheerful mood, dramatic mood versions
  156. ```
  157. **Combined Options:**
  158. ```bash
  159. /generate "friendly robot character" --styles="anime,minimalist" --variations="color-palette"
  160. # Creates anime and minimalist versions with different color palettes
  161. ```
  162. **Simple Multiple Generation:**
  163. ```bash
  164. /generate "tech startup logo" --count=6
  165. # Generates 6 different interpretations of the same prompt
  166. ```
  167. ## 🎯 Icon Generation
  168. The `/icon` command specializes in creating app icons, favicons, and UI elements with proper sizing and formatting.
  169. ### Icon Options
  170. **`--sizes="16,32,64"`** - Array of icon sizes in pixels (common: 16, 32, 64, 128, 256, 512, 1024)
  171. **`--type="app-icon|favicon|ui-element"`** - Icon type (default: app-icon)
  172. **`--style="flat|skeuomorphic|minimal|modern"`** - Visual style (default: modern)
  173. **`--format="png|jpeg"`** - Output format (default: png)
  174. **`--background="transparent|white|black|color"`** - Background type (default: transparent)
  175. **`--corners="rounded|sharp"`** - Corner style for app icons (default: rounded)
  176. ### Icon Examples
  177. ```bash
  178. # Complete app icon set
  179. /icon "productivity app with checklist" --sizes="64,128,256,512" --corners="rounded"
  180. # Website favicon package
  181. /icon "mountain logo" --type="favicon" --sizes="16,32,64" --format="png"
  182. # UI element set
  183. /icon "notification bell" --type="ui-element" --style="flat" --background="transparent"
  184. ```
  185. ## 🎨 Pattern & Texture Generation
  186. The `/pattern` command creates seamless patterns and textures perfect for backgrounds and design elements.
  187. ### Pattern Options
  188. **`--size="256x256"`** - Pattern tile size (common: 128x128, 256x256, 512x512)
  189. **`--type="seamless|texture|wallpaper"`** - Pattern type (default: seamless)
  190. **`--style="geometric|organic|abstract|floral|tech"`** - Pattern style (default: abstract)
  191. **`--density="sparse|medium|dense"`** - Element density (default: medium)
  192. **`--colors="mono|duotone|colorful"`** - Color scheme (default: colorful)
  193. **`--repeat="tile|mirror"`** - Tiling method for seamless patterns (default: tile)
  194. ### Pattern Examples
  195. ```bash
  196. # Website background pattern
  197. /pattern "subtle geometric hexagons" --type="seamless" --colors="duotone" --density="sparse"
  198. # Material texture
  199. /pattern "brushed metal surface" --type="texture" --style="tech" --colors="mono"
  200. # Decorative wallpaper
  201. /pattern "art deco design" --type="wallpaper" --style="geometric" --size="512x512"
  202. ```
  203. ## 📖 Visual Storytelling
  204. The `/story` command generates sequential images that tell a visual story or demonstrate a step-by-step process.
  205. ### Story Options
  206. **`--steps=N`** - Number of sequential images (2-8, default: 4)
  207. **`--type="story|process|tutorial|timeline"`** - Sequence type (default: story)
  208. **`--style="consistent|evolving"`** - Visual consistency across frames (default: consistent)
  209. **`--layout="separate|grid|comic"`** - Output layout (default: separate)
  210. **`--transition="smooth|dramatic|fade"`** - Transition style between steps (default: smooth)
  211. **`--format="storyboard|individual"`** - Output format (default: individual)
  212. ### Story Examples
  213. ```bash
  214. # Product development process
  215. /story "idea to launched product" --steps=5 --type="process" --style="consistent"
  216. # Educational tutorial
  217. /story "git workflow tutorial" --steps=6 --type="tutorial" --layout="comic"
  218. # Brand evolution timeline
  219. /story "company logo evolution" --steps=4 --type="timeline" --transition="smooth"
  220. ```
  221. ## 📊 Technical Diagrams
  222. The `/diagram` command generates professional technical diagrams, flowcharts, and architectural mockups from simple text descriptions.
  223. ### Diagram Options
  224. **`--type="flowchart|architecture|network|database|wireframe|mindmap|sequence"`** - Diagram type (default: flowchart)
  225. **`--style="professional|clean|hand-drawn|technical"`** - Visual style (default: professional)
  226. **`--layout="horizontal|vertical|hierarchical|circular"`** - Layout orientation (default: hierarchical)
  227. **`--complexity="simple|detailed|comprehensive"`** - Level of detail (default: detailed)
  228. **`--colors="mono|accent|categorical"`** - Color scheme (default: accent)
  229. **`--annotations="minimal|detailed"`** - Label and annotation level (default: detailed)
  230. ### Diagram Types & Use Cases
  231. - **flowchart**: Process flows, decision trees, workflows
  232. - **architecture**: System architecture, microservices, infrastructure
  233. - **network**: Network topology, server configurations
  234. - **database**: Database schemas, entity relationships
  235. - **wireframe**: UI/UX mockups, page layouts
  236. - **mindmap**: Concept maps, idea hierarchies
  237. - **sequence**: Sequence diagrams, API interactions
  238. ### Diagram Examples
  239. ```bash
  240. # Development workflow
  241. /diagram "CI/CD pipeline with testing stages" --type="flowchart" --complexity="detailed"
  242. # System design
  243. /diagram "chat application architecture" --type="architecture" --style="technical"
  244. # API documentation
  245. /diagram "REST API authentication flow" --type="sequence" --layout="vertical"
  246. # Database design
  247. /diagram "social media database schema" --type="database" --annotations="detailed"
  248. ```
  249. ## 📁 File Management
  250. ### Smart Filename Generation
  251. Images are saved with user-friendly names based on your prompts:
  252. - `"sunset over mountains"` → `sunset_over_mountains.png`
  253. - `"abstract art piece"` → `abstract_art_piece.png`
  254. ### Automatic Duplicate Prevention
  255. If a file already exists, a counter is automatically added:
  256. - `sunset_over_mountains.png`
  257. - `sunset_over_mountains_1.png`
  258. - `sunset_over_mountains_2.png`
  259. ### File Search Locations
  260. For editing/restoration, the extension searches for input images in:
  261. 1. Current working directory
  262. 2. `./images/` subdirectory
  263. 3. `./input/` subdirectory
  264. 4. `./nanobanana-output/` subdirectory
  265. 5. `~/Downloads/`
  266. 6. `~/Desktop/`
  267. ### Output Directory
  268. Generated images are saved to `./nanobanana-output/` which is created automatically.
  269. ## 🛠️ Development
  270. ### Build Commands
  271. ```bash
  272. # Build the MCP server
  273. npm run build
  274. # Install MCP server dependencies
  275. npm run install-deps
  276. # Development mode with file watching
  277. npm run dev
  278. ```
  279. ### MCP Server Commands
  280. ```bash
  281. # Build MCP server directly
  282. cd mcp-server && npm run build
  283. # Start server standalone (for testing)
  284. cd mcp-server && npm start
  285. # Development mode with TypeScript watching
  286. cd mcp-server && npm run dev
  287. ```
  288. ## 🔧 Technical Details
  289. ### MCP Server Protocol
  290. The extension uses the official Model Context Protocol (MCP) SDK for robust client-server communication:
  291. - **Protocol**: JSON-RPC over stdio
  292. - **SDK**: `@modelcontextprotocol/sdk`
  293. - **Tools**: `generate_image`, `edit_image`, `restore_image`
  294. ### API Integration
  295. - **Model**: `gemini-3.1-flash-image-preview`
  296. - **SDK**: `@google/genai`
  297. - **Response Handling**: Multiple fallback locations for image data detection
  298. ### Error Handling
  299. - Comprehensive error messages with debugging information
  300. - Graceful fallbacks for API response parsing
  301. - File validation and search path reporting
  302. ## 🐛 Troubleshooting
  303. ### Common Issues
  304. 1. **"Command not recognized"**: Ensure extension is in `~/.gemini/extensions/nanobanana-extension/` and Gemini CLI is restarted
  305. 2. **"No API key found"**: Set `NANOBANANA_API_KEY` environment variable:
  306. ```bash
  307. export NANOBANANA_API_KEY="your-api-key-here"
  308. ```
  309. 3. **"Build failed"**: Ensure Node.js 18+ is installed and run:
  310. ```bash
  311. npm run install-deps && npm run build
  312. ```
  313. 4. **"Image not found"**: Check that input files are in one of the searched directories (see File Search Locations above)
  314. ### Debug Mode
  315. The MCP server includes detailed debug logging that appears in the Gemini CLI console to help diagnose issues.
  316. ## 📄 Legal
  317. - **License**: [Apache License 2.0](LICENSE)
  318. - **Security**: [Security Policy](SECURITY.md)
  319. ## 🤝 Contributing
  320. 1. Fork the repository
  321. 2. Create a feature branch
  322. 3. Make your changes in the modular architecture
  323. 4. Run `npm run build` to ensure compilation
  324. 5. Test with the Gemini CLI
  325. 6. Submit a pull request

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.