─── B ───

The Soul-Wired Desktop Companion

B is not just an AI : he is a digital lifeform designed to live on your desktop. Built with a soul-first architecture, B observes your workflow, listens with neural precision, and interacts through a high-performance, glassmorphic overlay.

Explore the Vision • Architecture • Getting Started • Contributing • Privacy

Demo

B in action - watch him observe, think, and respond.

The Vision

Traditional assistants wait for a command. B waits for a moment.

B is designed as a proactive desktop companion. Using a 60fps event-driven central nervous system, B synchronizes his emotional state with your environment. He sees your screen semantically, tracks your active focus, and intervenes only when he has something truly valuable to contribute.

• Silent by Default : B respects your deep work state.
• Emotionally Aware : A complex internal state machine drives expressions and curiosity.
• Agentic Autonomy : B doesn't just respond; he thinks, wonders, and observes.

Architecture Overview

B is built on a centralized asynchronous pub/sub event bus : the EventBus. Every module communicates exclusively through this bus. No module knows about any other module. This strict decoupling makes the system testable, maintainable, and resilient.

flowchart TB
    subgraph P["Perception Layer"]
        WT["WindowTracker"]
        SS["SemanticSensor"]
        VS["VisionSensor OCR"]
    end

    subgraph C["Cognitive Layer"]
        CE["CognitiveEngine"]
        SM["StateMachine"]
        AE["AutonomyEngine"]
    end

    subgraph O["Output Layer"]
        VE["VoiceEngine"]
        FR["FaceRenderer"]
        CB["ChatBubble"]
        KE["KinematicsEngine"]
    end

    subgraph I["Core Infrastructure"]
        EB["EventBus"]
    end

    WT -- "active_window_changed" --> EB
    SS -- "context_updated" --> EB
    VS -- "context_updated" --> EB
    EB -- "context_updated" --> CE
    EB -- "tick" --> SM
    EB -- "tick" --> KE
    CE -- "b_spoke" --> EB
    EB -- "b_spoke" --> VE
    EB -- "b_spoke" --> FR
    EB -- "b_spoke" --> CB
    CE -- "b_move_request" --> EB
    EB -- "b_move_request" --> KE
    AE -- "trigger_proactive_thought" --> EB
    EB -- "trigger_proactive_thought" --> CE

System Workflow

The data flows through B in a deterministic pipeline: Perception → Cognition → Expression.

sequenceDiagram
    participant WT as WindowTracker
    participant SS as SemanticSensor
    participant VS as VisionSensor
    participant CE as CognitiveEngine
    participant VE as VoiceEngine
    participant FR as FaceRenderer

    WT->>SS: active_window_changed
    activate SS
    SS->>SS: UIA Tree Walk
    alt Extraction Success
        SS->>CE: context_updated
    else Failure / Cooldown
        SS->>VS: semantic_extraction_failed
        VS->>VS: OCR Capture
        VS->>CE: context_updated
    end
    deactivate SS

    CE->>CE: LLM Inference
    CE->>VE: b_spoke (Text + Emotion)
    activate VE
    VE->>VE: TTS + DSP Vocoder
    VE->>FR: speaking_start
    VE->>VE: Audio Output
    VE->>FR: speaking_end
    deactivate VE
    CE->>FR: b_move_request (Spatial)

Internal Module Structure

Core Infrastructure

Perception Layer (Sensors)

Cognitive Layer (The Brain)

Output Layer (Expression)

Data Flow

flowchart LR
    subgraph Input["Input"]
        A["User Types"]
        B["User Speaks"]
        C["Screen Changes"]
    end

    subgraph Process["Processing"]
        D["EventBus"]
        E["CognitiveEngine"]
        F["StateMachine"]
    end

    subgraph Output["Output"]
        G["FaceRenderer"]
        H["VoiceEngine"]
        I["ChatBubble"]
        J["Kinematics"]
    end

    A -- types --> D
    B -- speaks --> D
    C -- changes --> D
    D -- routes --> E
    E -- drives --> F
    F -- animates --> G
    F -- speaks --> H
    F -- displays --> I
    E -- moves --> J

Request Lifecycle

stateDiagram-v2
    [*] --> Idle
    Idle --> Listening : user_spoke / voice detected
    Listening --> Thinking : 1.2s delay
    Thinking --> Streaming : first token received
    Streaming --> Speaking : sentence_ready
    Speaking --> Streaming : next sentence
    Streaming --> Idle : [SILENCE] / end of response
    Speaking --> Idle : finished_speaking + linger
    Idle --> Proactive : autonomy trigger
    Proactive --> Thinking : context available
    Proactive --> Idle : no context / silence

Project Structure

B/
├── main.py                  # Entry point : boot sequence
├── core/
│   └── bus.py               # EventBus : central nervous system
├── brain/
│   ├── llm.py               # CognitiveEngine : LLM inference
│   ├── soul.py              # StateMachine : emotions & stream buffer
│   ├── autonomy_loop.py     # AutonomyEngine : proactive thought
│   ├── context.py           # Context management
│   └── work_mode.py         # Work mode prompt templates
├── vision/
│   ├── semantic.py          # SemanticSensor : UIA extraction
│   └── mss_capture.py       # VisionSensor : OCR fallback
├── sensors/
│   └── window_tracker.py    # WindowTracker : focus detection
├── audio/
│   ├── speaker.py           # VoiceEngine : TTS + DSP
│   └── ears.py              # EarsSensor : STT
├── physics/
│   └── kinematics.py        # KinematicsEngine : movement
├── ui/
│   ├── overlay.py           # WindowManager : transparent overlay
│   ├── face.py              # FaceRenderer : 60fps face
│   ├── chat.py              # ChatBubble : text overlay
│   ├── input_box.py         # InputBox : text input
│   ├── expressions.p