# CLAUDE.md

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

## CI/CD Notes

- CI builds take **less than 1 minute**
- **After pushing changes, Claude should automatically:**
  1. Wait ~1 minute for CI to complete
  2. Run: `ssh whale "docker pull gitea.voyager.sh/nick/kuma-strapper:latest && cd /opt/docker/kuma-strapper && docker compose up -d --force-recreate"`

## Build & Run Commands

### Docker (Production)
```bash
docker compose up --build        # Build and run
docker compose up -d             # Run detached
```

### Local Development
```bash
# Backend (Flask + SocketIO on port 5000)
cd backend
pip install -r requirements.txt
python app.py

# Frontend (Vite dev server on port 5173, proxies to backend)
cd frontend
npm install
npm run dev

# Frontend production build
npm run build
```

### Environment Setup
Copy `.env.example` to `.env` and set:
- `SSH_PRIVATE_KEY` - Base64-encoded SSH key (`base64 -w 0 ~/.ssh/id_rsa`)
- `UPTIME_KUMA_URL` - Uptime Kuma instance URL
- `UPTIME_KUMA_API_KEY` - Uptime Kuma API token
- `CLAUDE_API_KEY` - Anthropic API key
- `DEV_MODE` - When true, Claude-suggested SSH commands require user approval

## Architecture

**Stack**: Python Flask backend + React/Vite frontend + WebSocket (Socket.io) for real-time updates

### Data Flow
1. User submits hostname → `POST /api/scan` starts background thread
2. SSH Manager connects and runs safe discovery commands (docker ps, systemctl, df, etc.)
3. WebSocket emits `scan_progress` events as commands complete
4. On completion, Claude Agent analyzes results and suggests monitors
5. User selects monitors → created in Uptime Kuma via REST API

### Backend Services (`backend/services/`)
- **ssh_manager.py** - Paramiko-based SSH connection pool, supports RSA/Ed25519/ECDSA keys
- **discovery.py** - Runs safe commands on hosts, defines `SAFE_DISCOVERY_COMMANDS` whitelist
- **claude_agent.py** - Claude API integration with system prompt for monitor suggestions
- **kuma_client.py** - Uptime Kuma REST API wrapper
- **monitors.py** - Creates monitors from discovery data or Claude suggestions

### Approval System (`backend/utils/approval.py`)
When `DEV_MODE=true`, non-whitelisted SSH commands from Claude are queued for user approval. Safe commands (read-only patterns like `cat`, `docker ps`, `systemctl status`) execute immediately.

### Frontend Components (`frontend/src/components/`)
- **Dashboard.jsx** - Scan form and results display
- **DiscoveryResults.jsx** - Claude analysis, monitor selection checkboxes
- **ApprovalModal.jsx** - Dev mode command approval UI
- **DevModeToggle.jsx** - Toggle switch for dev mode

### API Routes (defined in `backend/app.py`)
- `POST /api/scan` - Initiate host scan
- `GET /api/scan/<id>` - Get scan results
- `POST /api/scan/<id>/command` - Run additional SSH command
- `GET/POST /api/approvals/*` - Approval queue management
- `POST /api/monitors/create-defaults` - Create ping/SSH monitors
- `POST /api/monitors/create-suggested` - Create Claude-suggested monitors

### WebSocket Events
- `scan_progress`, `scan_complete` - Scan lifecycle
- `analysis_started`, `analysis_complete`, `analysis_update` - Claude analysis
- `approval_request`, `approval_resolved` - Dev mode approvals

## Key Implementation Details

- Flask serves built frontend from `frontend/dist/` in production (see `serve_frontend` route)
- Vite proxies `/api` and `/socket.io` to Flask in development
- SSH key is decoded from base64 at runtime, never written to disk
- Claude uses `claude-sonnet-4-20250514` model with structured JSON responses