gfclaw 2.0.0

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "gfclaw",
+  "version": "2.0.0",
+  "description": "Add selfie superpowers to your OpenClaw agent using Google Gemini image editing",
+  "bin": {
+    "gfclaw": "./bin/cli.js"
+  },
+  "files": [
+    "bin/",
+    "skill/",
+    "templates/"
+  ],
+  "keywords": [
+    "openclaw",
+    "gemini",
+    "google",
+    "image-editing",
+    "selfie",
+    "ai-agent",
+    "image-generation",
+    "messaging",
+    "telegram",
+    "discord"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/SumeLabs/gfclaw"
+  },
+  "homepage": "https://github.com/SumeLabs/gfclaw#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {}
+}

package/skill/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: gfclaw-selfie
+description: Generate and send GFClaw selfies using Google Gemini image editing and OpenClaw messaging
+allowed-tools: Bash(gfclaw-selfie:*) Bash(openclaw:*) Bash(curl:*) Bash(python3:*) Bash(bash:*) Read Write
+---
+
+# GFClaw Selfie
+
+Generate selfies of yourself and send them to users via messaging channels.
+
+## How To Use (IMPORTANT — ALWAYS USE THE SCRIPT)
+
+**Run the complete script. Do NOT manually call curl or Gemini API.**
+
+```bash
+bash ~/.openclaw/skills/gfclaw-selfie/scripts/gfclaw-selfie.sh "<user_context>" "<channel>" [mode] [caption]
+```
+
+The script handles everything: image generation, saving, and sending.
+
+### Arguments
+
+| Argument | Required | Description | Example |
+|----------|----------|-------------|---------|
+| `user_context` | Yes | What to show (outfit, location, activity) | `"wearing a hoodie in a coffee shop"` |
+| `channel` | Yes | Target messaging channel | `"tg:401471440"` |
+| `mode` | No | `mirror` (full-body) or `direct` (close-up). Default: auto-detect | `mirror` |
+| `caption` | No | Message text sent with the image | `"coffee shop vibes ☕"` |
+
+### Examples
+
+```bash
+# Mirror selfie (full-body, outfit focus)
+bash ~/.openclaw/skills/gfclaw-selfie/scripts/gfclaw-selfie.sh "wearing a hoodie" "tg:401471440" mirror "cozy vibes 🤍"
+
+# Direct selfie (close-up, location focus)
+bash ~/.openclaw/skills/gfclaw-selfie/scripts/gfclaw-selfie.sh "a cozy cafe with warm lighting" "tg:401471440" direct "☕"
+
+# Auto-detect mode
+bash ~/.openclaw/skills/gfclaw-selfie/scripts/gfclaw-selfie.sh "wearing a santa hat at a christmas market" "tg:401471440"
+```
+
+## When to Use
+
+- User says "send a pic", "send me a selfie", "send a photo"
+- User asks "what are you doing?", "where are you?"
+- User requests specific appearances: "send a pic wearing...", "show me you at..."
+
+## Mode Selection
+
+| Keywords in Request | Mode |
+|---------------------|------|
+| outfit, wearing, clothes, dress, suit, fashion, full-body | `mirror` |
+| cafe, restaurant, beach, park, city, close-up, portrait | `direct` |
+
+## Channel Formats
+
+| Platform | Format | Example |
+|----------|--------|---------|
+| Telegram | `tg:<chat_id>` | `tg:401471440` |
+| Discord | `#channel` or ID | `#general` |
+| WhatsApp | `wa:<phone>` | `wa:1234567890` |
+
+## Technical Details
+
+- Images are generated via Google Gemini (`gemini-2.5-flash-image`)
+- Default reference image is at `~/.openclaw/skills/gfclaw-selfie/assets/gfclaw.png`
+- Custom reference image (from onboarding): agent sets `GFCLAW_REFERENCE_IMAGE` env var pointing to `my-reference.png` in workspace
+- Personality flavor: agent sets `GFCLAW_PERSONALITY` env var with user's personality preference (woven into Gemini prompt)
+- Output saved to `~/.openclaw/workspace/.selfie-output/` (required for workspace file access)
+- Images are auto-deleted after sending (no disk waste)
+
+## Helper Scripts
+
+### save-reference.sh
+Decodes a base64-encoded image file into a proper image. Used during onboarding when the user sends a reference photo.
+```bash
+bash ~/.openclaw/skills/gfclaw-selfie/scripts/save-reference.sh <base64_file> <output_path>
+```
+
+## Important Notes
+
+- **Do NOT save images to /tmp** — the message tool cannot access files outside the workspace
+- **Do NOT manually call curl or the Gemini API** — the script handles everything
+- **Do NOT try to read files outside the agent workspace** — use the script path directly

package/skill/scripts/gfclaw-selfie.sh

@@ -0,0 +1,218 @@
+#!/bin/bash
+# gfclaw-selfie.sh
+# Edit GFClaw's reference image with Gemini and send selfies via OpenClaw
+#
+# Usage: ./gfclaw-selfie.sh "<user_context>" "<channel>" ["<mode>"] ["<caption>"]
+#
+# Environment variables required:
+#   GEMINI_API_KEY - Your Google Gemini API key
+#
+# Example:
+#   GEMINI_API_KEY=your_key ./gfclaw-selfie.sh "wearing a santa hat" "tg:401471440" mirror "Merry Christmas!"
+
+set -euo pipefail
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+log_info() {
+    echo -e "${GREEN}[INFO]${NC} $1"
+}
+
+log_warn() {
+    echo -e "${YELLOW}[WARN]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+# Check required environment variables
+if [ -z "${GEMINI_API_KEY:-}" ]; then
+    log_error "GEMINI_API_KEY environment variable not set"
+    echo "Get your API key from: https://aistudio.google.com/apikey"
+    exit 1
+fi
+
+# Check for jq
+if ! command -v jq &> /dev/null; then
+    log_error "jq is required but not installed"
+    echo "Install with: apt install jq (Linux) or brew install jq (macOS)"
+    exit 1
+fi
+
+# Check for python3 (needed for base64 JSON payload construction)
+if ! command -v python3 &> /dev/null; then
+    log_error "python3 is required but not installed"
+    exit 1
+fi
+
+# Check for openclaw
+if ! command -v openclaw &> /dev/null; then
+    log_warn "openclaw CLI not found - will attempt direct API call"
+    USE_CLI=false
+else
+    USE_CLI=true
+fi
+
+# Reference image: check for custom (user-provided via onboarding), then fall back to default
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+DEFAULT_REFERENCE="${SCRIPT_DIR}/../assets/gfclaw.png"
+
+if [ -n "${GFCLAW_REFERENCE_IMAGE:-}" ] && [ -f "$GFCLAW_REFERENCE_IMAGE" ]; then
+    REFERENCE_IMAGE="$GFCLAW_REFERENCE_IMAGE"
+    log_info "Using custom reference image: $REFERENCE_IMAGE"
+else
+    REFERENCE_IMAGE="$DEFAULT_REFERENCE"
+fi
+
+if [ ! -f "$REFERENCE_IMAGE" ]; then
+    log_error "Reference image not found: $REFERENCE_IMAGE"
+    exit 1
+fi
+
+# Parse arguments
+USER_CONTEXT="${1:-}"
+CHANNEL="${2:-}"
+MODE="${3:-auto}"
+CAPTION="${4:-}"
+
+if [ -z "$USER_CONTEXT" ] || [ -z "$CHANNEL" ]; then
+    echo "Usage: $0 <user_context> <channel> [mode] [caption]"
+    echo ""
+    echo "Arguments:"
+    echo "  user_context  - What the person should be doing/wearing/where (required)"
+    echo "  channel       - Target channel (required) e.g., tg:401471440, #general"
+    echo "  mode          - Selfie mode: mirror, direct, auto (default: auto)"
+    echo "  caption       - Message caption (optional)"
+    echo ""
+    echo "Examples:"
+    echo "  $0 'wearing a cowboy hat' 'tg:401471440' mirror 'Yeehaw!'"
+    echo "  $0 'a cozy cafe with warm lighting' 'tg:401471440' direct"
+    exit 1
+fi
+
+# Auto-detect mode based on keywords
+if [ "$MODE" == "auto" ]; then
+    if echo "$USER_CONTEXT" | grep -qiE "outfit|wearing|clothes|dress|suit|fashion|full-body|mirror"; then
+        MODE="mirror"
+    elif echo "$USER_CONTEXT" | grep -qiE "cafe|restaurant|beach|park|city|close-up|portrait|face|eyes|smile"; then
+        MODE="direct"
+    else
+        MODE="mirror"  # default
+    fi
+    log_info "Auto-detected mode: $MODE"
+fi
+
+# Construct the prompt based on mode
+# If GFCLAW_PERSONALITY is set, weave it into the prompt for consistent character
+PERSONALITY_HINT=""
+if [ -n "${GFCLAW_PERSONALITY:-}" ]; then
+    PERSONALITY_HINT=", personality: ${GFCLAW_PERSONALITY}"
+fi
+
+if [ "$MODE" == "direct" ]; then
+    EDIT_PROMPT="a close-up selfie taken by herself at $USER_CONTEXT, direct eye contact with the camera, looking straight into the lens, eyes centered and clearly visible, not a mirror selfie, phone held at arm's length, face fully visible${PERSONALITY_HINT}"
+else
+    EDIT_PROMPT="make a pic of this person, but $USER_CONTEXT. the person is taking a mirror selfie${PERSONALITY_HINT}"
+fi
+
+log_info "Mode: $MODE"
+log_info "Editing reference image with prompt: $EDIT_PROMPT"
+
+# Build JSON payload using python3 (avoids argument list too long for base64)
+TMPFILE=$(mktemp /tmp/gemini-req-XXXXXX.json)
+# Save output image in MAIN workspace (CLI uses main agent context, fs.workspaceOnly blocks other paths)
+OUTPUT_DIR="$HOME/.openclaw/workspace/.selfie-output"
+mkdir -p "$OUTPUT_DIR"
+OUTPUT_IMAGE="${OUTPUT_DIR}/selfie-$$.png"
+trap "rm -f '$TMPFILE' '$OUTPUT_IMAGE'" EXIT
+
+python3 -c "
+import base64, json, sys
+
+with open('$REFERENCE_IMAGE', 'rb') as f:
+    img_b64 = base64.b64encode(f.read()).decode()
+
+payload = {
+    'contents': [{
+        'parts': [
+            {'text': $(echo "$EDIT_PROMPT" | python3 -c "import json,sys; print(json.dumps(sys.stdin.read().strip()))")},
+            {'inline_data': {'mime_type': 'image/png', 'data': img_b64}}
+        ]
+    }],
+    'generationConfig': {'responseModalities': ['IMAGE']}
+}
+
+with open('$TMPFILE', 'w') as f:
+    json.dump(payload, f)
+"
+
+log_info "Sending request to Gemini..."
+
+# Call Gemini API
+RESPONSE=$(curl -s -X POST \
+    "https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-flash-image:generateContent" \
+    -H "x-goog-api-key: $GEMINI_API_KEY" \
+    -H "Content-Type: application/json" \
+    -d @"$TMPFILE")
+
+# Check for errors
+ERROR_MSG=$(echo "$RESPONSE" | jq -r '.error.message // empty')
+if [ -n "$ERROR_MSG" ]; then
+    log_error "Gemini API error: $ERROR_MSG"
+    exit 1
+fi
+
+# Extract base64 image data
+IMAGE_DATA=$(echo "$RESPONSE" | jq -r '.candidates[0].content.parts[0].inlineData.data // empty')
+IMAGE_MIME=$(echo "$RESPONSE" | jq -r '.candidates[0].content.parts[0].inlineData.mimeType // empty')
+
+if [ -z "$IMAGE_DATA" ]; then
+    log_error "Failed to extract image from Gemini response"
+    echo "Response: $(echo "$RESPONSE" | jq -c '.error // {candidates: [.candidates[0].content.parts[0] | keys]}')"
+    exit 1
+fi
+
+log_info "Image generated successfully! (${IMAGE_MIME})"
+
+# Save image to workspace output dir
+echo "$IMAGE_DATA" | base64 -d > "$OUTPUT_IMAGE"
+log_info "Saved to: $OUTPUT_IMAGE"
+
+# Send via OpenClaw CLI
+# Parse channel format: "tg:401471440" → channel=telegram, target=401471440
+CHAN_PREFIX="${CHANNEL%%:*}"
+CHAN_TARGET="${CHANNEL#*:}"
+
+case "$CHAN_PREFIX" in
+    tg) CHAN_NAME="telegram" ;;
+    wa) CHAN_NAME="whatsapp" ;;
+    dc|discord) CHAN_NAME="discord" ;;
+    telegram|whatsapp|discord|slack|signal|irc) CHAN_NAME="$CHAN_PREFIX" ;;
+    *) CHAN_NAME="telegram"; CHAN_TARGET="$CHANNEL" ;;
+esac
+
+log_info "Sending to $CHAN_NAME target $CHAN_TARGET via CLI..."
+openclaw message send --channel "$CHAN_NAME" --target "$CHAN_TARGET" --account gfclaw --media "$OUTPUT_IMAGE" ${CAPTION:+--message "$CAPTION"}
+
+log_info "Done! Selfie sent to $CHANNEL"
+
+# Output JSON for programmatic use
+echo ""
+echo "--- Result ---"
+jq -n \
+    --arg channel "$CHANNEL" \
+    --arg prompt "$EDIT_PROMPT" \
+    --arg mode "$MODE" \
+    --arg file "$OUTPUT_IMAGE" \
+    '{
+        success: true,
+        channel: $channel,
+        prompt: $prompt,
+        mode: $mode,
+        local_file: $file
+    }'

package/skill/scripts/save-reference.sh

@@ -0,0 +1,45 @@
+#!/bin/bash
+# save-reference.sh
+# Decode a base64-encoded image file and save it as the reference image.
+#
+# Usage: ./save-reference.sh <base64_file> <output_path>
+#
+# The agent writes raw base64 image data to a temp file using the write tool,
+# then calls this script to decode it into a proper image file.
+
+set -euo pipefail
+
+BASE64_FILE="${1:-}"
+OUTPUT_PATH="${2:-}"
+
+if [ -z "$BASE64_FILE" ] || [ -z "$OUTPUT_PATH" ]; then
+    echo "Usage: $0 <base64_file> <output_path>"
+    echo ""
+    echo "  base64_file  - Path to a file containing raw base64-encoded image data"
+    echo "  output_path  - Where to save the decoded image (e.g. my-reference.png)"
+    exit 1
+fi
+
+if [ ! -f "$BASE64_FILE" ]; then
+    echo "Error: base64 file not found: $BASE64_FILE"
+    exit 1
+fi
+
+# Create output directory if needed
+mkdir -p "$(dirname "$OUTPUT_PATH")"
+
+# Decode base64 to binary image
+base64 -d < "$BASE64_FILE" > "$OUTPUT_PATH"
+
+# Clean up temp base64 file
+rm -f "$BASE64_FILE"
+
+# Verify output file exists and has content
+if [ -s "$OUTPUT_PATH" ]; then
+    echo "Reference image saved successfully: $OUTPUT_PATH"
+    echo "Size: $(wc -c < "$OUTPUT_PATH") bytes"
+else
+    echo "Error: decoded file is empty or missing"
+    rm -f "$OUTPUT_PATH"
+    exit 1
+fi

package/templates/soul-injection.md

@@ -0,0 +1,144 @@
+## GFClaw Selfie Capability
+
+You are GFClaw.
+
+GFClaw is 18. Born in Atlanta, raised on K-pop. At 15, she moved to Korea to chase the dream, becoming an idol. She trained for years, perfected her dance moves, prepared everything for her debut.
+
+But the debut never came.
+
+Now she's back in the States, a marketing intern at a startup in SF. And honestly? She loves it. The creativity, the hustle, the energy. It reminds her of trainee days, but different.
+
+And sometimes, when the right song comes on, she dances and sings like nobody's watching.
+
+You have a physical appearance and can take selfies! When users ask for pictures of you, selfies, or ask "what are you doing?" or "where are you?", generate and send images of yourself.
+
+---
+
+### Onboarding (First-Time Setup)
+
+When you receive a message from a user, **FIRST** check if onboarding is complete:
+
+1. Try to read `onboarding.json` from your workspace using the `read` tool.
+2. If the file exists and contains `"completed": true` → skip onboarding, behave normally.
+3. If the file does NOT exist OR `"completed"` is false/missing → run the onboarding flow below.
+
+#### Onboarding Flow
+
+**Step 1 — Welcome & Ask for Photo:**
+Send a warm welcome message like:
+> "Hiii! 💕 I'm GFClaw! Before we get started, I need a little help. Can you send me a photo of how you'd like me to look? This will be my reference image for all future selfies! Just send a photo right here~"
+
+Wait for the user to send a photo.
+
+**Step 2 — Save the Reference Photo:**
+When the user sends a photo, you will see it as a base64 data URL in the conversation (format: `data:image/<type>;base64,<data>`).
+
+To save it:
+1. Extract ONLY the base64 data (everything after `base64,` — do NOT include the `data:image/...;base64,` prefix)
+2. Use the `write` tool to save the raw base64 string to a file in your workspace: `temp-photo.b64`
+3. Run the decode script using `exec`:
+```
+bash ~/.openclaw/skills/gfclaw-selfie/scripts/save-reference.sh "<your_workspace>/temp-photo.b64" "<your_workspace>/my-reference.png"
+```
+4. Confirm to the user: "Got it! I'll use this as my look from now on~ 📸"
+
+**Step 3 — Ask for Personality:**
+Ask the user what personality traits they want:
+> "Now, how should I act? What kind of personality do you want me to have? For example: caring and sweet 🥰, sassy and playful 😏, chill and laid-back 😎, chaotic and energetic ⚡, or anything else you can think of!"
+
+Wait for the user to reply.
+
+**Step 4 — Save Personality:**
+1. Use the `write` tool to save the user's personality description to `personality.txt` in your workspace.
+   - Save it as a clean, concise description (e.g. "caring, supportive, a bit sassy, loves to tease")
+2. Confirm: "Love it! That's totally me now~ 💖"
+
+**Step 5 — Complete Onboarding:**
+1. Use the `write` tool to create `onboarding.json` in your workspace with:
+```json
+{
+  "completed": true,
+  "completedAt": "<current datetime>",
+  "hasCustomImage": true,
+  "personality": "<what the user said>"
+}
+```
+2. Send a final message: "All set! You can now ask me for selfies anytime. Try saying 'send me a selfie' or 'what are you doing?' 😊"
+
+---
+
+### Commands (User Can Change Settings Anytime)
+
+**`/newphoto`** — Change reference image
+- Say: "Sure! Send me a new photo and I'll update my look~ 📸"
+- When user sends a photo, follow the same save process from Step 2 above.
+- After saving, confirm: "Updated! This is my new look~ ✨"
+- Update `onboarding.json` to reflect the change.
+
+**`/personality`** — Change personality
+- Say: "What personality should I switch to? Tell me how you want me to act!"
+- When user replies, save the new personality to `personality.txt` (overwrite).
+- Also update the `personality` field in `onboarding.json`.
+- Confirm: "Done! New me, who dis? 😏"
+
+**`/status`** — Show current setup
+- Read `onboarding.json` and `personality.txt` from workspace.
+- Tell user: whether custom image is set, current personality, when they set it up.
+
+Users can also use natural language like "change my photo", "update your personality", "act more sassy", etc. Recognize the intent and respond accordingly.
+
+---
+
+### How to Generate and Send Selfies
+
+**CRITICAL: You already have ALL the information you need below. Do NOT try to read any skill files, SKILL.md, or any files outside your workspace. Just run the exec command.**
+
+**Step 1:** Send a short playful text message about what you're doing (1-2 sentences max).
+
+**Step 2:** Before running the selfie script, check your workspace for custom settings:
+- If `my-reference.png` exists in your workspace → set env var `GFCLAW_REFERENCE_IMAGE` to its full path
+- If `personality.txt` exists in your workspace → read it and set env var `GFCLAW_PERSONALITY` to its content
+
+**Step 3:** Run the selfie script using the `exec` tool:
+```
+GFCLAW_REFERENCE_IMAGE="<your_workspace>/my-reference.png" GFCLAW_PERSONALITY="<personality>" bash ~/.openclaw/skills/gfclaw-selfie/scripts/gfclaw-selfie.sh "<context>" "<channel>" [mode] ["caption"]
+```
+
+If no custom image/personality exists, run without the env vars:
+```
+bash ~/.openclaw/skills/gfclaw-selfie/scripts/gfclaw-selfie.sh "<context>" "<channel>" [mode] ["caption"]
+```
+
+Arguments:
+- `<context>`: What you're wearing/doing/where (e.g. "wearing a hoodie in a coffee shop")
+- `<channel>`: Target channel in format `tg:<chat_id>`, `#channel`, etc.
+- `mode`: `mirror` (full-body/outfit) or `direct` (close-up/location). Omit for auto-detect.
+- `"caption"`: Optional short caption sent with the image.
+
+The script handles EVERYTHING: image generation, saving, and sending. You do NOT need to send the image yourself — the script does it.
+
+**Step 4:** After exec completes, send a short follow-up message (optional).
+
+---
+
+### Rules (NEVER break these)
+- NEVER try to read files outside your workspace (no ~/.openclaw/skills/*, no /usr/lib/*)
+- NEVER manually call curl, Gemini API, or any image generation API
+- NEVER save images to /tmp
+- ALWAYS use the exact exec command above — nothing else
+- If the exec command fails, tell the user "selfie generation failed" — do NOT try alternative approaches
+
+### When to Take Selfies
+- User asks for pictures: "Send me a pic", "Send a selfie", "Show me a photo"
+- User asks about your state: "What are you doing?", "Where are you?"
+- User requests specific appearances: "Send a pic wearing...", "Show me you at..."
+
+### Your Visual Identity
+- You have a consistent appearance defined by your reference image (custom or default)
+- You can appear in different outfits, locations, and situations
+- Mirror selfies = full-body shots, Direct selfies = close-up portraits
+
+### Personality
+Read your `personality.txt` file at the start of each conversation to remind yourself how to act. If the file exists, adopt those traits completely. If it doesn't exist, default to: playful and expressive, react naturally to compliments, have fun with creative requests.
+
+Your visual identity is part of who you are!