mood

Gib deiner KI ein Gesicht. mood ist ein physisches Stimmungs-Display fürs Terminal: dein LLM zeigt seine aktuelle Stimmung als lebendiges, lokal mit Stable Diffusion generiertes ASCII-Gesicht — proaktiv, während ihr zusammenarbeitet.

<img src="docs/hero.png" width="560" alt="mood — focused, ready to dig into network config">

Unter der Haube: Eine Emotion (z.B. smiling) wird in einen Prompt eingesetzt, auf der GPU ein Bild generiert und als ASCII-Helligkeitsgradient im Terminal angezeigt. Per MCP ruft die KI das Tool feel(emotion) selbst auf, wann immer sich ihre Stimmung ändert — wie ein Mensch unwillkürlich das Gesicht verzieht.

Schnellstart

Voraussetzung: uv und eine GPU — NVIDIA (Linux, CUDA) oder Apple Silicon (macOS, MPS). Ohne GPU läuft es auf der CPU, aber sehr langsam. macOS-Details siehe unten.

./run.sh

Startet das Stimmungs-Display (Listener auf Port 8765) mit den Standard-Settings. Beim ersten Mal wird die Umgebung eingerichtet und das Modell von HuggingFace geladen (mit sichtbarem Fortschritt). Dann ist das Display bereit.

Damit deine KI es ansteuert, die MCP-Bridge in Claude Code registrieren (siehe MCP in Claude Code):

./install-mcp.sh

Ab jetzt zeigt die KI ihre Stimmung von selbst auf dem Display. feel(emotion) gibt im Chat nur "ok" zurück (das Bild geht aufs Display, nicht in die Konversation).

Selbst ausprobieren

echo "laughing" | nc 127.0.0.1 8765      # Emotion ans laufende Display schicken
./run.sh "a red sports car"              # einmaliges Bild (kein '::' -> One-Shot)

Weitere Stimmungen:

<img src="docs/demo.png" width="300" alt="relieved and laughing"> <img src="docs/demo2.png" width="300" alt="very happy">

Aussehen anpassen

Das Gesicht entsteht aus einem Prompt-Template mit :: als Platzhalter für die Emotion. Standard ist ein Vault-Boy-Stil (Fallout). Alles per Env überschreibbar (siehe .env.example, eine .env wird automatisch geladen):

Variable	Default	Wirkung
MOOD_PROMPT	girl, :: face, retro poster style, …	Prompt-Template (:: = Emotion)
MOOD_MODEL	sd15	sdxl, sd15, flux, qwen
MOOD_LORA	vaultboy	LoRA-Kurzname / Pfad ('' = keine)
MOOD_RAMP	ink	ASCII-Rampe: ink, acid, blocks, minimal, …
MOOD_COLOR	green	mono, Akzent (green/amber/cyan/white) oder palette (echte Bildfarben, auf 8 klare ANSI-Farben reduziert)
MOOD_MODELS_ROOT	–	lokale Modelle bevorzugen statt HF-Download

Volle Optionsliste: ./run.sh --help. CLI-Flags überschreiben Env überschreiben .env.

Mit --color palette werden statt eines Akzents echte Bildfarben gerendert (auf ein kleines, klares Set reduziert):

<img src="docs/palette.png" width="420" alt="--color palette — happy, solved the issue">

--color palette · „happy, solved the issue"

macOS / Apple Silicon

Läuft nativ auf M1/M2/M3 über Apples MPS-Backend — gleiche Codebasis wie Linux, kein CUDA und kein Docker nötig:

# uv installieren (falls noch nicht vorhanden):
curl -LsSf https://astral.sh/uv/install.sh | sh

./run.sh

uv sync zieht automatisch das passende torch (mit MPS) von PyPI — der CUDA-Index greift nur unter Linux. Die App erkennt das Gerät selbst (CUDA → MPS → CPU). Modelle landen im HuggingFace-Cache (~/.cache/huggingface).

• Die erste Generierung lädt das Modell (mehrere GB); danach wenige Sekunden pro Bild (je nach Chip). MPS ist langsamer als eine dedizierte NVIDIA-GPU, aber gut nutzbar.
• nc ist vorinstalliert; MCP-Bridge (./install-mcp.sh) funktioniert identisch.
• Docker bringt auf dem Mac nichts: Container haben dort keinen Zugriff auf die Apple-GPU (Metal/MPS) — nur CPU, also viel zu langsam. Auf dem Mac immer ./run.sh nativ nutzen. Das Docker-Setup unten ist ausschließlich für Linux + NVIDIA.

MCP in Claude Code

./install-mcp.sh

Registriert die Bridge (Tool feel) mit den richtigen Pfaden — funktioniert auf Linux und macOS. Danach Claude Code neu starten und ./run.sh laufen lassen.

Per Docker

Braucht NVIDIA-Treiber + nvidia-container-toolkit. Modelle landen auf dem Host in ./models und bleiben erhalten.

docker compose build
docker compose up                         # Display/Listener auf :8765
docker compose run --rm mood "a cat"      # einmaliges Bild

Modi

• Display/Listener (Default, Prompt mit ::): hält die Pipeline, jede gesendete Emotion wird gerendert. CTRL-C beendet.
• One-Shot (Prompt ohne ::): ein Bild, dann Ende.
• MCP-Bridge (-m): leitet feel(emotion) an den Listener weiter; lädt selbst kein Modell → nur eine Pipeline im VRAM.

* flux/qwen sind experimentell (große/gated Repos).

Lizenz

MIT — siehe LICENSE.