AI CLI Integration

How Claude Code CLI and Gemini CLI are invoked for site generation.

Design Philosophy

Hippopotamoose does not call the Claude or Gemini APIs directly. Instead, it spawns the official CLI tools in separate, visible terminal windows. This design has several advantages:

• The AI has full tool access (file read/write, shell commands) within its window
• You can watch the AI work in real-time
• The app's main process stays responsive — it just monitors when the terminal closes
• If the AI gets stuck, you can interact with the terminal directly
• No API key management in the app — the CLI handles auth

The Launcher Chain

ai_launcher.py → reads USE_GEMINI_CLI from registry → calls claude_launcher.py or gemini_launcher.py

Claude Launcher

File: core/claude_launcher.py

Why a Temp File for the Prompt?

Windows has a maximum command-line length of ~32,000 characters. Demo prompts routinely exceed this (they include full site file listings). Passing the prompt via a temporary file avoids this limit entirely.

Process

1. Prompt string is written to data/temp/tmpXXXXXX.txt (unique filename per invocation).
2. A PowerShell command is assembled:

   Set-Location '<working_dir>';
   $task = Get-Content -Path '<prompt_file>' -Raw;
   claude --dangerously-skip-permissions --model <model> --effort <effort> $task

3. subprocess.Popen is called with creationflags=subprocess.CREATE_NEW_CONSOLE and shell=True. This opens a new, independent terminal window.
4. The flag -NoExit is NOT used — the terminal closes when Claude exits, which is how ProcessMonitor detects completion.
5. A ProcessMonitor QThread is started to watch the process. When it emits finished, the temp file is deleted.

Return Value

Returns a tuple (proc, monitor) where proc is the subprocess.Popen object and monitor is the ProcessMonitor QThread. The caller connects to monitor.finished to react when the AI session ends.

Gemini Launcher

File: core/gemini_launcher.py

Identical structure to claude_launcher but runs:

gemini --yolo $task

The --yolo flag grants the Gemini CLI permission to run tool calls without confirmation prompts, mirroring the behavior of --dangerously-skip-permissions for Claude.

AI Model & Effort Parameters

Both launchers accept use_case and model parameters. ai_launcher.py reads the per-use-case model and effort from the registry before calling the launcher:

Use Case	Registry Keys
scratch	AI_MODEL_SCRATCH, AI_EFFORT_SCRATCH
demo	AI_MODEL_DEMO, AI_EFFORT_DEMO
form	AI_MODEL_FORM, AI_EFFORT_FORM
reiterate	AI_MODEL_REITERATE, AI_EFFORT_REITERATE

Cold Call — Silent Invocation

The Cold Call step does not open a terminal window. Instead, ColdCallWorker runs Claude with the -p (print) flag for a single-shot, non-interactive response:

claude -p "<contact_extraction_prompt>" \
       --model claude-sonnet-4-6 \
       --effort low

The worker captures stdout directly and parses the JSON response. This is appropriate for cold call because the task is mechanical (extract contacts) and doesn't benefit from the interactive AI tool loop.

Demo Prompt Structure

The Demo prompt instructs the AI to work autonomously through a site rebuild. It includes:

• The original site's file tree and key HTML content
• The business name, URL, and niche
• File listings of any example sites in the same niche
• Explicit instructions: build React, use modern libraries, preserve all content, write DESIGN_NOTES.md
• A reminder that the working directory is the site folder and the AI should create all files there

Monitoring Terminal Exit

The pipeline row widget connects to ProcessMonitor.finished(exit_code):

• Exit code 0 → step marked complete
• Any other exit code → step marked failed
• If the user closes the terminal window manually → process exit code depends on how PowerShell handles the close (typically non-zero)