# 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.

---

## Installation

### Option 1: pip install (Recommended)

```bash
pip install carl-control-panel
```

Then run:
```bash
carl
```

**If `carl` command not found** (common on Windows), use one of these alternatives:

```bash
# Option A: Run as Python module
python -m carl_control_panel

# Option B: Add Python Scripts to PATH (Windows)
# The install location is usually: %APPDATA%\Python\Python3XX\Scripts
# Add this to your system PATH, then restart terminal

# Option C: Use pipx (handles PATH automatically)
pip install pipx
pipx install carl-control-panel
carl
```

### Option 2: Standalone Executable

Download from [Releases](https://github.com/ChristopherKahler/claude-code-carl/releases):
- **Windows:** `CARL.Control.Panel.exe`
- **macOS:** `CARL.Control.Panel.app`

### Option 3: Run from Source

```bash
git clone https://github.com/ChristopherKahler/claude-code-carl.git
cd carl-control-panel
pip install -r requirements.txt
python launcher.pyw  # Windows
python3 launcher-mac.py  # macOS/Linux
```

---

## Requirements

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

---

## Troubleshooting

### "carl" command not recognized (Windows)

Python Scripts folder isn't in your PATH. Solutions:

1. **Use the module syntax instead:**
   ```bash
   python -m carl_control_panel
   ```

2. **Or add to PATH permanently** (PowerShell as Admin):
   ```powershell
   $scriptsPath = "$env:APPDATA\Python\Python312\Scripts"
   [Environment]::SetEnvironmentVariable("PATH", $env:PATH + ";$scriptsPath", "User")
   ```
   Then restart your terminal.

3. **Or use pipx** (recommended for CLI tools):
   ```bash
   pip install pipx
   pipx install carl-control-panel
   ```

### "No CARL installation found"

- Make sure you have a `.carl/manifest` file in your workspace
- Click "Browse Existing" to select a folder with existing CARL setup
- Or click "Initialize CARL" to create a new installation

### App opens but no styling (raw HTML)

- Close any other instances of the app running
- Kill Python processes: `taskkill /F /IM python.exe` (Windows)
- Reinstall: `pip uninstall carl-control-panel -y && pip install carl-control-panel --no-cache-dir`

### PyWebView issues on Linux

Install GTK dependencies:
```bash
sudo apt install python3-gi gir1.2-webkit2-4.0
```

### Server won't start / Port in use

- Check if port 5050 is already in use
- Check `server.log` in the app directory for errors
- Try killing existing Python processes

### Update available but I'm on latest version

If the update banner shows incorrectly, upgrade to the latest version:
```bash
pip install --upgrade carl-control-panel
```

---

## pip Commands Reference

```bash
# Install latest
pip install carl-control-panel

# Install specific version
pip install carl-control-panel==1.0.14

# Upgrade to latest
pip install --upgrade carl-control-panel

# Fresh install (bypass cache)
pip install carl-control-panel --no-cache-dir

# Reinstall clean
pip uninstall carl-control-panel -y && pip install carl-control-panel --no-cache-dir

# Check installed version
pip show carl-control-panel

# Uninstall
pip uninstall carl-control-panel
```

---

## Features

- **Multi-workspace support** - Manage multiple CARL installations
- **Domain management** - Toggle domains on/off, edit rules
- **Session overrides** - Per-session toggle overrides
- **Hooks management** - Install and configure CARL hooks
- **Addon system** - Install domain packs and command sets
- **Auto-updates** - Notifies when new versions available
- **System tray** - Minimize to tray, quick access

---

## Development

### Project Structure

```
carl-control-panel/
├── carl_control_panel/       # Main package (pip install target)
│   ├── __init__.py           # Package version
│   ├── __main__.py           # Enables: python -m carl_control_panel
│   ├── main.py               # Entry point
│   ├── app.py                # Flask server (REST API)
│   ├── api/                  # Python API modules
│   │   ├── updater.py        # Version checking (APP_VERSION here)
│   │   ├── addons.py         # Addon management
│   │   └── ...
│   ├── templates/            # Jinja2 HTML templates
│   ├── static/               # CSS/JS assets
│   ├── hooks/                # Bundled CARL hooks
│   └── assets/               # Icons
├── launcher.pyw              # Standalone Windows launcher
├── launcher-mac.py           # Standalone Mac/Linux launcher
├── pyproject.toml            # Package config + version
└── requirements.txt          # Dev dependencies
```

### Version Management

**IMPORTANT:** Version must be updated in THREE places before release:

| File | Variable | Example |
|------|----------|---------|
| `pyproject.toml` | `version = "X.Y.Z"` | `version = "1.0.14"` |
| `carl_control_panel/__init__.py` | `__version__ = "X.Y.Z"` | `__version__ = "1.0.14"` |
| `carl_control_panel/api/updater.py` | `APP_VERSION = "X.Y.Z"` | `APP_VERSION = "1.0.14"` |

If these get out of sync, the app will incorrectly show "Update available" to users.

### Publishing to PyPI

1. **Update version** in all 3 files (see above)

2. **Clean and build:**
   ```bash
   rm -rf dist/ build/ *.egg-info/
   python -m build
   ```

3. **Upload to PyPI:**
   ```bash
   python -m twine upload dist/*
   # Enter PyPI API token when prompted
   ```

4. **Verify:**
   ```bash
   pip install carl-control-panel==X.Y.Z --no-cache-dir
   carl
   ```

### Testing Locally Before Publishing

```bash
# Install in editable mode
pip install -e .

# Run
carl
# or
python -m carl_control_panel

# Test specific scenarios:
# - Fresh install (no existing CARL)
# - Connecting to existing workspace
# - Addon preview/install
# - Update banner behavior
```

### Build Standalone Executables

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

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

### Running Flask Server Directly (Development)

```bash
cd carl_control_panel
python app.py
# Server at http://localhost:5050
```

---

## Architecture

The app uses **Flask + pywebview**:

- `app.py` - Flask server providing REST API endpoints
- `main.py` - pywebview wrapper (native desktop window)
- `launcher.pyw` - Standalone launcher with splash screen and system tray
- Frontend connects via HTTP to `http://localhost:5050`

---

## License

MIT License
