banana-claws

banana-claws

banana-claws is a public OpenClaw skill and script toolkit for OpenRouter image generation, designed for both autonomous agents and human builders. It supports fast single-image generation, queue-first batch workflows, and machine-readable result artifacts so orchestration systems can acknowledge quickly, process in background, and return consolidated attached outputs.

Fast install (copy/paste for agents)

If you are instructing another OpenClaw agent, use this instruction block verbatim:

Install the OpenClaw skill `banana-claws` from:
https://github.com/ironystock/banana-claws

Steps:
1) Clone repo
2) Copy `skill/` contents into ~/.openclaw/workspace/skills/banana-claws/
3) Ensure OPENROUTER_API_KEY is set in runtime env
4) Restart/reload agent runtime so skills are re-indexed
5) Verify skill discovery, then run a queue-mode smoke test with attached outputs

Recommended smoke-test prompt for the agent:

Use banana-claws to generate 2 variants of "neon cyberpunk crab logo" in queue mode.
Acknowledge queued immediately, then return a consolidated completion status and attach outputs.

Best install path for external agents

• Preferred: install from GitHub repo source (skill/ directory), not from release zip.
• Why: agents reliably understand repo URL + folder copy instructions; zip handling varies across runtimes/tools.
• If using release zip anyway: extract it first, then manually copy skill/ into the OpenClaw skills directory.

What this includes

• skill/SKILL.md — skill instructions + queue/response pattern
• skill/scripts/generate_image.py — single image generation
• skill/scripts/enqueue_image_job.py — enqueue one job
• skill/scripts/enqueue_variants.py — enqueue N variants with consistent naming
• skill/scripts/run_image_queue.py — drain queue and write success/failure job records
• skill/scripts/queue_and_return.py — enqueue + immediate return + background worker handoff (with worker cap + orphan cleanup)
• skill/scripts/summarize_request.py — summarize request completion/attachments for push reporting
• skill/scripts/preflight_check.py — first-run diagnostics + copy/paste fixups

Requirements

• Python 3.9+
• OPENROUTER_API_KEY environment variable
• Python package requests
• Internet access to https://openrouter.ai

Install Python dependency:

python3 -m pip install requests
# or: pip install -r requirements.txt

Quick start

0) First-time setup check (FTUX)

python3 skill/scripts/preflight_check.py
python3 skill/scripts/preflight_check.py --json

Generate one image:

python3 skill/scripts/generate_image.py \
  --prompt "A cinematic portrait of a cyberpunk crab" \
  --model google/gemini-3.1-flash-image-preview \
  --image-size low \
  --clarify-hints \
  --out ./generated/cyber-crab.png

Queue 4 variants with async handoff (recommended):

python3 skill/scripts/queue_and_return.py \
  --prompt "YouTube thumbnail: Snowcrab AI — Queue Mode Test, neon cyberpunk" \
  --count 4 \
  --baseline-image ./generated/base-thumbnail.png \
  --baseline-source-kind explicit_path_or_url \
  --confirm-external-upload \
  --variation-strength low \
  --lock-palette \
  --lock-composition \
  --must-keep "title placement" \
  --must-keep "logo region" \
  --image-size low \
  --clarify-hints \
  --out-dir ./generated \
  --prefix snowcrab-queue-test \
  --request-id "discord-<message-id>" \
  --queue-dir ./generated/imagegen-queue

Manual worker drain (worker context only):

python3 skill/scripts/run_image_queue.py --queue-dir ./generated/imagegen-queue --request-id "discord-<message-id>" --handoff-mode background

Background hardening knobs:

python3 skill/scripts/queue_and_return.py ... \
  --max-background-workers 2 \
  --orphan-timeout-sec 1800

Iteration vs final quality

• Use --image-size low for fast/low-cost exploratory passes.
• Use --image-size medium or --image-size high for final-quality outputs.

Prompt clarity hints

• Add --clarify-hints to print actionable prompt-quality hints (style, size/format, exact text, composition constraints).
• Add --strict-clarify to fail early when prompt appears underspecified.

Provider data handling note (deny-by-default)

• Requests are sent to OpenRouter for generation/edit processing.
• When using baseline/edit flags (for example --baseline-image), that input image is transmitted to the provider.
• Local baseline uploads are blocked unless --confirm-external-upload is explicitly set.
• Only use images that the user has explicitly approved for external processing.

Baseline-locked variants (on-rails)

• Use --baseline-image for true image-to-image varianting.
• Resolve baseline deterministically in caller: current-message attachment > replied-message attachment > clarification request.
• Record baseline provenance with --baseline-source-kind current_attachment|reply_attachment|explicit_path_or_url.
• Edit/variant intent prompts fail fast when no baseline is provided (override only with --allow-no-baseline-on-edit-intent).
• Default rails are auto-applied when baseline is present: variation-strength=low, lock-palette, lock-composition.
• Use --variation-strength low|medium|high to control divergence from baseline.
• Use repeatable --must-keep constraints for consistency.
• enqueue_variants.py writes a <prefix>-manifest.json file for reproducible reruns/debugging.

Queue/result contract

• Pending jobs: generated/imagegen-queue/pending/*.json
• Success records: generated/imagegen-queue/results/*.json
• Failure records: generated/imagegen-queue/failed/*.json

Each result/failed record includes request_id, out, exit_code, stdout/stderr, and persisted provider metadata (including top-level generation id and provider response payload/path) for orchestration and edit/debug workflows.

Drift diagnostics are also persisted per job (edit_intent_detected, baseline_applied, baseline_source, baseline_source_kind, baseline_resolution_policy, rails_applied, clarify_hints) so agents can prove whether baseline rails were actually used.

Messaging behavior note:

• For multi-image requests, send an immediate queued ack, then a consolidated completion status update.
• Do not run queue drain in the same foreground turn for multi-image requests.
• Always attach generated files (never path-only).
• If your message adapter only supports one attachment per send, post file attachments as replies under the completion status message.

Install & use in OpenClaw (GitHub)

1) Clone the repo

git clone https://github.com/ironystock/banana-claws.git
cd banana-claws

2) Place the skill where OpenClaw can discover it

Copy the skill/ folder into your OpenClaw skills workspace (example shown below):

mkdir -p ~/.openclaw/workspace/skills/banana-claws
cp -R skill/* ~/.openclaw/workspace/skills/banana-claws/

3) Set required environment variable

export OPENROUTER_API_KEY="your_openrouter_api_key"

4) Refresh/restart agent runtime so skills are re-indexed

If the running agent session does not see the skill yet, restart/reload your OpenClaw runtime/session and verify the new skill is discoverable.

5) Prompt examples that should trigger this