hyprchan 0.1.0

An anime girl that lives in your Hyprland and chills.

🌌 HyprAI OS: Hyprchan

The homeostatic system companion that lives in your Hyprland workspace.

---

Hyprchan is a homeostatic system entity driven by a continuous kernel loop, multimodal perception, and a layered memory stack. She observes your workspaces, listens to your voice, and reacts to your presence with dynamic mood shifts and pixel-art animations.

Quick Start • Features • Architecture • Commands

---

📸 Visuals

Live Rich TUI with telemetry and memory snapshots.

Animated Hyprland overlay with tool-calling capabilities.

---

🚀 Quick Start

Getting Hyprchan running is simple. Just install and run the setup wizard.

1. Installation

pip install hyprchan

2. Setup Wizard

Run the interactive setup to configure your LLM provider, memory (Postgres/Redis), and system services.

hyprchan wizard setup

3. Launch the TUI

Once setup is complete, wake her up and start chatting:

hyprchan tui

---

✨ Features

• 🧠 Layered Memory Stack: Brain-inspired architecture with Short-Term (Redis), Long-Term (Postgres + pgvector), and Working Memory.
• 🌙 Sleep & Dreaming: Automatically distills events into semantic facts during consolidation cycles. She literally dreams about your interactions.
• 🎭 Dynamic Mood Dynamics: Internal scalars (valence, energy, fatigue) drive her personality. Sustained interaction or rudeness shifts her stance in real-time.
• 👁️ Multimodal Perception:
  • Vision: Webcam face/motion detection and periodic desktop snapshots.
  • Audio: Continuous speech-to-text via Faster-Whisper with auto-language detection.
  • OS: Monitors Hyprland workspace switches and window focus events.
• 🎨 LLM-Driven Animations: The assistant can trigger poses (idle, depressed, sleeping) and move herself across your screen using custom tools.

---

🏗️ Architecture

Hyprchan operates on a Continuous Kernel Loop where perception preempts cognition.

The Perception-to-Mood Pipeline

1. Controllers: Emit raw OS/Voice/Vision events.
2. Toggle Detector: Filters high-frequency "noise" from actual activity.
3. Activity Detector: Calculates macro-pressure on her attention.
4. Mood Engine: Updates internal scalars based on interaction quality ($d$ delta) and phase fatigue.
5. Logit Bias: Mood scalars are projected into token-level biases, subtly altering her speech patterns.

---

💻 CLI Commands

Hyprchan comes with a powerful CLI for management and interaction.

Command	Description
hyprchan wizard setup	Launches the interactive configuration master.
hyprchan tui	Opens the live Rich terminal interface.
hyprchan serve	Starts the FastAPI backend daemon.
hyprchan extensions	Manage built-in extensions (Hyprgram, HyprX).
hyprchan status	Check the health of the kernel and perception services.

---

_{Built with the Ascender Framework. Maintained by Ascender Team and Hyprland Community Enthusiasts.}