kuma-strapper/CLAUDE.md

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)

docker compose up --build        # Build and run
docker compose up -d             # Run detached

Local Development

# 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