clawbridge: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What is ClawBridge?

ClawBridge is a desktop and browser automation agent with a web dashboard. It orchestrates three AI-powered engines (browser-use, computer-use, OpenClaw) behind a FastAPI server with a WebSocket-driven chat UI. BYOK (bring your own key) — all LLM API keys stay local.

Development Model: Monolith-First

clawbridge.py (~12,900 lines) is the single-file monolith and the only active development target. All changes go here first. It contains the full application: FastAPI routes, engine implementations, dashboard HTML/JS, safety system, personality manager, task orchestrator, SQLite persistence, and inline CSS/JS.

clawbridge/ is a modular package that mirrors the monolith's logic split across files. It exists for reference and testing but lags behind the monolith. The test suite (tests/) imports from the package, not the monolith.

clawbridge_mcp.py is a standalone MCP server that proxies to the monolith's REST API. It has no shared code with the monolith — it's a thin HTTP client wrapper.

Commands

# Run the server (primary way)
python clawbridge.py
# Dashboard at http://localhost:8765

# Run with Docker
docker-compose up

# Install dev dependencies
pip install -r requirements-dev.txt

# Run all tests (unit + integration, against the package)
pytest

# Run a single test file
pytest tests/unit/test_safety.py

# Run a single test by name
pytest tests/unit/test_safety.py -k "test_scan_detects_aws_key"

# Run with coverage
pytest --cov=clawbridge

# Smoke tests (requires running server on :8765)
python tests/smoke_test.py

# Build portable Windows distribution
python build.py

# Build Windows installer (needs Inno Setup ISCC.exe on PATH)
python build.py --inno

# Build macOS app
python build_macos.py --arch arm64

Architecture

Request flow:
  Dashboard (inline HTML/JS) ──WebSocket──▶ FastAPI ──▶ TaskManager ──▶ Engine
                                                            │
                                                    ┌───────┼───────┐
                                                    ▼       ▼       ▼
                                              browser-use  computer  openclaw
                                              (Playwright) (pyauto   (Node.js
                                               + LLM)      gui+UIA)  gateway)