# CARL Control Panel

A desktop settings UI for managing CARL (Context Augmentation & Reinforcement Layer) configuration.

**Note:** This is an optional addon. CARL works fully without this tool - it just makes managing settings easier.

## Prerequisites

- **Python 3.10+** must be installed
  - Windows: Download from [python.org](https://python.org) (check "Add to PATH")
  - macOS: `brew install python3`
  - Linux: `sudo apt install python3 python3-pip`

## Quick Start

### Windows
Double-click `launcher.pyw`

Dependencies install automatically on first run.

### macOS / Linux
```bash
python3 launcher-mac.py
```

### Build Standalone App

**Windows:**
```bash
build.bat
# Creates: dist/CARL Control Panel.exe
```

**macOS:**
```bash
./build-mac.sh
# Creates: dist/CARL Control Panel.app
```

## Architecture

```
carl-control-panel/
├── launcher.pyw      # Desktop launcher (splash, tray, pywebview)
├── launcher-mac.py   # Mac/Linux launcher
├── app.py            # Flask server (REST API)
├── api/              # Python API modules
├── templates/        # Jinja2 HTML templates
├── static/           # CSS/JS assets
├── hooks/            # Bundled CARL hooks
└── assets/           # Icons (optional)
```

The app uses a **Flask + pywebview** architecture:
- `app.py` - Flask server providing REST API endpoints
- `launcher.pyw` - Desktop launcher with splash screen and system tray
- Frontend connects via HTTP to `http://localhost:5050`

## Features

- **Multi-workspace support** - Manage multiple CARL installations
- **Toggle management** - DEVMODE, GLOBAL_STATE, domain states, etc.
- **Session overrides** - Per-session toggle overrides
- **Hooks management** - Install and wire CARL hooks
- **System tray** - Minimize to tray, quick access

## Development

Run Flask server directly for development:
```bash
python app.py
# Server runs at http://localhost:5050
```

Run with pywebview (full desktop experience):
```bash
python launcher.pyw  # Windows
python3 launcher-mac.py  # Mac/Linux
```

## Troubleshooting

**"No CARL installation found"**
- Make sure you have a `.carl/manifest` file in your workspace
- Use "Initialize CARL" to create one

**PyWebView issues on Linux**
- Install GTK: `sudo apt install python3-gi gir1.2-webkit2-4.0`

**Server won't start**
- Check `server.log` for errors
- Ensure port 5050 is available

## License

Part of the CARL system. MIT License.
