crumbmissions/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

CF_Zero_V1 Project Overview

CF_Zero_V1 is an educational Bash learning platform called "Crumbforest" that uses 17 character-based AI assistants ("Waldwächter" - Forest Guardians) to teach command-line concepts, programming fundamentals, and hardware/robotics projects through interactive missions. The system is designed to run on devices ranging from Raspberry Pi Zero to desktop computers, emphasizing transparency, file-based state, and pedagogical value.

Key Commands

Mission System

# Launch the interactive mission selector (main entry point)
./crumb-mission-selector.sh

# Option 9 opens CrumbCrew Command Central (interactive shell with all AI characters)

# Run individual missions directly
bash missions/basics/fridolin.sh           # Navigation basics
bash missions/basics/balu.sh               # File creation
bash missions/basics/noko.sh               # File reading
bash missions/advanced/dns_mission.sh      # DNS tools
bash missions/advanced/ssh_security.sh     # SSH basics
bash missions/robots/lipo_power_academy.sh # LiPo battery education
bash missions/robots/regenbogen_zaehlmaschine.sh # Rainbow counter project
bash missions/robots/mond_maschine.sh      # Moon machine ML project
bash missions/robots/solar_kettle.sh       # Solar water heater physics

AI Character Assistants - The 17 Waldwächter

All characters require OPENROUTER_API_KEY environment variable set in .env file:

# Configure environment (required first step)
cp .env.template .env
# Edit .env and add your OPENROUTER_API_KEY

# === DAS DREIECK (The Triangle - Foundation) ===
# Philosophical/didactic framework (not a technical module)
./crumbforest_roles/dumbosql_zero.sh "Design a sensor database"    # Structure/Lists
./crumbforest_roles/funkfox_zero.sh "Explain pipes in rap form"    # Flow/Rhythm
./crumbforest_roles/taichitaube_zero.sh "How to balance chaos?"    # Balance/Spiral

# === Hardware Team ===
./crumbforest_roles/tobi_zero.sh "Explain capacitors"              # CapaciTobi - Electronics
./crumbforest_roles/schnecki_zero.sh "How to wire sensors?"        # Wiring specialist
./crumbforest_roles/schraubaer_zero_final.sh "Welding tips?"       # Heavy machinery

# === Code Team ===
./crumbforest_roles/snakepy_zero.sh "Python list comprehension"    # Python guide
./crumbforest_roles/pepperphp_zero.sh "MVC architecture"           # PHP structure
./crumbforest_roles/crabbrust_zero.sh "Memory safety in Rust"      # Security guardian
./crumbforest_roles/spider_zero.sh "API REST design"               # Network specialist

# === UI Team ===
./crumbforest_roles/schnippsi_zero.sh "CSS grid layout"            # Styling
./crumbforest_roles/templatus_zero.sh "HTML structure"             # Templates
./crumbforest_roles/asciimonster_zero.sh "Draw ASCII art"          # Terminal art

# === System Team ===
./crumbforest_roles/mayaeule_zero.sh "What is wisdom?"             # Meta-knowledge owl
./crumbforest_roles/deepbit_zero.sh "How does grep work?"          # Bash deep dive
./crumbforest_roles/bugsy_zero.sh "Debug this error"               # Debugging
./crumbforest_roles/vektor_zero.sh "Navigate this project"         # Point-to-point guide

Unified Access via Waldwächter Library

Preferred method for missions and scripts:

# Source the library to get all characters as shell functions
source lib/waldwaechter.sh

# Now all characters are available as commands (no path needed)
dumbosql "Design a users table"
funkfox "Explain while loops as a rap"
schnippsi "Center a div with CSS"
mayaeule "What is the meaning of code?"

# Utility commands (available after sourcing waldwaechter.sh)
crew_tokens     # View token usage across all characters
crew_status     # Check which characters are available
crew_memory     # View conversation histories (crew context)
crew_doctor     # System health check (dependencies, API keys)
crew_syntax     # Validate bash syntax for all scripts
crew_help       # Show available commands
crew_memo       # Track creative outputs (Mixcloud, Git, etc.)

CrumbCrew Command Central (Position 9 in Mission Selector)

Interactive shell with all Waldwächter pre-loaded:

• Custom prompt: (🌲 CrumbCrew) user@host:path$
• All 17 characters available as direct commands
• Utilities: crew_status, crew_tokens, crew_memory, crew_doctor
• Exit with exit or Ctrl+D

Crumbblocks - Browser-Terminal Bridge

# Start local server for interactive HTML simulations
./start_crumbblocks.sh

# Opens browser to http://localhost:8000 (or similar)
# Available simulations:
# - lipo_6s_charger_sim_safe_v7.html (LiPo battery charger)
# - rainbow_counter.html (Color event counter)
# - solar_kettle_dark.html (Solar water heater physics)
# - bezier_stream.html, painter.html, and more

# Simulations use Clipboard API to send results back to terminal
# Evaluation scripts in missions/robots/ parse clipboard data

Token Usage Monitoring

# View token usage across all AI assistants (new unified system)
crew_tokens

# View individual character logs (repo-based)
cat logs/mayaeule/token_log.json
cat logs/funkfox/token_log.json
cat logs/dumbosql/token_log.json

# View conversation history
cat logs/mayaeule/eule_history.json
cat logs/funkfox/funkfox_history.json

# Track creative outputs
crew_memo
cat logs/crumb_memo.json

Creative Output Tracking (crumb_memo)

# Log creative outputs (dual transparency: input + output)
crumb_memo "https://mixcloud.com/your-mix" "My first beat"
crumb_memo "https://github.com/user/repo" "My robot code"
crumb_memo "https://youtube.com/watch?v=..." "Tutorial video"

# View all logged creative outputs
crew_memo

Architecture Overview

Core Design Philosophy

Waldwächter (Forest Guardian) Architecture:

• Transparency over magic - All state is file-based JSON
• Metadata-driven extensibility - Add content without code changes
• Educational first - Token tracking teaches mindful questioning
• Raspberry Pi Zero compatible - Minimal dependencies, lightweight
• Multilingual - Characters respond in the language of the question
• File-based agent memory - Characters can read each other's logs

Mission System Architecture

Metadata-Driven Design:

• Each mission consists of two files: mission_name.sh (executable) and mission_name.meta.json (metadata)
• The mission selector (crumb-mission-selector.sh) dynamically loads missions by scanning directories
• No code changes required to add new content - just drop in files

Metadata structure:

{
  "icon": "🦊",
  "title": "Mission Title",
  "description": "What this teaches",
  "category": "basics|advanced|challenges|robots",
  "enabled": true
}

Mission Categories:

• missions/basics/ - Beginner missions (navigation, file operations) - 3 missions
• missions/advanced/ - Advanced topics (DNS, SSH, networking) - 2 missions
• missions/challenges/ - Story-based complex missions - 1 mission
• missions/robots/ - Hardware projects (LiPo, rainbow counter, moon machine, solar kettle) - 5 missions
• missions/dojo/ - BashPanda Kung Fu Belt System (progressive Bash mastery) - 6 missions

AI Assistant Architecture - The 17 Waldwächter

Character Roster (Organized by Role):

1. Das Dreieck (The Triangle) - Philosophical framework:

   • DumboSQL (🐘) - Structure/Lists (SQL, data organization, never forgets)
   • FunkFox (🦊) - Flow/Rhythm (Bash rapper, explains as hip-hop)
   • Taichi Taube (🕊️) - Balance/Spiral (Chaos management, patience)

2. Hardware Team:

   • CapaciTobi (🐿️) - Electronics, power, capacitors (alias: Tobi)
   • Schnecki (🐌) - Wiring, connections (slow and precise)
   • Schraubbär (🐻) - Heavy machinery, welding, mechanical systems

3. Code Team:

   • SnakePy (🐍) - Python guide (shows multiple paths)
   • PepperPHP (🧓) - PHP structure mentor (MVC as recipes)
   • CrabbyRust (🦀) - Rust security guardian (memory safety)
   • Spider (🕷️) - Network specialist (APIs, connections)

4. UI Team:

   • Schnippsi (✂️) - CSS and styling expert
   • Templatus (📄) - HTML template master
   • ASCII-Monster (👾) - Terminal artist (ASCII art)

5. System Team:

   • Maya-Eule (🦉) - Wise owl with meta-knowledge
   • Deepbit (🔧) - Bash deep dive explainer
   • Bugsy (🐛) - Debugging detective
   • Vektor (🧭) - Point-to-point navigation guide

6. Education Team:

   • BashPanda (🐼) - Kung Fu Bash Meister (teaches progressive Bash through martial arts metaphors)

Common Pattern (Each Character Script):

1. Load .env file (API keys)
2. Check token budget (optional parental control)
3. Build personality-specific system prompt
4. Check crew memory (if other characters mentioned in question)
5. Call OpenRouter API with conversation history
6. Log response + tokens to logs/{character}/
7. Display with character-specific formatting

The Personality IS the System Prompt: Each character has a unique system prompt that defines their teaching style. Example from FunkFox:

"Du bist FunkFox - der Bash Rapper.
Du erklärst Terminal-Konzepte im Hip-Hop-Flow.
Pipes sind Beats, Loops sind Rhythmen."

API Flow:

Question → Check Budget → Load History → Build Prompt → OpenRouter API → Log Response → Display
                                    ↓
                              Check Crew Memory (if other characters mentioned)

Log Structure (Repo-Based):

logs/
├── mayaeule/
│   ├── eule_history.json          # Conversation history
│   ├── token_log.json             # Token usage tracking
│   ├── eule_request.json          # Last API request
│   └── eule_response.json         # Last API response
├── funkfox/
│   ├── funkfox_history.json
│   └── token_log.json
├── dumbosql/
│   ├── dumbosql_history.json
│   └── token_log.json
├── ... (all 17 characters)
├── crumb_memo.json                # Creative output tracking
└── missions/                      # Mission execution logs

Key Difference from Old System:

• Old: Logs in ~/.{character}_logs/ (home directory)
• New: Logs in logs/{character}/ (repository-based)
• Why: Git-trackable, transparent, portable, easier debugging

Waldwächter Library (lib/waldwaechter.sh)

Central Integration Point - 715 lines of unified functionality:

This is the most important file for understanding how the system works. It provides:

1. Unified character access - All 17 characters as shell functions
2. Environment management - Loads .env, sets CRUMB_LOGS_DIR
3. Utility functions - crew_tokens, crew_status, crew_memory, crew_doctor, etc.
4. Token budget enforcement - Optional parental controls
5. Cross-shell compatibility - Works in bash, zsh

Usage in missions:

# At top of mission script
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
source "${SCRIPT_DIR}/../../lib/waldwaechter.sh"

# Now all characters and utilities are available
funkfox "Explain this concept"
crew_tokens

Utility Functions:

• crew_tokens - Display token usage across all characters with cost estimates
• crew_status - Check which character scripts are available
• crew_memory - View conversation histories (crew context awareness)
• crew_doctor - System health check (dependencies, API keys, paths)
• crew_syntax - Validate bash syntax for all scripts
• crew_help - Show available commands and characters
• crew_memo - Track creative outputs (Mixcloud, Git repos, YouTube, etc.)

Inter-Character Communication (Crew Memory)

Lightweight Agent-Like Behavior:

Characters can reference each other's conversation histories through JSON log files:

# User asks FunkFox a question mentioning another character
funkfox "DumboSQL said we need a users table, what bash loops do I use?"

# FunkFox script automatically:
# 1. Detects "dumbosql" mention in question
# 2. Reads logs/dumbosql/dumbosql_history.json
# 3. Includes last 3 conversations as context
# 4. Enriches system prompt with crew context
# 5. Responds with awareness of DumboSQL's advice

Implementation:

• Characters detect mentions of other crew members (case-insensitive grep)
• Read last 3 conversations from mentioned character's history file
• Include as context in API call system prompt
• Lightweight: Simple JSON file reading, no complex orchestration
• Transparent: All context visible in log files
• Raspberry Pi friendly: No Redis, no databases, just files

Crew context format:

{
  "role": "system",
  "content": "Context from DumboSQL: [last 3 conversations]..."
}

Crumbblocks Architecture (Browser-Terminal Bridge)

17 HTML files in crumbblocks/ directory:

Design Pattern:

• Self-contained - No external dependencies, single HTML files
• Clipboard API - Send data back to terminal via copy to clipboard
• Interactive simulations - Physics engines, visualizations, games
• Educational - Each teaches a concept (batteries, colors, energy, art)

Key Examples:

• lipo_6s_charger_sim_safe_v7.html - LiPo battery charger simulation (6S, balancing, safety)
• rainbow_counter.html - Color event counter with RGB sensor simulation
• solar_kettle_dark.html - Solar water heater physics engine
• bezier_stream.html - Bézier curve generator
• painter.html, painter_spray.html, painter_lines.html - Creative painting tools
• schnippsi_ui.html - Schnippsi's UI editor

Evaluation Flow:

1. User interacts with Crumbblock simulation in browser
2. Simulation calculates results (e.g., battery voltage, water temperature)
3. Results exported to clipboard as JSON
4. User pastes in terminal
5. Mission evaluation script parses JSON and provides feedback

Server Options:

# PHP server (if available)
php -S localhost:8000

# Python server (fallback)
python3 -m http.server 8000

# start_crumbblocks.sh detects and uses best option

"Das Dreieck" - Philosophical Framework

Important: This is a didactic model, not a technical module.

The Triangle represents three foundational concepts taught through specific characters:

1. DumboSQL (🐘) - Structure/Lists

   • Data organization, SQL, tables, persistence
   • "The elephant never forgets"
   • Teaches: How to organize information

2. FunkFox (🦊) - Flow/Rhythm

   • Pipes, loops, process orchestration
   • "Terminal concepts as hip-hop beats"
   • Teaches: How processes flow and connect

3. Taichi Taube (🕊️) - Balance/Spiral

   • Chaos management, patience, iterative refinement
   • "The spiral path, not the straight line"
   • Teaches: How to handle complexity gracefully

Usage in Missions:

Complex projects (like robots missions) explicitly invoke The Triangle for planning:

dumbosql "Design the data structure for rainbow counter"
funkfox "What's the flow of data from sensor to display?"
taichitaube "How do we balance hardware and software complexity?"

This creates a structured approach to problem-solving that children can internalize.

"BashPanda Dojo" - Progressive Bash Learning System

NEW in v0.0-RC4: A complete Kung Fu-themed Bash learning curriculum with belt progression system.

The BashPanda Dojo teaches Bash through martial arts metaphors, creating a gamified progression path from beginner to master. Each belt represents a skill level with dedicated missions and interactive quizzes.

The 6 Belts:

1. 🖤 Schwarzer Gürtel (Black) - The Basics

   • echo, printf, ANSI codes
   • Variables (creating, using)
   • read (user input)
   • Mission: bash missions/dojo/schwarzer_guertel.sh

2. 💖 Pinker Gürtel (Pink) - Control Flow

   • if/then/else conditions
   • while and for loops
   • Arrays
   • Arithmetik $(( ))
   • Mission: bash missions/dojo/pinker_guertel.sh

3. 💙 Blauer Gürtel (Blue) - Text Mastery

   • sed (stream editor)
   • case statements
   • bc (floating point math)
   • wc (word count)
   • Mission: bash missions/dojo/blauer_guertel.sh

4. 💚 Grüner Gürtel (Green) - Pattern Recognition

   • grep basics and options
   • Regular expressions (regex)
   • Email/date pattern matching
   • grep -E (extended regex)
   • Mission: bash missions/dojo/gruener_guertel.sh

5. 💛 Gelber Gürtel (Yellow) - Modularity

   • Functions (defining, calling)
   • Function parameters ($1, $@, $#)
   • source (library loading)
   • return vs exit
   • local variables
   • Mission: bash missions/dojo/gelber_guertel.sh

6. 🤍 Weisser Gürtel (White) - Mastery

   • Background jobs (&)
   • jobs, ps commands
   • wait for synchronization
   • Parallel processing
   • Process control
   • Mission: bash missions/dojo/weisser_guertel.sh

Interactive Gürtelprüfung (Belt Exam):

Each belt has a browser-based quiz for assessment:

1. Open: ./start_crumbblocks.sh
2. Navigate to: bashpanda_guertelpruefung.html
3. Select your belt and answer 5 questions
4. Results auto-copy to clipboard
5. Paste into terminal: bash missions/dojo/evaluate_guertelpruefung.sh
6. Receive certificate if passed (80%+ required)

Certificates:

• Stored in logs/zertifikate/
• Format: {belt}_{user}_{timestamp}.txt
• Contains score, date, BashPanda seal

Teaching Philosophy:

• "Der Weg des Codes ist wie der Weg der Kampfkunst: Geduld, Präzision, Wiederholung"
• Each command is a "kata" (form) to be practiced
• Errors are teachers, not failures
• Progressive difficulty builds confidence
• BashPanda provides wisdom and encouragement throughout

Integration with Waldwächter:

• BashPanda can be called from any mission: bashpanda "question"
• Understands context from other characters via crew memory
• Responds in language of question (German/English/etc.)
• Token tracking for mindful learning

Usage Example:

# Start belt progression
bash missions/dojo/schwarzer_guertel.sh

# Ask BashPanda for help
source lib/waldwaechter.sh
bashpanda "Erkläre mir echo vs printf"

# Take belt exam
./start_crumbblocks.sh
# (Open bashpanda_guertelpruefung.html in browser)

# Evaluate results
bash missions/dojo/evaluate_guertelpruefung.sh

Project Structure

CF_Zero_V1/
├── crumb-mission-selector.sh          # Main entry point (1027 lines)
├── lib/
│   └── waldwaechter.sh                # 17 AI characters + utilities (715 lines)
├── crumbforest_roles/                 # 17 individual AI character scripts
│   ├── dumbosql_zero.sh               # Structure/Lists (Das Dreieck)
│   ├── funkfox_zero.sh                # Flow/Rhythm (Das Dreieck)
│   ├── taichitaube_zero.sh            # Balance/Spiral (Das Dreieck)
│   ├── tobi_zero.sh                   # CapaciTobi - Electronics
│   ├── schnecki_zero.sh               # Wiring specialist
│   ├── schraubaer_zero_final.sh       # Heavy machinery
│   ├── snakepy_zero.sh                # Python guide
│   ├── pepperphp_zero.sh              # PHP structure
│   ├── crabbrust_zero.sh              # Rust security
│   ├── spider_zero.sh                 # Network APIs
│   ├── schnippsi_zero.sh              # CSS styling
│   ├── templatus_zero.sh              # HTML templates
│   ├── asciimonster_zero.sh           # ASCII art
│   ├── mayaeule_zero.sh               # Wise owl
│   ├── deepbit_zero.sh                # Bash deep dive
│   ├── bugsy_zero.sh                  # Debugging
│   └── vektor_zero.sh                 # Navigation
├── missions/                          # Educational missions
│   ├── basics/                        # 3 beginner missions
│   │   ├── fridolin.sh/meta.json      # Navigation (pwd, ls, cd)
│   │   ├── balu.sh/meta.json          # File creation (mkdir, touch)
│   │   └── noko.sh/meta.json          # File reading (cat, grep)
│   ├── advanced/                      # 2 advanced missions
│   │   ├── dns_mission.sh/meta.json   # DNS tools
│   │   └── ssh_security.sh/meta.json  # SSH basics
│   ├── challenges/                    # 1 story-based mission
│   ├── robots/                        # 5 hardware missions
│   │   ├── lipo_power_academy.sh      # LiPo battery education (8 phases)
│   │   ├── regenbogen_zaehlmaschine.sh # Rainbow counter (7 phases)
│   │   ├── mond_maschine.sh           # Moon machine ML (8 phases)
│   │   ├── solar_kettle.sh            # Solar water heater (6 phases)
│   │   └── evaluate_solar_kettle.sh   # Evaluation script
│   └── dojo/                          # 6 BashPanda belt missions (NEW!)
│       ├── schwarzer_guertel.sh       # Black belt - Basics
│       ├── pinker_guertel.sh          # Pink belt - Control flow
│       ├── blauer_guertel.sh          # Blue belt - Text
│       ├── gruener_guertel.sh         # Green belt - Pattern matching
│       ├── gelber_guertel.sh          # Yellow belt - Functions
│       ├── weisser_guertel.sh         # White belt - Processes
│       └── evaluate_guertelpruefung.sh # Quiz evaluation
├── crumbblocks/                       # 18 HTML interactive simulations
│   ├── lipo_6s_charger_sim_safe_v7.html
│   ├── rainbow_counter.html
│   ├── solar_kettle_dark.html
│   ├── bashpanda_guertelpruefung.html  # Belt quiz (NEW!)
│   ├── bezier_stream.html
│   ├── painter.html
│   └── ... (12 more)
├── logs/                              # Repo-based logging
│   ├── mayaeule/
│   │   ├── eule_history.json
│   │   └── token_log.json
│   ├── funkfox/
│   ├── dumbosql/
│   ├── bashpanda/                     # BashPanda logs (NEW!)
│   ├── ... (all 18 characters)
│   ├── crumb_memo.json                # Creative output tracking
│   ├── zertifikate/                   # Belt certificates (NEW!)
│   └── missions/                      # Mission execution logs
├── seeds/                             # Seed data for collaborative systems
├── start_crumbblocks.sh               # Launch browser simulations
├── .env.template                      # Environment variables template
└── README.md                          # German documentation

Important Implementation Notes

Adding New Missions

Zero code changes required - just drop in two files:

1. Create two files in appropriate category folder:

   touch missions/robots/new_mission.sh
   touch missions/robots/new_mission.meta.json
   chmod +x missions/robots/new_mission.sh
   

2. Metadata must include:

   {
     "icon": "🚀",
     "title": "Your Mission Title",
     "description": "What this teaches",
     "category": "basics|advanced|challenges|robots",
     "enabled": true
   }
   

3. Mission script best practices:

   #!/bin/bash
   # Source waldwaechter library for AI character access
   SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
   source "${SCRIPT_DIR}/../../lib/waldwaechter.sh"
   
   # Use cat << 'EOF' for multi-line instructions
   # Include interactive prompts with read -p
   # Provide examples before asking user to try
   # Call AI characters as needed: funkfox "question"
   # End with success message
   

4. Mission will automatically appear in mission selector on next run

Creating New AI Assistants

Current roster is complete (17 characters), but if adding new ones:

1. Copy template from existing character:

   cp crumbforest_roles/deepbit_zero.sh crumbforest_roles/newchar_zero.sh
   

2. Update these elements:

   • Character name and emoji in echo statements
   • System prompt in jq -n command (defines personality)
   • Log file paths (use ${CRUMB_LOGS_DIR}/newchar/)
   • Function name if adding to waldwaechter.sh

3. Add to lib/waldwaechter.sh:

   # 🎭 NewChar - Description
   function newchar() {
       "${ROLES_DIR}/newchar_zero.sh" "$@"
   }
   export -f newchar
   

4. Test with:

   source lib/waldwaechter.sh
   newchar "Test question"
   crew_status  # Should show new character
   

Token Log Format

Each character logs API usage in this format:

{
  "zeit": "2025-12-23 19:05:33",
  "rolle": "funkfox",
  "usage": {
    "prompt_tokens": 45,
    "completion_tokens": 123,
    "total_tokens": 168
  }
}

View with: crew_tokens (formatted with cost estimates)

Creating New Crumblocks

Self-contained HTML simulations:

1. Create single HTML file in crumbblocks/:

   touch crumbblocks/my_simulation.html
   

2. Include in HTML:

   • All CSS in <style> tags
   • All JavaScript inline
   • No external dependencies (except standard browser APIs)
   • Use Clipboard API to export results:

     const results = {your: "data"};
     navigator.clipboard.writeText(JSON.stringify(results));
     

3. Create evaluation script in mission:

   # missions/robots/my_mission.sh
   echo "Paste your results from the browser:"
   read USER_CLIPBOARD
   
   # Parse JSON with jq
   VALUE=$(echo "$USER_CLIPBOARD" | jq -r '.your')
   
   # Evaluate and provide feedback
   if [[ $VALUE == "expected" ]]; then
       echo "✅ Success!"
   fi
   

4. Launch with: ./start_crumbblocks.sh → navigate to your simulation

Environment Requirements

Minimal Requirements (Bash Missions Only)

• Bash 3.2+ (macOS default shell compatible)
• jq - JSON processing (brew install jq or apt install jq)
• curl - API calls (usually pre-installed)
• bc - Math calculations (usually pre-installed)

AI Assistants

• OPENROUTER_API_KEY in .env file (required)
• Optional: OPENAI_API_KEY, ANTHROPIC_API_KEY, or local Ollama
• Internet connection for API calls

Crumbblocks (Browser Simulations)

• Modern web browser (Chrome, Firefox, Safari, Edge)
• PHP or Python3 for local server (start_crumbblocks.sh auto-detects)

Computer Vision Missions (Optional)

• Python 3.x
• OpenCV: pip install opencv-python
• Webcam (for SnakeCam missions)
• Requires Raspberry Pi 4+ (Raspberry Pi Zero insufficient for OpenCV)

Recommended Development Tools

• shellcheck - Bash linting (brew install shellcheck)
• tree - Directory visualization

Philosophy and Design Principles

Token Philosophy - "Was kostet die Frage eines Kindes?"

"What does a child's question cost?"

In the forest, a child's question is priceless. In our digital age, questions to AI consume tokens. This creates a teaching moment:

• In the forest: Unbezahlbar (priceless) - every question holds infinite value
• In the system: Measured in tokens - a concrete, understandable metric
• Pedagogically: Token tracking teaches mindful questioning

Why This Matters:

1. Teaches Reflection - Think before asking
2. Creates Awareness - Resources have value
3. Builds Quality - Better questions → better answers
4. Encourages Research - Try to find answers independently first
5. Develops Patience - Not every thought needs immediate AI response

Token Budget System:

# In .env file
DAILY_TOKEN_BUDGET=0        # 0 = unlimited (default)
DAILY_TOKEN_BUDGET=10000    # ~20 thoughtful questions per day

This isn't restriction - it's mindfulness education.

Dual Transparency: Input + Output

Input Transparency: crew_tokens - What you ASK

• Tracks every question to AI characters
• Shows token cost per question
• Teaches resource awareness

Output Transparency: crew_memo - What you CREATE

• Tracks creative outputs (Mixcloud, Git, YouTube)
• Values both learning AND creation
• Celebrates achievements

# Log a creative output
crumb_memo "https://mixcloud.com/your-mix" "My first beat"
crumb_memo "https://github.com/user/repo" "Robot project code"

# View all logged outputs
crew_memo

Philosophy: Transparency in what we consume AND what we produce.

Character-Based Learning

Why 17 distinct personalities?

Different learners connect with different teaching styles:

• FunkFox - Explains concepts as rap/hip-hop (rhythm learners)
• DumboSQL - Never forgets, structured explanations (logical learners)
• Taichi Taube - Poetic, patient, spiral approach (reflective learners)
• CrabbyRust - Security-focused, precise (safety-conscious learners)
• ASCII-Monster - Visual, artistic (creative learners)

Result: Every child finds a character they connect with.

File-Based State (No Databases)

Why JSON files instead of Redis/Postgres?

1. Transparency - Any text editor can read state
2. Debuggability - cat logs/funkfox/funkfox_history.json shows everything
3. Git-trackable - Version control for learning history
4. Raspberry Pi friendly - No database server overhead
5. Educational - Students can see how data is stored
6. Portable - Copy logs/ folder = copy entire history

Trade-off: Not suitable for concurrent multi-user systems. Perfect for single-user educational context.

Raspberry Pi Zero Compatibility

Design Constraint: Core features must run on Raspberry Pi Zero (ARM, 512MB RAM)

Implications:

• Bash-first, no heavy frameworks
• File-based state, no databases
• Lightweight AI models (gpt-3.5-turbo default)
• Optional features for higher-spec hardware (OpenCV missions)
• Minimal dependencies

Testing: Always test on constrained hardware, not just desktop.

German-First, Multilingual Ready

Primary Language: German (all documentation, missions, README)

Multilingual AI: Characters respond in the language of the question:

mayaeule "What is wisdom?"      # → English response
mayaeule "Was ist Weisheit?"    # → German response
funkfox "Explique les pipes"    # → French response

Implementation: OpenRouter API automatically detects input language.

Common Pitfalls and Solutions

Pitfall 1: Hardcoded Log Paths

Wrong:

LOGDIR="$HOME/.funkfox_logs"

Correct:

# Use repo-based logging with CRUMB_LOGS_DIR
LOGDIR="${CRUMB_LOGS_DIR}/funkfox"
mkdir -p "$LOGDIR"

Why: Repo-based logs are git-trackable, portable, and transparent.

Pitfall 2: Circular Imports

Wrong:

# In a mission script
source "${SCRIPT_DIR}/../../crumb-mission-selector.sh"

Correct:

# Only source the library
source "${SCRIPT_DIR}/../../lib/waldwaechter.sh"

Why: Mission selector is an entry point, not a library.

Pitfall 3: Bash Version Assumptions

Wrong:

# Uses Bash 4+ features
declare -A assoc_array

Correct:

# Compatible with Bash 3.2 (macOS default)
# Use arrays or alternative approaches

Why: macOS ships with Bash 3.2 by default (license reasons).

Pitfall 4: Missing API Keys

Wrong:

# Assumes API key exists
curl -H "Authorization: Bearer $OPENROUTER_API_KEY" ...

Correct:

# Check for API key first
if [[ -z "$OPENROUTER_API_KEY" ]]; then
    echo "❌ Error: OPENROUTER_API_KEY not set"
    echo "Copy .env.template to .env and add your key"
    exit 1
fi

Why: Better error messages help new users set up correctly.

Pitfall 5: Ignoring Token Budget

Wrong:

# Call API without checking budget
curl ... "$API_URL"

Correct:

# Check token budget first (if enabled)
if [[ -n "$DAILY_TOKEN_BUDGET" ]] && [[ "$DAILY_TOKEN_BUDGET" -gt 0 ]]; then
    # Check today's usage
    # Compare with budget
    # Warn or block if over budget
fi

Why: Parental controls for children's AI usage.

Pitfall 6: Not Testing on Raspberry Pi

Wrong:

# Only test on desktop with 16GB RAM

Correct:

# Test on actual target hardware
# Or simulate constraints: limit memory, slow CPU

Why: Educational system should work on affordable hardware.

Development Workflow

Quick Start for New Developers

1. Clone and setup:

   git clone <repo>
   cd CF_Zero_V1
   cp .env.template .env
   # Edit .env, add OPENROUTER_API_KEY
   

2. Explore the system:

   ./crumb-mission-selector.sh  # Main entry point
   # Choose option 9 for CrumbCrew Command Central
   # Try: crew_status, crew_help, crew_doctor
   

3. Read key files:

   • README.md - German overview
   • CLAUDE.md - This file
   • lib/waldwaechter.sh - Core integration (most important!)
   • crumbforest_roles/funkfox_zero.sh - Example character

4. Run a mission:

   bash missions/basics/fridolin.sh
   # Follow along, see how AI characters are used
   

5. Check system health:

   source lib/waldwaechter.sh
   crew_doctor  # System diagnostics
   

Testing Changes

No formal test suite - philosophy relies on:

1. Manual testing - Run missions and interact
2. Syntax validation:

   source lib/waldwaechter.sh
   crew_syntax  # Validates all bash scripts
   

3. Health checks:

   crew_doctor  # Dependencies, API keys, paths
   

4. Token logging - Verify AI interactions work

Making Changes

Before making changes:

1. Read the philosophical sections of this CLAUDE.md
2. Understand the "why" behind file-based state, transparency, etc.
3. Test on Raspberry Pi if possible (or simulate constraints)

When adding features:

1. Maintain transparency (no hidden state)
2. Keep Raspberry Pi Zero compatible
3. Use file-based state (JSON)
4. Add token tracking if using AI
5. Update this CLAUDE.md if architecture changes

When adding missions:

1. Follow metadata-driven pattern
2. Source lib/waldwaechter.sh
3. Use AI characters for teaching
4. Include interactive elements
5. Test on actual target audience (children!)

Project Maturity and Status

Version: v0.0-RC3 (Release Candidate 3) Status: Active development, production-ready for educational use Git: Clean working tree at time of this CLAUDE.md update

Recent Developments:

• RC3: Crumbblocks browser-terminal bridge
• RC3: "Dein Zeichen im Wald" UI mission (Schnippsi)
• RC3: Smart evaluation routing (clipboard → JSON → bash evaluation)
• RC3: Solar Wasserkocher mission (physics engine)
• RC0: Full 17-character roster complete

Philosophy: "Der Wald ist nie fertig - er wächst mit jeder Idee!" (The forest is never finished - it grows with every idea)

Quick Reference: Most Important Files

For maximum productivity, focus on these core files:

1. lib/waldwaechter.sh (715 lines) - Central integration, all characters + utilities
2. crumb-mission-selector.sh (1027 lines) - Main entry point, metadata parser
3. crumbforest_roles/funkfox_zero.sh - Example character (understand the pattern)
4. missions/robots/lipo_power_academy.sh - Example complex mission (8 phases, multiple characters)
5. .env.template - Configuration reference
6. README.md - User-facing documentation (German)
7. This CLAUDE.md - Architecture and development guide

Summary: What Makes This Unique

CF_Zero_V1 is not just another educational coding platform. It's unique because:

1. Character-Driven Learning - 17 distinct AI personalities, each teaching differently
2. Token Transparency as Pedagogy - "What does a question cost?" teaches mindfulness
3. File-Based Agent Memory - Characters read each other's logs for context
4. Browser-Terminal Bridge - Crumbblocks simulations export to terminal
5. Das Dreieck Framework - Structure/Flow/Balance as a teaching model
6. Raspberry Pi Zero Compatible - Runs on $15 hardware
7. Metadata-Driven - Add content without touching code
8. Dual Transparency - Track both input (questions) and output (creations)
9. Hardware-Software Integration - Teach coding through robotics projects
10. Multilingual by Default - AI responds in the language of the question

The architecture prioritizes transparency, extensibility, and pedagogical value over technical complexity. Every design decision serves the educational mission.