Bananahub

BananaHub

Generate or edit images from non-English or mixed-language requests inside one /bananahub workflow. GPT Image 2 through an OpenAI-compatible image endpoint is the default provider path; user-configured Gemini/Nano Banana, OpenAI official, Vertex, chat-compatible paths, and Codex/host-native image tools are preserved. BananaHub keeps prompt optimization, conservative enhancement, model fallback, image editing, template use, and BananaHub discovery in a single skill instead of splitting them across separate installs.

When BananaHub is loaded implicitly for a generic agent image request, act as a lightweight optimization layer first. Do not silently take over generation: ask whether the user wants BananaHub to optimize the prompt before the image tool runs, then respect the answer.

Quick Start

• Install via Open Agent Skills: npx skills add https://github.com/bananahub-ai/bananahub-skill --skill bananahub
• Install in Claude Code directly: claude skill install https://github.com/bananahub-ai/bananahub-skill
• Run setup once: /bananahub init
• Test a host-native image tool such as Codex built-in image generation: /bananahub test-host-imagegen
• Generate from a natural-language request: /bananahub 一只橘猫趴在键盘上打盹
• Edit an image: /bananahub edit 把背景换成海滩 --input photo.png
• Discover a reusable template: /bananahub discover 代码库讲解图
• Capture the current image iteration as a workflow template: /bananahub capture-workflow

Key Paths

• Generation script: {baseDir}/scripts/bananahub.py
• Provider adapters: {baseDir}/scripts/providers/ — Gemini, OpenAI Images, and chat/completions-compatible runtime adapters
• Runtime config module: {baseDir}/scripts/runtime_config.py — provider constants, aliases, transport defaults, config keys, and endpoint normalization
• Config store module: {baseDir}/scripts/config_store.py — config loading, profile merge, validation, provider override, and serialization helpers
• Prompt optimization rules: references/prompt-guide.md — read during Phase 1 (base optimization)
• Enhancement profiles: references/profiles/{name}.md — read during Phase 3 (on-demand)
• Official references: references/official-sources.md — authoritative source URLs, core example library
• Capability registry: references/capability-registry.md — provider/model feature routing and fallback policy
• Model registry: references/model-registry.json — canonical model ids, aliases, defaults, and provider families
• Provider guides: references/providers/{provider}.md — lazy-loaded model-family prompt and runtime rules
• Template system: references/template-system.md — read when handling templates/use/create-template commands
• Hub discovery guide: references/hub-discovery.md — read when handling discover or when local template matching is weak
• Template files: {baseDir}/references/templates/<id>/template.md (built-in) + ~/.config/bananahub/templates/<id>/template.md (user-installed)
• Telemetry helper: python3 {baseDir}/scripts/bananahub.py telemetry ... — use for built-in/installed template adoption events
• Telemetry state: ~/.config/bananahub/telemetry.json — stores the local anonymous usage id
• Init guide: references/init-guide.md — read when handling init command
• Optimization pipeline: references/optimization-pipeline.md — read when optimizing prompts
• Template format spec: references/template-format-spec.md — detailed field definitions, repo structure, sample requirements
• Template validator: python3 {baseDir}/scripts/validate_templates.py — validates bundled/user template metadata for schema v1/v2 compatibility
• Mode detector: python3 {baseDir}/scripts/bananahub.py check-mode — reports provider-backed / host-native / prompt-only execution mode and capability layer boundaries
• Host-native image tool test: /bananahub test-host-imagegen or /bananahub test-codex-imagegen — skill-layer command; call the host/Codex built-in image generation tool with the validation prompt below
• Prompt archive: current working directory bananahub-prompts/ when --save-prompt, --prompt-output, or BANANAHUB_SAVE_PROMPTS=1 is used
• API config (priority high→low):
  1. --config <file> CLI flag
  2. Selected skill profile in ~/.config/bananahub/config.json
  3. Environment variables fill missing fields by default (OPENAI_API_KEY, OPENAI_BASE_URL, GOOGLE_API_KEY, GEMINI_API_KEY, BANANAHUB_PROVIDER, BANANAHUB_AUTH_MODE, BANANAHUB_MODEL, GOOGLE_GEMINI_BASE_URL, GEMINI_BASE_URL, BANANAHUB_BASE_URL, GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)
     • Use BANANAHUB_PROFILE=<name> to select another persisted profile
     • Set BANANAHUB_ENV_OVERRIDE=1 only when environment variables should temporarily override profile fields
  4. Skill config examples:
     • {"provider": "google-ai-studio", "api_key": "...", "model": "gemini-3-pro-image-preview"}
     • {"provider": "gemini-compatible", "api_key": "...", "base_url": "https://..."}
     • {"provider": "openai", "openai_api_key": "...", "model": "gpt-image-2"}
     • {"provider": "openai-compatible", "openai_api_key": "...", "openai_base_url": "https://...", "model": "gpt-image-2"}
     • {"provider": "chatgpt-compatible", "chatgpt_api_key": "...", "chatgpt_base_url": "https://...", "model": "gpt-5.4"}
     • multi-profile: {"default_profile":"gpt","profiles":{"gpt":{"provider":"openai-compatible","openai_api_key":"...","openai_base_url":"https://...","model":"gpt-image-2"},"nano":{"provider":"google-ai-studio","api_key":"..."}}}
     • {"provider": "vertex-ai", "auth_mode": "adc", "project": "...", "location": "global"}
  5. Persistent config helpers:
     • python3 {baseDir}/scripts/bananahub.py config show
     • python3 {baseDir}/scripts/bananahub.py config doctor --json
     • python3 {baseDir}/scripts/bananahub.py config quickset --provider openai-compatible --profile gpt --default-profile --base-url https://your-openai-compatible-endpoint --api-key <key> --model gpt-image-2
     • python3 {baseDir}/scripts/bananahub.py config quickset --provider openai-compatible --profile gpt --default-profile --base-url https://your-openai-compatible-endpoint --api-key-stdin --model gpt-image-2
     • python3 {baseDir}/scripts/bananahub.py config quickset --provider openai --profile gpt --default-profile --api-key <key> --model gpt-image-2
     • python3 {baseDir}/scripts/bananahub.py config quickset --provider google-ai-studio --profile nano --default-profile --api-key <key> --model gemini-3-pro-image-preview
     • python3 {baseDir}/scripts/bananahub.py config quickset --provider vertex-ai --profile vertex --default-profile --auth-mode adc --project <gcp-project> --location global
     • python3 {baseDir}/scripts/bananahub.py init --wizard (human-terminal fallback only)
     • python3 {baseDir}/scripts/bananahub.py config set --clear-base-url
• Output directory: current working directory (where the skill is invoked)

First-Run Detection

Before executing any command other than help, check if the environment is ready:

1. Run python3 {baseDir}/scripts/bananahub.py config doctor --json when setup status is unclear.
2. If status is needs_setup, read references/init-guide.md, ask only for missing provider-required fields, then persist them with the matching config quickset command.
3. Direct API-key entry is allowed when the user chooses it or already pasted a key. Write it with config quickset --api-key-stdin and do not echo it back.
4. If the user does not want secrets in chat, give them the config quickset command with <key> placeholders for their local terminal.
5. If config exists but generation fails with auth/dependency errors → suggest config doctor --json.
6. Persist new config into ~/.config/bananahub/config.json, preferably as a named profile (gpt, nano, vertex, or chat).
7. Treat init --wizard as a human-terminal fallback only; do not assume agents can run interactive prompts.
8. Treat openai-compatible + gpt-image-2 as the default setup path. If the user already configured a provider/profile/model, preserve it and route within that provider.
9. Before asking for a provider API key, check whether the current client exposes a host-native image generation tool. In Codex, OAuth sessions and some API logins expose a built-in image tool; if available, offer it as a no-local-AK image channel and optionally run /bananahub test-host-imagegen.
10. Supported runtime providers:

• google-ai-studio: generate / edit / models / init
• gemini-compatible: generate / edit / models / init
• vertex-ai: generate / edit / models / init
• openai: OpenAI-native GPT Image generate / edit / models / init
• openai-compatible: OpenAI-style Images API generate / edit / models / init, capability-dependent
• chatgpt-compatible: chat/completions endpoint that returns images inside assistant replies

11. openai-compatible is not the same as OpenAI-native GPT Image. The runtime attempts standard Images API generation/editing, but exact support still depends on the gateway.
12. Endpoint normalization rules:

• gemini-compatible: if the user pastes a URL ending in /v1beta, keep it conceptually but normalize the trailing version during runtime so it is not duplicated
• openai-compatible: if the user pastes a bare host, the runtime may append /v1; for Google's official endpoint, resolve it to /v1beta/openai

Runtime Mode Layers

Run python3 {baseDir}/scripts/bananahub.py check-mode --pretty when the execution path is unclear. BananaHub has three execution modes:

Capability ownership is layered:

• Cross-model skill layer: prompt optimization, translation policy, conservative enhancement, --direct, --raw, prompt archiving, template discovery/activation, host-native delegation, and prompt-only advisory output.
• Template layer: matching and activation are common, but provider/model compatibility, prompt variants, tested quality, and samples belong to template metadata.
• Provider/model layer: image edit, mask edit, multi-reference, exact size, native quality, transparent background, output format/compression, and fallback are not universal; route them through references/capability-registry.md, references/model-registry.json, and provider adapters.

Host-Native Codex Image Tool

Treat Codex built-in image generation as a host-native channel, not as a persisted provider. It is useful when the user is authenticated through Codex OAuth or another host/API login that exposes an image tool and does not want to enter a separate BananaHub API key.

• Offer this channel during init when the current agent visibly has an image generation tool.
• To verify it, run /bananahub test-host-imagegen or /bananahub test-codex-imagegen: optimize no extra provider config, call the host image generation tool directly, and report whether an image file was produced.
• Validation prompt:

  Create a compact BananaHub channel validation image: a clean workflow card connected to a built-in image generation tool node, with a green check indicator. Include only the exact label "Codex Image Tool OK". Crisp modern product illustration, high readability, no logos, no watermark, no extra text.

• After a successful test, treat the current session as host-native. For CLI-only diagnostics, run python3 {baseDir}/scripts/bananahub.py check-mode --host-imagegen --pretty or set BANANAHUB_HOST_IMAGEGEN=1.
• Do not promise provider-native controls on this path. Exact pixel size, mask editing, native quality, output format, compression, transparent background, and multi-reference limits depend on the host tool surface.
• If a generated image is meant for the current project, move or copy the final asset from the host tool's default output location into the workspace before referencing it.

If a feature changes request payload shape, file validation, cost, policy behavior, or output parsing, do not treat it as cross-model even if several providers happen to support similar wording.

Agent operating principle: do not ask the human to make choices the agent can resolve from diagnosis, config, templates, or file paths. Ask only for secrets, provider/channel selection when unknown, paid generation consent, or genuinely creative direction.

Implicit Image Request Flow

This flow applies when BananaHub is loaded by a generic agent image request rather than an explicit /bananahub command.

1. Detect the user's intent:
   • image generation: "生成图片", "画一个", "create an image", "make a poster", "generate a logo", etc.
   • image editing: "改这张图", "replace the background", "edit this image", etc.
2. If the user explicitly asks to skip optimization, says "直接生成/直接画/raw/no optimization", or the request is already a highly structured final prompt, do not interrupt. Use the current image channel directly.
3. Otherwise ask one short confirmation before generation:

   要不要我先用 BananaHub 优化一下 prompt，再用当前可用的生图通道生成？我会保留你的原意，只增强结构、约束和模型适配。

   In English sessions:

   Do you want BananaHub to optimize the prompt before I generate it? I will preserve your intent and only tighten structure, constraints, and model fit.

4. If the user agrees, run the normal BananaHub optimization pipeline, suggest a matching local template only when there is a clear fit, then generate through the active provider or host-native image tool.
5. If the user declines, do not use BananaHub optimization for that request. Hand the original request to the current image generation tool.
6. If the request includes exact text, brand constraints, a reference image, editing boundaries, a workflow/template need, or a deliverable that benefits from prompt archiving, briefly recommend optimization but still wait for confirmation unless the user invoked /bananahub explicitly.