carl-control-panel 1.0.39

Context Augmentation & Reinforcement Layer - Desktop control panel for Claude Code

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)

pip install carl-control-panel

Then run:

carl

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

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

• Windows: CARL.Control.Panel.exe
• macOS: CARL.Control.Panel.app

Option 3: Run from Source

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 (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:

   python -m carl_control_panel
   

2. Or add to PATH permanently (PowerShell as Admin):

   $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):

   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:

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:

pip install --upgrade carl-control-panel

---

pip Commands Reference

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

   rm -rf dist/ build/ *.egg-info/
   python -m build
   

3. Upload to PyPI:

   python -m twine upload dist/*
   # Enter PyPI API token when prompted
   

4. Verify:

   pip install carl-control-panel==X.Y.Z --no-cache-dir
   carl
   

Testing Locally Before Publishing

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

build.bat
# Output: dist/CARL Control Panel.exe

macOS:

./build-mac.sh
# Output: dist/CARL Control Panel.app

Running Flask Server Directly (Development)

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