# 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:
1. System resource monitor (CPU, GPU, memory usage)
2. Ollama model manager (list, download, delete models via Ollama API on port 11434)
3. Platform for additional system tools

## Development Commands

### Running the Application
```bash
# 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
```bash
# 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
1. **Page Classes**: Pages are implemented as classes inheriting from NiceGUI elements (e.g., `WelcomePage` extends `ui.column`)
2. **Environment Configuration**: All app settings are managed via `.env` file and loaded with python-dotenv
3. **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