# Development Guide

This document provides detailed information for developers who want to understand, modify, or extend the HA Vibecode Agent.

## 🛠️ Development and Testing on Home Assistant

The **Home Assistant Vibecode Agent** is designed to run *on* your Home Assistant instance.  
If you’re working on new features or bugfixes, you’ll often want to test your changes from a specific Git branch directly on the device, before they are merged into `main`.

Below is one way to do that using a local add-on. If you know a better flow for your environment, PRs are very welcome 🙂

---

### Prerequisites

- Home Assistant **OS** or **Supervised** (i.e. with the Add-on system and Supervisor).
- The **Advanced SSH & Web Terminal** add-on installed and configured.
  - In your user profile, enable **Advanced mode**.
  - In the SSH & Web Terminal add-on settings, disable **Protection mode** so the terminal can access the full filesystem.
- (Optional but recommended) Uninstall or stop the “release” version of the Vibecode Agent add-on if you already installed it from the default repository, to avoid confusion between the store and local versions.

---

### 1. Clone the repository as a local add-on

1. Open **Advanced SSH & Web Terminal** from the Home Assistant sidebar.
2. Create the local add-ons directory if it doesn’t exist yet:

   ```bash
   mkdir -p /addons/local
   ```

3. Change into that directory and clone your fork / the main repository:

   ```bash
   cd /addons/local
   git clone https://github.com/Coolver/home-assistant-vibecode-agent.git
   ```

4. Switch to the branch you want to test (for example):

   ```bash
   cd home-assistant-vibecode-agent
   git checkout your-feature-branch
   ```

At this point, your add-on files live under:

```text
/addons/local/home-assistant-vibecode-agent
```

Home Assistant will treat this as a **local add-on**.

---

### 2. Install the local version of the Vibecode Agent

1. In the Home Assistant UI, go to  
   **Settings → Add-ons → Add-on Store**.
2. Click the **⋮** menu in the top-right and choose **Reload**.
3. After reload, you should see a **“Local add-ons”** section (or similar), where a local copy of **Home Assistant Vibecode Agent** will appear.
4. Open it, click **Install**, then **Start** (and enable “Start on boot” if needed).

You are now running the add-on directly from your checked-out branch in `/addons/local/vibecode-agent`.

---

### 3. Updating the code from your branch

When you make further changes to your branch and push them to GitHub, you’ll want to pull those updates onto your Home Assistant instance and rebuild the add-on.

1. Open **Advanced SSH & Web Terminal** again and run:

   ```bash
   cd /addons/local/home-assistant-vibecode-agent
   git pull
   ```

   This will pull the latest commits from your branch.

2. Then, in the Home Assistant UI, go to:  
   **Settings → Add-ons → Home Assistant Vibecode Agent**  
   (make sure you’re opening the **local** version).

3. Click **Rebuild** (if available) and **Start** the add-on to apply the new code.

After rebuild/restart, the add-on will run with the latest changes from your branch.

---

This workflow lets you iterate on the Vibecode Agent locally on the actual Home Assistant device, while keeping your development flow branch-based and fully under version control.



## 📁 Project Structure

```
home-assistant-vibecode-agent/
├── config.yaml              # Add-on configuration
├── Dockerfile               # Container definition
├── run.sh                   # Startup script
├── requirements.txt         # Python dependencies
├── app/
│   ├── main.py             # FastAPI application
│   ├── auth.py             # API authentication
│   ├── ingress_panel.py    # Web UI panel
│   ├── api/                # API endpoints
│   │   ├── files.py        # File operations
│   │   ├── entities.py     # Entity states
│   │   ├── helpers.py      # Helper management
│   │   ├── automations.py  # Automation CRUD
│   │   ├── scripts.py      # Script CRUD
│   │   ├── system.py       # System operations
│   │   ├── backup.py       # Git versioning
│   │   ├── logs.py         # Log access
│   │   ├── addons.py       # Add-on management
│   │   ├── hacs.py         # HACS integration
│   │   ├── lovelace.py     # Dashboard management
│   │   ├── themes.py       # Theme management
│   │   ├── logbook.py      # Logbook entries
│   │   └── ai_instructions.py # AI guidance docs
│   ├── services/           # Business logic
│   │   ├── ha_client.py    # HA REST API client
│   │   ├── ha_websocket.py # HA WebSocket client
│   │   ├── supervisor_client.py # Supervisor API
│   │   ├── file_manager.py # File operations
│   │   └── git_manager.py  # Git versioning
│   ├── models/             # Pydantic models
│   │   └── schemas.py
│   ├── utils/              # Utilities
│   │   ├── logger.py       # Logging setup
│   │   └── yaml_editor.py  # YAML manipulation
│   ├── templates/          # HTML templates
│   │   └── ingress_panel.html
│   └── ai_instructions/    # AI agent guidance
├── tests/                  # Test suites
├── CHANGELOG.md
└── README.md
```

---

## 📚 API Documentation

### Interactive Documentation

Once the agent is running, access interactive API documentation:

- **Swagger UI:** `http://host:8099/docs`
- **ReDoc:** `http://host:8099/redoc`

### API Endpoints

#### Files API (`/api/files`)

Manage configuration files in the Home Assistant `/config` directory.

```bash
# List files
GET /api/files/list?directory=&pattern=*.yaml

# Read file
GET /api/files/read?path=configuration.yaml

# Write file
POST /api/files/write
{
  "path": "automations.yaml",
  "content": "...",
  "create_backup": true
}

# Append to file
POST /api/files/append
{
  "path": "scripts.yaml",
  "content": "\nmy_script:\n  ..."
}

# Delete file
DELETE /api/files/delete?path=old_file.yaml

# Parse YAML
GET /api/files/parse_yaml?path=configuration.yaml
```

#### Entities API (`/api/entities`)

Query Home Assistant entities and their states.

```bash
# List all entities
GET /api/entities/list

# Filter by domain
GET /api/entities/list?domain=climate

# Search entities
GET /api/entities/list?search=bedroom

# Get specific entity state
GET /api/entities/state/climate.bedroom_trv_thermostat

# List all services
GET /api/entities/services

# Call a Home Assistant service
POST /api/entities/call_service
{
  "domain": "light",
  "service": "turn_on",
  "target": {"entity_id": "light.living_room"},
  "service_data": {"brightness": 255}
}

# Rename an entity
POST /api/entities/rename
{
  "old_entity_id": "climate.old_name",
  "new_entity_id": "climate.new_name"
}
```

#### Helpers API (`/api/helpers`)

Create and manage input helpers (input_boolean, input_text, input_number, etc.).

```bash
# Create helper
POST /api/helpers/create
{
  "domain": "input_boolean",
  "entity_id": "my_switch",
  "name": "My Switch",
  "config": {
    "icon": "mdi:toggle-switch",
    "initial": false
  }
}

# Delete helper
DELETE /api/helpers/delete/input_boolean.my_switch?commit_message=Remove helper
```

#### Automations API (`/api/automations`)

Manage Home Assistant automations.

```bash
# List automations
GET /api/automations/list

# Create automation
POST /api/automations/create
{
  "id": "my_automation",
  "alias": "My Automation",
  "trigger": [...],
  "action": [...],
  "commit_message": "Add automation: My Automation"
}

# Delete automation
DELETE /api/automations/delete/my_automation?commit_message=Remove automation
```

#### Scripts API (`/api/scripts`)

Manage Home Assistant scripts.

```bash
# List scripts
GET /api/scripts/list

# Create script
POST /api/scripts/create
{
  "entity_id": "my_script",
  "alias": "My Script",
  "sequence": [...],
  "commit_message": "Add script: My Script"
}

# Delete script
DELETE /api/scripts/delete/my_script?commit_message=Remove script
```

#### System API (`/api/system`)

System-level operations for Home Assistant.

```bash
# Reload component
POST /api/system/reload?component=automations
# Components: automations, scripts, templates, core, all

# Check configuration
POST /api/system/check_config

# Get HA config
GET /api/system/config

# Restart HA (⚠️ use carefully!)
POST /api/system/restart
```

#### Backup API (`/api/backup`)

Git versioning and rollback operations.

```bash
# Create backup (commit)
POST /api/backup/commit
{
  "message": "Before climate control installation"
}

# Get backup history
GET /api/backup/history?limit=20

# Rollback to commit (by hash)
POST /api/backup/rollback/{commit_hash}

# Rollback to commit (by body)
POST /api/backup/rollback
{
  "commit_hash": "a1b2c3d4"
}

# Get diff
GET /api/backup/diff
GET /api/backup/diff?commit1=a1b2c3d4

# Create checkpoint (start of user request)
POST /api/backup/checkpoint?user_request=Create theme with dark blue header

# End checkpoint (re-enable auto-commits)
POST /api/backup/checkpoint/end

# Manual cleanup of old commits
POST /api/backup/cleanup?delete_backup_branches=true

# Restore files from commit
POST /api/backup/restore
{
  "commit_hash": "a1b2c3d4",
  "file_patterns": ["*.yaml", "configuration.yaml"]
}
```

#### Logs API (`/api/logs`)

Access agent logs.

```bash
# Get agent logs
GET /api/logs/?limit=100
GET /api/logs/?level=ERROR

# Clear logs
DELETE /api/logs/clear
```

#### Add-ons API (`/api/addons`)

Manage Home Assistant add-ons via Supervisor API.

```bash
# List ALL add-ons from store (full catalog)
GET /api/addons/store

# List available add-ons (installed and available)
GET /api/addons/available

# List installed add-ons only
GET /api/addons/installed

# Get add-on info
GET /api/addons/{slug}/info

# Get add-on logs
GET /api/addons/{slug}/logs?lines=100

# Install add-on
POST /api/addons/{slug}/install

# Uninstall add-on
POST /api/addons/{slug}/uninstall

# Start/stop/restart add-on
POST /api/addons/{slug}/start
POST /api/addons/{slug}/stop
POST /api/addons/{slug}/restart

# Update add-on
POST /api/addons/{slug}/update

# Get add-on configuration options
GET /api/addons/{slug}/options

# Set add-on configuration options
POST /api/addons/{slug}/options
{
  "option1": "value1",
  "option2": "value2"
}

# List add-on repositories
GET /api/addons/repositories

# Add custom repository
POST /api/addons/repositories/add
{
  "repository_url": "https://github.com/hassio-addons/repository"
}
```

#### HACS API (`/api/hacs`)

Manage HACS (Home Assistant Community Store) integrations.

```bash
# Check HACS status
GET /api/hacs/status

# Install HACS
POST /api/hacs/install

# Uninstall HACS
POST /api/hacs/uninstall

# List all repositories
GET /api/hacs/repositories

# Search repositories
GET /api/hacs/search?query=xiaomi&category=integration

# Install repository
POST /api/hacs/install_repository?repository=AlexxIT/XiaomiGateway3&category=integration

# Get repository details
GET /api/hacs/repository/{repository_id}

# Update all repositories
POST /api/hacs/update_all
```

#### Themes API (`/api/themes`)

Manage Home Assistant themes.

```bash
# List all themes
GET /api/themes/list

# Get theme content
GET /api/themes/get?theme_name=nice_dark

# Create new theme
POST /api/themes/create
{
  "theme_name": "my_theme",
  "theme_config": {
    "primary-color": "#ffb74d",
    "accent-color": "#ffb74d"
  }
}

# Update existing theme
PUT /api/themes/update
{
  "theme_name": "my_theme",
  "theme_config": {
    "primary-color": "#0000ff"
  }
}

# Delete theme
DELETE /api/themes/delete?theme_name=my_theme

# Reload themes
POST /api/themes/reload

# Check if themes are configured
GET /api/themes/check_config
```

#### Lovelace API (`/api/lovelace`)

Manage Lovelace dashboards.

```bash
# Analyze entities for dashboard generation
GET /api/lovelace/analyze

# Preview current dashboard configuration
GET /api/lovelace/preview

# Apply dashboard configuration
POST /api/lovelace/apply
{
  "dashboard_config": {...},
  "filename": "ai-dashboard.yaml",
  "create_backup": true,
  "register_dashboard": true
}

# Delete dashboard
DELETE /api/lovelace/delete/{filename}
```

#### Logbook API (`/api/logbook`)

Query Home Assistant logbook entries.

```bash
# Get logbook entries
GET /api/logbook/?limit=100
GET /api/logbook/?start_time=2025-12-01T00:00:00Z&end_time=2025-12-07T23:59:59Z
GET /api/logbook/?lookback_minutes=120
GET /api/logbook/?entity_id=automation.my_automation
GET /api/logbook/?domains=automation,script
GET /api/logbook/?event_types=automation_triggered,script_started
GET /api/logbook/?search=motion
```

---

## 🔐 Authentication

All API endpoints (except `/api/health`) require authentication.

### Agent Key Authentication

The add-on uses **Agent Key** authentication for external clients:

1. Agent Key is auto-generated on first start
2. Get your Agent Key from **Web UI** (Settings → Add-ons → HA Vibecode Agent → Open Web UI)
3. Include in requests as Bearer token

### Request Format

Add the `Authorization` header to all requests:

```
Authorization: Bearer YOUR_AGENT_KEY
```

**Example with curl:**

```bash
curl -H "Authorization: Bearer YOUR_AGENT_KEY" \
     http://localhost:8099/api/entities/list
```

### Internal Operations

The add-on automatically uses the **Supervisor Token** for Home Assistant API operations when running as an add-on. No manual configuration needed.

---

## 🏗️ Architecture Overview

### Core Components

1. **FastAPI Application** (`app/main.py`)
   - Main application entry point
   - Routes configuration
   - Middleware setup

2. **API Endpoints** (`app/api/`)
   - RESTful API endpoints
   - Request/response validation using Pydantic
   - Error handling

3. **Services** (`app/services/`)
   - Business logic layer
   - Home Assistant API clients
   - File and Git management

4. **Models** (`app/models/`)
   - Pydantic schemas for request/response validation
   - Data models

### Key Design Decisions

- **Separation of Concerns**: API endpoints are thin, business logic in services
- **Type Safety**: Pydantic models for all API interactions
- **Error Handling**: Consistent error responses across all endpoints
- **Git Versioning**: Automatic commits with meaningful messages
- **Security**: Path validation, authentication, and audit logging

---

For more information, see [README.md](README.md) and [CONTRIBUTING.md](CONTRIBUTING.md).