76 lines
2.6 KiB
Markdown
76 lines
2.6 KiB
Markdown
# 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 |