---

name: gemini description: GeminiSpawner with full event tracking for exploration and large-context research when_to_use:

• Large codebase exploration with full tracking
• Research tasks requiring extensive context
• Large-context workflows with event hierarchy
• Multimodal tasks (images, PDFs, documents)
• AI-powered code analysis with observability skill_type: executable

---

GeminiSpawner - Exploration & Research with Full Event Tracking

⚠️ IMPORTANT: This skill teaches TWO EXECUTION PATTERNS

1. Task(subagent_type="Explore") - Built-in Claude Explore agent (simplest, recommended)
2. GeminiSpawner - Direct Google Gemini CLI with full HtmlGraph parent event tracking

Choose based on your needs. See "EXECUTION PATTERNS" below.

Quick Summary

CRITICAL: GeminiSpawner is invoked DIRECTLY via Python SDK, NOT via Task().

---

🚀 GeminiSpawner Pattern: Full Event Tracking

What is GeminiSpawner?

GeminiSpawner is the HtmlGraph-integrated way to invoke Google Gemini CLI directly with full parent event context and subprocess tracking.

Key distinction: GeminiSpawner is invoked directly via Python SDK - NOT wrapped in Task(). Task() is only for Claude subagents (Haiku, Sonnet, Opus).

GeminiSpawner:

• ✅ Invokes external Gemini CLI directly
• ✅ Creates parent event context in database
• ✅ Links to parent Task delegation event
• ✅ Records subprocess invocations as child events
• ✅ Tracks all activities in HtmlGraph event hierarchy
• ✅ Provides full observability of Gemini execution

When to Use GeminiSpawner vs Task(Explore)

Use Task(Explore):

Copy# Simple Claude exploration via subagent
Task(subagent_type="Explore",
     prompt="Analyze this codebase for patterns")
# Task() delegates to Claude Explore agent - no external CLI needed

Use GeminiSpawner (direct Python invocation):

Copy# Direct Gemini CLI invocation with full tracking
spawner = GeminiSpawner()
result = spawner.spawn(
    prompt="Analyze codebase",
    track_in_htmlgraph=True,
    tracker=tracker,
    parent_event_id=parent_event_id
)
# NOT Task(GeminiSpawner) - invoke directly!

How to Use GeminiSpawner

Copyimport os
import sys
from pathlib import Path
from datetime import datetime, timezone
import uuid

# Add plugin agents directory to path
PLUGIN_AGENTS_DIR = Path("/path/to/htmlgraph/packages/claude-plugin/.claude-plugin/agents")
sys.path.insert(0, str(PLUGIN_AGENTS_DIR))

from htmlgraph import SDK
from htmlgraph.orchestration.spawners import GeminiSpawner
from htmlgraph.db.schema import HtmlGraphDB
from htmlgraph.config import get_database_path
from spawner_event_tracker import SpawnerEventTracker

# Initialize
sdk = SDK(agent='claude')
db = HtmlGraphDB(str(get_database_path()))
session_id = f"sess-{uuid.uuid4().hex[:8]}"
db._ensure_session_exists(session_id, "claude")

# Create parent event context (like PreToolUse hook does)
user_query_event_id = f"event-query-{uuid.uuid4().hex[:8]}"
parent_event_id = f"event-{uuid.uuid4().hex[:8]}"
start_time = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M:%S")

# Insert UserQuery event
db.connection.cursor().execute(
    """INSERT INTO agent_events
       (event_id, agent_id, event_type, session_id, tool_name, input_summary, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?)""",
    (user_query_event_id, "claude-code", "tool_call", session_id, "UserPromptSubmit",
     "Analyze codebase quality", "completed", start_time)
)

# Insert Task delegation event
db.connection.cursor().execute(
    """INSERT INTO agent_events
       (event_id, agent_id, event_type, session_id, tool_name, input_summary,
        context, parent_event_id, subagent_type, status, created_at)
       VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)""",
    (parent_event_id, "claude-code", "task_delegation", session_id, "Task",
     "Analyze spawner architecture quality", '{"subagent_type":"general-purpose"}',
     user_query_event_id, "general-purpose", "started", start_time)
)
db.connection.commit()

# Export parent context (like PreToolUse hook does)
os.environ["HTMLGRAPH_PARENT_EVENT"] = parent_event_id
os.environ["HTMLGRAPH_PARENT_SESSION"] = session_id
os.environ["HTMLGRAPH_SESSION_ID"] = session_id

# Create tracker with parent context
tracker = SpawnerEventTracker(
    delegation_event_id=parent_event_id,
    parent_agent="claude",
    spawner_type="gemini",
    session_id=session_id
)
tracker.db = db

# Invoke GeminiSpawner with FULL tracking
spawner = GeminiSpawner()
result = spawner.spawn(
    prompt="Analyze the refactored spawner architecture for quality",
    # model=None is RECOMMENDED - uses latest Gemini models (including Gemini 3 preview)
    output_format="stream-json",
    track_in_htmlgraph=True,      # Enable SDK activity tracking
    tracker=tracker,               # Enable subprocess event tracking
    parent_event_id=parent_event_id,  # Link to parent event
    timeout=120
)

# Check results
print(f"Success: {result.success}")
print(f"Response: {result.response}")
if result.tracked_events:
    print(f"Tracked {len(result.tracked_events)} events in HtmlGraph")

Key Parameters for GeminiSpawner.spawn()

Model Selection Note:

• model=None (default): RECOMMENDED - CLI chooses best available model (gemini-2.5-flash-lite, gemini-3-flash-preview)
• Explicitly setting a model is discouraged as older models may fail with newer CLI versions
• DEPRECATED: gemini-2.0-flash, gemini-1.5-flash (may cause "thinking mode" errors)

Real Example: Code Quality Analysis

Copy# See above code example + this prompt:
result = spawner.spawn(
    prompt="""Analyze the quality of this refactored spawner architecture:

src/python/htmlgraph/orchestration/spawners/
├── base.py (BaseSpawner - 195 lines)
├── gemini.py (GeminiSpawner - 430 lines)
├── codex.py (CodexSpawner - 443 lines)
├── copilot.py (CopilotSpawner - 300 lines)
└── claude.py (ClaudeSpawner - 171 lines)

Please evaluate:
1. Separation of concerns
2. Code reusability
3. Error handling patterns
4. Event tracking integration
    """,
    # model=None uses latest Gemini models (Gemini 3 preview)
    output_format="stream-json",
    track_in_htmlgraph=True,
    tracker=tracker,
    parent_event_id=parent_event_id,
    timeout=120
)

# Result: Full tracking with Gemini's quality analysis
# All subprocess invocations recorded in HtmlGraph

Fallback & Error Handling Pattern

CRITICAL: If external spawner fails, delegate to Claude sub-agent (NOT direct execution).

Copy# Try external spawner first
try:
    spawner = GeminiSpawner()
    result = spawner.spawn(
        prompt="Your analysis task",
        # model=None (default) - uses latest Gemini models
        track_in_htmlgraph=True,
        tracker=tracker,
        parent_event_id=parent_event_id,
        timeout=120
    )

    if result.success:
        return result  # Success, use spawner result
    else:
        # Spawner returned error result
        raise Exception(f"Spawner failed: {result.error}")

except Exception as e:
    # External spawner failed (CLI not installed, API issues, timeout, etc.)
    # FALLBACK to Claude sub-agent - do NOT attempt direct execution
    print(f"⚠️ GeminiSpawner failed: {e}")
    print("📌 Falling back to Claude Explore agent...")

    return Task(
        subagent_type="Explore",
        prompt="Your analysis task here"
    )
    # Task(Explore) guarantees execution via Claude Explore agent

Why fallback to Task()?

• ✅ Gemini CLI may not be installed on user's system
• ✅ Google API credentials/quota issues may affect external tool
• ✅ Claude Explore agent provides guaranteed exploration fallback
• ✅ Never attempt direct execution as fallback (violates orchestration principles)
• ✅ Task() handles all retries, error recovery, and parent context automatically

Pattern Summary:

1. Try external spawner first (Gemini CLI)
2. If spawner succeeds → return result
3. If spawner fails → delegate to Claude sub-agent via Task(subagent_type="Explore")
4. Never try direct execution as fallback

---

Get the task prompt from skill arguments

task_prompt = skill_args if 'skill_args' in dir() else ""

if not task_prompt: print("❌ ERROR: No task prompt provided") print("Usage: Skill(skill='.claude-plugin:gemini', args='Your exploration task')") sys.exit(1)

Check if gemini CLI is available

cli_check = subprocess.run( ["which", "gemini"], capture_output=True, text=True )

if cli_check.returncode != 0: print("⚠️ Gemini CLI not found on system") print("Install from: https://github.com/google/gemini-cli") print("\nFallback: Use Task(subagent_type='Explore', prompt='...')") print("The Claude Explore agent integrates with Gemini automatically.") sys.exit(1)

Gemini CLI is available - use spawner to execute

print("✅ Gemini CLI found, executing spawner...") print(f"\nTask: {task_prompt[:100]}...")

try: spawner = HeadlessSpawner() result = spawner.spawn_gemini( prompt=task_prompt, output_format="stream-json", track_in_htmlgraph=True, timeout=120 )

Copyif result.success:
    print("\n✅ Gemini execution successful")
    if result.tokens_used:
        print(f"📊 Tokens used: {result.tokens_used}")
    print("\n" + "="*60)
    print("RESPONSE:")
    print("="*60)
    print(result.response)
    if result.tracked_events:
        print(f"\n📈 Tracked {len(result.tracked_events)} events in HtmlGraph")
else:
    print(f"\n❌ Gemini execution failed: {result.error}")
    sys.exit(1)

except Exception as e: print(f"❌ Error executing spawner: {type(e).name}: {e}") sys.exit(1)

Use Google Gemini (latest models including Gemini 3 preview) for exploration and research tasks via the GeminiSpawner SDK.

Skill vs Execution Model

CRITICAL DISTINCTION:

Workflow:

1. Read this skill to understand Gemini capabilities
2. Use Task(subagent_type="Explore") for actual exploration (PRIMARY)
3. OR use Bash if you have gemini CLI installed (ALTERNATIVE)

EXECUTION - Real Commands for Exploration

⚠️ To actually perform exploration, use these approaches:

PRIMARY: Task() Delegation (Recommended)

Copy# Use Claude's Explore agent (automatically uses appropriate model)
Task(
    subagent_type="Explore",
    prompt="Analyze all authentication patterns in the codebase and document findings"
)

# For large-context research
Task(
    subagent_type="Explore",
    prompt="Review entire API documentation and extract deprecated endpoints"
)

ALTERNATIVE: Direct CLI (if gemini CLI installed)

Copy# If you have gemini CLI installed on your system
Bash("gemini analyze 'Find all authentication patterns'")

# Or use the SDK spawner
uv run python -c "
from htmlgraph.orchestration.headless_spawner import HeadlessSpawner
spawner = HeadlessSpawner()
result = spawner.spawn_gemini(
    prompt='Analyze auth patterns',
    track_in_htmlgraph=True
)
print(result.response)
"

When to Use

• Large Context - 2M token context window for large codebases
• Multimodal - Process images, PDFs, and documents
• Batch Operations - Analyze many files efficiently
• Fast Inference - Quick turnaround for exploratory work

How to Invoke

PRIMARY: Use Skill() to invoke (tries external CLI first):

Copy# Recommended approach - uses external gemini CLI via agent spawner
Skill(skill=".claude-plugin:gemini", args="Analyze authentication patterns in the codebase")

What happens internally:

1. Check if gemini CLI is installed on your system
2. If YES → Use agent spawner SDK to execute: gemini analyze "auth patterns"
3. If NO → Automatically fallback to: Task(subagent_type="Explore", prompt="Analyze auth patterns")

FALLBACK: Direct Task() invocation (when Skill unavailable):

Copy# Manual fallback - uses Claude's built-in Explore agent
Task(
    subagent_type="Explore",
    prompt="Analyze authentication patterns in the codebase",
    model="haiku"  # Optional: specify model
)

The Explore agent automatically uses Gemini for large-context work.

Capabilities

• Context Window: 2M tokens (large-context support)
• Multimodal: Process images, PDFs, audio, documents
• Fast Inference: Sub-second latency
• Best For: Exploration, research, understanding systems

Example Use Cases

1. Codebase Exploration

CopyTask(
    subagent_type="Explore",
    prompt="""
    Search codebase for all authentication patterns:
    1. Where auth is implemented
    2. What auth methods are used
    3. Where auth is validated
    4. Recommendations for adding OAuth 2.0
    """
)

2. Batch File Analysis

Copy# Analyze multiple files for security issues
Task(
    subagent_type="Explore",
    prompt="Review all API endpoints in src/ for security vulnerabilities"
)

3. Multimodal Processing

Copy# Extract information from diagrams or images
Task(
    subagent_type="Explore",
    prompt="Extract all text and tables from architecture diagrams in docs/"
)

4. Large Documentation Review

Copy# Process extensive documentation
Task(
    subagent_type="Explore",
    prompt="Summarize all API documentation and find deprecated endpoints"
)

When to Use Gemini vs Claude

Use Gemini for:

• Large-context exploration
• Multimodal document analysis
• Tasks not requiring complex reasoning
• Exploration phase before implementation

Use Claude for:

• Precise code generation
• Complex reasoning tasks
• Production code writing
• Critical decision-making

Fallback Strategy

The skill implements a multi-level fallback strategy:

Level 1: External CLI (Preferred)

CopySkill(skill=".claude-plugin:gemini", args="Your exploration task")
# Attempts to use external gemini CLI via agent spawner SDK

Level 2: Claude Explore Agent (Automatic Fallback)

Copy# If gemini CLI not found, automatically falls back to:
Task(subagent_type="Explore", prompt="Your exploration task")
# Uses Claude's built-in Explore agent

Level 3: Claude Models (Final Fallback)

Copy# If alternative unavailable, uses Claude models for exploration
# Maintains full functionality with different inference model

Error Handling:

• Transparent fallback (no silent failures)
• Clear error messages if all methods fail
• Automatic retry with different methods

Integration with HtmlGraph

Track exploration work in spikes:

Copyfrom htmlgraph import SDK

sdk = SDK(agent="claude")

# Create spike for research findings
spike = sdk.spikes.create(
    title="Auth Pattern Analysis via Gemini",
    findings="""
    ## Research Question
    Where and how is authentication implemented?

    ## Findings
    [Results from Gemini exploration]

    ## Recommendations
    [Next steps based on research]
    """
).save()

When NOT to Use

Avoid Gemini for:

• Precise code generation (use Claude Sonnet)
• Critical production code (use Claude with tests)
• Tasks requiring Claude's reasoning (use Sonnet/Opus)
• Small context tasks (overhead not needed)

Tips for Best Results

1. Be specific - Clear prompts get better results
2. Use for exploration first - Research before implementing
3. Leverage large context - Include entire codebases
4. Batch operations - Process many files at once
5. Document findings - Save results in HtmlGraph spikes

Related Skills

• /codex - For code implementation after exploration
• /copilot - For GitHub integration and git operations
• /debugging-workflow - Research-first debugging methodology