AI Bonzi Buddy - Desktop Companion for Linux/KDE

A modern, customizable desktop companion application for Linux with AI-powered conversation capabilities using LM Studio's local API.

Features

Core Functionality

• Transparent Overlay Window: Always-on-top companion that doesn't interfere with your work
• Sprite-based Animation System: Smooth animations for idle, walking, and talking states
• Character Pack System: Easily swap between different character appearances
• AI Integration: Connect to LM Studio for intelligent conversations
• Desktop Interaction: Click and drag to move your companion around

Building from Source

Prerequisites

• Qt6 (Core, Widgets, Network modules)
• CMake 3.16 or higher
• C++17 compatible compiler
• LM Studio (for AI features)

Build Instructions

# Build the application
./build.sh

# Or manually:
mkdir build
cd build
cmake ..
cmake --build .

Running the Application

./AIBonziBuddy

Character Pack Structure

Character packs are folders containing sprite sheets and configuration:

character-pack/
├── idle.png        # Idle animation (single frame or sprite sheet)
├── walking.png     # Walking animation sprite sheet
├── talking.png     # Talking animation sprite sheet
└── config.json     # Animation configuration and metadata

Config.json Format

{
    "name": "Character Name",
    "sprites": {
        "idle": {
            "frameWidth": 128,
            "frameHeight": 128,
            "frameCount": 1,
            "frameDuration": 100
        },
        "walking": {
            "frameWidth": 128,
            "frameHeight": 128,
            "frameCount": 4,
            "frameDuration": 150
        },
        "talking": {
            "frameWidth": 128,
            "frameHeight": 128,
            "frameCount": 2,
            "frameDuration": 200
        }
    }
}

Creating Custom Character Packs

1. Create a new folder in assets/
2. Add your sprite sheets (PNG format with transparency)
3. Create a config.json with proper frame dimensions
4. Place your character pack in the assets folder

Sprite Sheet Guidelines

• Use PNG format with alpha channel for transparency
• Arrange frames horizontally in sprite sheets
• Keep consistent dimensions across all animations
• Recommended size: 128x128 pixels per frame

Project Structure

ai-bonzi-buddy/
├── src/
│   ├── main.cpp              # Application entry point
│   ├── CompanionWindow.h/cpp # Main window with transparency
│   ├── Character.h/cpp       # Character sprite management
│   └── AnimationSystem.h/cpp # Animation state machine
├── assets/
│   └── default/              # Default character pack
│       └── config.json
├── CMakeLists.txt
└── build.sh

Technical Details

Transparency Implementation

• Uses Qt's WA_TranslucentBackground attribute
• Frameless window with Qt::FramelessWindowHint
• Always-on-top with Qt::WindowStaysOnTopHint
• Click-through capability can be toggled

Animation System

• Frame-based sprite animation
• Configurable frame rates per animation
• Smooth transitions between states
• Support for both single images and sprite sheets

Next Steps

The basic application is ready with:

• ✅ Transparent overlay window
• ✅ PNG sprite rendering with alpha channel
• ✅ Click and drag functionality
• ✅ Animation state machine
• ✅ Character pack system with JSON config

To add more features:

1. LM Studio Integration: Add HTTP client for localhost:1234 API
2. Speech Bubbles: Implement QWidget-based bubble rendering
3. Settings Dialog: Create preferences UI
4. More Characters: Add additional character packs with sprites