### Frontend Development Commands

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Commands for installing dependencies, running the development server, and performing validation/formatting checks for the frontend using npm.

```bash
# Frontend (in frontend/ directory)
npm install
npm run dev
npm run check            # TypeScript/Svelte validation
npm run lint             # ESLint (Svelte + Tailwind)
npm run lint:fix         # ESLint with auto-fix
npm run format:check     # Prettier format check
npm run format           # Prettier auto-format
```

--------------------------------

### Start Homebox Companion with Docker Compose

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Command to start the Homebox Companion service defined in your docker-compose.yml file in detached mode.

```bash
docker compose up -d
```

--------------------------------

### Environment Variables for Homebox Companion

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Example environment variables required for the Homebox Companion application. Includes API keys, model selection, and Homebox URL.

```bash
HBC_LLM_API_KEY=sk-your-key             # Required
HBC_LLM_MODEL=gpt-5-mini                # Optional (default)
HBC_LLM_API_BASE=https://...            # Optional, for proxies
HBC_HOMEBOX_URL=https://demo.homebox.software
```

--------------------------------

### Configure CORS Origins for Production

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Sets specific allowed CORS origins for production environments to enhance security. This example allows requests only from 'inventory.example.com'.

```bash
# Allow only your frontend domain
HBC_CORS_ORIGINS=https://inventory.example.com
```

--------------------------------

### Docker Compose Setup for Homebox Companion

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

This Docker Compose configuration sets up the Homebox Companion service. It requires your OpenAI API key and the URL of your Homebox instance. The service is set to restart automatically.

```yaml
#docker-compose.yml
services:
  homebox-companion:
    image: ghcr.io/duelion/homebox-companion:latest
    container_name: homebox-companion
    restart: always
    environment:
      - HBC_LLM_API_KEY=sk-your-api-key-here
      - HBC_HOMEBOX_URL=http://your-homebox-ip:7745
    ports:
      - 8000:8000
```

--------------------------------

### Initiate OIDC Login Flow

Source: https://github.com/duelion/homebox-companion/blob/main/tests/oidc_test.html

Opens a popup window to start the OIDC login process and monitors it for completion or closure. Handles potential popup blockers.

```javascript
function startOIDCFlow() {
    log('Opening OIDC login popup...');
    const oidcUrl = `${homeboxUrl}/api/v1/users/login/oidc`;
    log(`Redirect URL: ${oidcUrl}`);
    const width = 500;
    const height = 600;
    const left = (screen.width - width) / 2;
    const top = (screen.height - height) / 2;
    oidcPopup = window.open(
        oidcUrl,
        'HomeboxOIDC',
        `width=${width},height=${height},left=${left},top=${top}`
    );
    if (!oidcPopup) {
        showStatus('oidcResult', '❌ Popup blocked! Please allow popups for this site.', 'error');
        return;
    }
    showStatus('oidcResult', '⏳ Waiting for OIDC login... Check the popup window.', 'info');
    const checkInterval = setInterval(() => {
        try {
            if (oidcPopup.closed) {
                clearInterval(checkInterval);
                log('Popup was closed');
                showStatus('oidcResult', '⚠️ Popup was closed. Check the log for any captured data.', 'warning');
                return;
            }
            const popupUrl = oidcPopup.location.href;
            log(`Popup URL: ${popupUrl}`);
            if (popupUrl.includes(homeboxUrl.replace('https://', '').replace('http://', ''))) {
                log('Detected return to Homebox domain!');
                const url = new URL(popupUrl);
                const hashParams = new URLSearchParams(url.hash.substring(1));
                const queryParams = url.searchParams;
                log('URL Search Params: ' + url.search);
                log('URL Hash: ' + url.hash);
                const token = hashParams.get('token') || queryParams.get('token') || hashParams.get('access_token') || queryParams.get('access_token');
                if (token) {
                    clearInterval(checkInterval);
                    captureToken(token, 'URL Parameter');
                    oidcPopup.close();
                }
                try {
                    const cookies = oidcPopup.document.cookie;
                    if (cookies) {
                        log('Popup cookies: ' + cookies);
                    }
                } catch (e) {}
            }
        } catch (e) {}
    }, 500);
    setTimeout(() => {
        clearInterval(checkInterval);
        if (oidcPopup && !oidcPopup.closed) {
            log('Timeout waiting for OIDC response');
        }
    }, 300000);
}
```

--------------------------------

### Python Development Commands with uv

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Commands for managing Python dependencies and running scripts using uv. Use 'uv sync' to install, 'uv add' to add packages, and 'uv run' to execute commands within the virtual environment.

```bash
# Python (use uv, not pip)
uv sync                  # Install dependencies
uv add <package>         # Add dependency
uv run <command>         # Run in virtual env
```

--------------------------------

### Frontend CSS Custom Values Example

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Illustrates how to use theme() function within Svelte component styles to access Tailwind CSS tokens, ensuring consistency.

```html
 **Canvas operations**: Use `CANVAS_COLORS` from `lib/utils/canvas-colors.ts` (synced with Tailwind tokens).

 **CSS custom values**: In component `<style>` blocks, use `theme('colors.primary.500')` instead of hard-coded hex values.
```

--------------------------------

### Frontend Design System Tokens (Tailwind CSS)

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Examples of using Tailwind CSS design tokens for consistent styling in the frontend. Demonstrates correct usage for overlays, text, semantic colors, accents, and typography.

```html
| Category | ✅ Use This | ❌ Avoid |
|----------|-------------|
| **Overlays** | `bg-neutral-950/60` | `bg-black/60` |
| **Text on dark** | `text-neutral-100`, `text-neutral-300` | `text-white`, `text-white/80` |
| **Semantic colors** | `warning-*`, `success-*`, `error-*` | `amber-*`, `yellow-*`, `red-*` |
| **Accent color** | `text-accent`, `text-primary-400` | `text-cyan-400`, `text-blue-400` |
| **Typography** | `text-body-sm`, `text-caption` | `text-sm`, `text-xs` |
| **Touch targets** | `min-h-touch`, `min-w-touch` | `min-h-[44px]`, `min-w-[44px]` |
```

--------------------------------

### Build and Run Full App (PowerShell)

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Steps to build the frontend, copy it to the server's static files directory, and then run the Python server using PowerShell.

```powershell
# 1. Build frontend (from frontend/ directory)
cd frontend
npm install
npm run build

# 2. Copy build to server static files
Remove-Item -Recurse -Force ../server/static/*
Copy-Item -Recurse -Force build/* ../server/static/

# 3. Run the server (from project root)
cd ..
uv run python -m server.app
```

--------------------------------

### Run Homebox Companion with Demo Server

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Use this command to run the Homebox Companion using the public demo server. Ensure you replace 'sk-your-key' with your actual OpenAI API key.

```bash
docker run -p 8000:8000 \
  -e HBC_LLM_API_KEY=sk-your-key \
  -e HBC_HOMEBOX_URL=https://demo.homebox.software \
  ghcr.io/duelion/homebox-companion:latest
```

--------------------------------

### Configure Local LLM Server

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Set environment variables to connect Homebox Companion to a locally running LLM server. Ensure the model supports vision and function calling if using the Chat assistant.

```bash
HBC_LLM_API_KEY=any-value-works-for-local  # Just needs to be non-empty
HBC_LLM_API_BASE=http://localhost:11434     # Your local server URL
HBC_LLM_MODEL=ollama/llava:34b              # Your local model name
HBC_LLM_ALLOW_UNSAFE_MODELS=true            # Required for most local models
```

--------------------------------

### Configure Server and Logging Settings

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Sets the server bind address, port, logging level, and disables update notifications. Also configures the maximum upload file size and allowed CORS origins.

```bash
HBC_SERVER_HOST=0.0.0.0
HBC_SERVER_PORT=8000
HBC_LOG_LEVEL=INFO
HBC_DISABLE_UPDATE_CHECK=false
HBC_MAX_UPLOAD_SIZE_MB=20
HBC_CORS_ORIGINS=*

```

--------------------------------

### Pre-Commit Checklist

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

A checklist of commands to run before committing code, ensuring code quality and consistency across Python and frontend components.

```bash
1. uv run ruff check .
2. uv run ty check
3. uv run vulture --min-confidence 70 --sort-by-size
4. cd frontend
5. npm run check
6. npm run lint
7. npm run format:check
8. npm audit
```

--------------------------------

### Configure Security Rate Limits for Production

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Sets production-recommended rate limits for authentication attempts and chat messages per IP address to protect against brute-force attacks and manage LLM costs.

```bash
HBC_AUTH_RATE_LIMIT_RPM=10
HBC_CHAT_RATE_LIMIT_RPM=20
```

--------------------------------

### Configure Rate Limits for OpenAI Tier 3

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Sets API rate limits for OpenAI Tier 3, further increasing RPM and TPM values for the highest usage tiers.

```bash
HBC_RATE_LIMIT_RPM=4000
HBC_RATE_LIMIT_TPM=3200000
```

--------------------------------

### Configure Rate Limits for OpenAI Tier 2

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Sets API rate limits for OpenAI Tier 2, increasing RPM and TPM values to accommodate higher usage limits.

```bash
HBC_RATE_LIMIT_RPM=4000
HBC_RATE_LIMIT_TPM=1600000
```

--------------------------------

### Python Testing Commands

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Commands for running unit, integration, and live tests using pytest. Live tests require Docker.

```bash
# Testing
uv run pytest                 # Unit tests
uv run pytest -m integration  # Integration tests
uv run pytest -m live         # Live tests (requires Docker)
```

--------------------------------

### Configure Capture Limits

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Sets the maximum number of photos per capture session and the maximum file size per image. These are experimental settings; defaults are recommended to minimize data loss.

```bash
HBC_CAPTURE_MAX_IMAGES=30
HBC_CAPTURE_MAX_FILE_SIZE_MB=10
```

--------------------------------

### Set Image Quality for Uploads

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Controls the compression level for images uploaded to Homebox. This setting affects server-side compression during AI analysis. Use 'high' for best quality with moderate file size.

```bash
HBC_IMAGE_QUALITY=high
```

--------------------------------

### Test Password Login

Source: https://github.com/duelion/homebox-companion/blob/main/tests/oidc_test.html

Prompts the user for their Homebox username and password, then attempts to log in using the /api/v1/users/login endpoint. Captures the token if login is successful.

```javascript
async function testPasswordLogin() {
    const username = prompt('Enter Homebox username/email:');
    if (!username) return;
    const password = prompt('Enter Homebox password:');
    if (!password) return;
    log(`Testing password login for ${username}...`);
    try {
        const response = await fetch(`${homeboxUrl}/api/v1/users/login`, {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'Accept': 'application/json'
            },
            body: new URLSearchParams({
                username: username,
                password: password,
                stayLoggedIn: 'true'
            })
        });
        const data = await response.json();
        log(`Login response: ${JSON.stringify(data)}`);
        if (response.ok && data.token) {
            captureToken(data.token.replace(/^Bearer\s*/i, ''), 'Password Login');
        } else {
            showStatus('oidcResult', `❌ Login failed: ${data.error || response.status}`, 'error');
        }
    } catch (e) {
        log(`Password login error: ${e.message}`);
        showStatus('oidcResult', `❌ Error: ${e.message}`, 'error');
    }
}
```

--------------------------------

### Enable API Rate Limiting

Source: https://github.com/duelion/homebox-companion/blob/main/README.md

Enables API rate limiting and sets requests per minute (RPM) and tokens per minute (TPM). Default settings are conservative and suitable for OpenAI Tier 1. Adjust for higher tiers.

```bash
HBC_RATE_LIMIT_ENABLED=true
HBC_RATE_LIMIT_RPM=400
HBC_RATE_LIMIT_TPM=400000
HBC_RATE_LIMIT_BURST_MULTIPLIER=1.5
```

--------------------------------

### Check Homebox Status and OIDC Configuration

Source: https://github.com/duelion/homebox-companion/blob/main/tests/oidc_test.html

Fetches the status of the Homebox API and parses the OIDC configuration. Displays connection status and OIDC details.

```javascript
async function checkStatus() {
    homeboxUrl = document.getElementById('homeboxUrl').value.trim().replace(/\/$/, '');
    if (!homeboxUrl) {
        showStatus('statusResult', '❌ Please enter your Homebox URL', 'error');
        return;
    }
    log(`Checking ${homeboxUrl}/api/v1/status...`);
    try {
        const response = await fetch(`${homeboxUrl}/api/v1/status`, {
            method: 'GET',
            headers: {
                'Accept': 'application/json'
            }
        });
        if (!response.ok) {
            throw new Error(`HTTP ${response.status}`);
        }
        const data = await response.json();
        log(`Status response received: ${JSON.stringify(data, null, 2)}`);
        const oidc = data.oidc || { enabled: false };
        let statusHtml = ` <strong>✅ Connected to Homebox!</strong> <div class="results"> <div class="result-item"> <div class="result-label">OIDC Enabled</div> <div>${oidc.enabled ? '✅ Yes' : '❌ No'}</div> </div> `;
        if (oidc.enabled) {
            statusHtml += ` <div class="result-item"> <div class="result-label">Allow Local Login</div> <div>${oidc.allowLocal ? '✅ Yes' : '❌ No (OIDC Only)'}</div> </div> <div class="result-item"> <div class="result-label">Auto Redirect</div> <div>${oidc.autoRedirect ? '✅ Yes' : '❌ No'}</div> </div> <div class="result-item"> <div class="result-label">Button Text</div> <div>${oidc.buttonText || '(default)'}</div> </div> `;
        }
        statusHtml += '</div>';
        showStatus('statusResult', statusHtml, 'success');
        document.getElementById('oidcTestCard').style.display = 'block';
        if (oidc.enabled) {
            log('OIDC is enabled! You can test the OIDC flow.');
        } else {
            log('OIDC is not enabled. You can still test password login.');
        }
    } catch (error) {
        log(`Error: ${error.message}`, 'error');
        showStatus('statusResult', ` <strong>❌ Connection Failed</strong> <p style="margin-top: 0.5rem;">${error.message}</p> <p style="margin-top: 0.5rem; color: var(--muted);"> Make sure CORS is enabled or try running this from the same domain. </p> `, 'error');
    }
}
```

--------------------------------

### Python Linting and Type Checking

Source: https://github.com/duelion/homebox-companion/blob/main/AGENTS.md

Commands for linting and type checking Python code using Ruff and Ty. Includes checking for unused code with Vulture.

```bash
# Linting & Type Checking
uv run ruff check .
uv run ty check
uv run vulture --min-confidence 70 --sort-by-size
```

--------------------------------

### Handle PostMessage and URL Token

Source: https://github.com/duelion/homebox-companion/blob/main/tests/oidc_test.html

Listens for postMessage events from a popup window and checks the current page's URL parameters for a token. Captures the token if found via either method.

```javascript
window.addEventListener('message', (event) => {
    log(`Received postMessage from ${event.origin}: ${JSON.stringify(event.data)}`);
    if (event.data && event.data.token) {
        captureToken(event.data.token, 'postMessage');
        if (oidcPopup) oidcPopup.close();
    }
});

const urlParams = new URLSearchParams(window.location.search);
const hashParams = new URLSearchParams(window.location.hash.substring(1));
const tokenFromUrl = urlParams.get('token') || hashParams.get('token');
if (tokenFromUrl) {
    log('Token found in current page URL!');
    captureToken(tokenFromUrl, 'Redirect URL');
}
```

--------------------------------

### Log and Status Update Functions

Source: https://github.com/duelion/homebox-companion/blob/main/tests/oidc_test.html

Utility functions for logging messages and updating status indicators on the page. These are used throughout the companion interface.

```javascript
function log(message, type = 'info') {
    const container = document.getElementById('logContainer');
    const time = new Date().toLocaleTimeString();
    const entry = document.createElement('div');
    entry.className = 'log-entry';
    entry.innerHTML = `<span class="log-time">[${time}]</span> ${message}`;
    container.insertBefore(entry, container.firstChild);
}
function showStatus(elementId, message, type) {
    const el = document.getElementById(elementId);
    el.className = `status ${type}`;
    el.innerHTML = message;
}
```

--------------------------------

### Capture and Display OIDC Token

Source: https://github.com/duelion/homebox-companion/blob/main/tests/oidc_test.html

Receives the OIDC token from the popup, logs it, and displays it in the results section. This function is called upon successful OIDC authentication.

```javascript
function captureToken(token, source) {
    log(`🎉 Token captured from ${source}!`);
    document.getElementById('resultsCard').style.display = 'block';
    document.getElementById('resultsList').innerHTML = ` <div class="result-item"> <div class="result-label">Token Source</div> <div>${source}</div> </div> <div class="result-item"> <div class="result-label">Bearer Token</div> <pre>$
```

--------------------------------

### Capture and Test OIDC Token

Source: https://github.com/duelion/homebox-companion/blob/main/tests/oidc_test.html

Captures an OIDC token and tests its validity by calling the /api/v1/users/self endpoint. Displays the authenticated user's information if the token is valid.

```javascript
async function testToken(token) {
    log('Testing token with /api/v1/users/self...');
    try {
        const response = await fetch(`${homeboxUrl}/api/v1/users/self`, {
            headers: {
                'Authorization': `Bearer ${token}`,
                'Accept': 'application/json'
            }
        });
        if (response.ok) {
            const data = await response.json();
            log(`Token valid! User: ${JSON.stringify(data)}`);
            const userInfo = data.item || data;
            document.getElementById('resultsList').innerHTML += ` <div class="result-item"> <div class="result-label">Authenticated User</div> <div>${userInfo.name || userInfo.email || 'Unknown'}</div> </div> `;
        } else {
            log(`Token test failed: HTTP ${response.status}`);
        }
    } catch (e) {
        log(`Token test error: ${e.message}`);
    }
}
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.