CLAUDE.md

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

Project Context

This is a NiceGUI-based web frontend for managing an Arch Linux system with AMD GPU and Ollama. The application serves as:

System resource monitor (CPU, GPU, memory usage)
Ollama model manager (list, download, delete models via Ollama API on port 11434)
Platform for additional system tools

Development Commands

Running the Application

# Install dependencies
uv sync

# Run the development server (use port 8081 for testing as 8080 is usually occupied)
APP_PORT=8081 uv run python src/main.py

# Default port (8080) - usually already in use by main instance
uv run python src/main.py

Dependency Management

# Add a new dependency
uv add <package>

# Add a dev dependency
uv add --dev <package>

# Update dependencies
uv sync

Architecture Overview

Technology Stack

Package Manager: uv (version 0.8.17)
UI Framework: NiceGUI (async web framework based on FastAPI/Vue.js)
Python Version: 3.13+
Ollama API: Running on localhost:11434

Project Structure

src/main.py: Entry point, configures NiceGUI app with environment variables
src/pages/: Page components inheriting from NiceGUI elements
src/components/: Reusable UI components (currently empty, ready for implementation)
src/static/: Static assets (CSS, images)
.env: Configuration variables (APP_TITLE, APP_PORT, APP_STORAGE_SECRET, APP_SHOW)

Key Design Patterns

Page Classes: Pages are implemented as classes inheriting from NiceGUI elements (e.g., WelcomePage extends ui.column)
Environment Configuration: All app settings are managed via .env file and loaded with python-dotenv
Async Support: Main page handlers use async functions for potential async operations

Ollama Integration

The Ollama API is available at http://localhost:11434/api/. Key endpoints:

/api/version: Get Ollama version
/api/tags: List available models
/api/pull: Download models
/api/delete: Remove models
/api/generate: Generate text
/api/chat: Chat completion

System Monitoring

For AMD GPU monitoring on Arch Linux:

Use rocm-smi for GPU stats (temperature, usage, memory)
Use psutil for CPU and memory monitoring
Consider py3nvml or direct sysfs reading for additional GPU metrics

NiceGUI Patterns

Use ui.dark_mode() for theme toggling
Implement pages as classes extending NiceGUI elements for better organization
Use ui.timer() for periodic updates (system stats)
Leverage ui.refreshable decorator for dynamic content updates

2.6 KiB Raw Blame History