# noelthirtyfour/llama-model-manager architecture

> Architecture diagram of the GitHub repository noelthirtyfour/llama-model-manager, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-22). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noelthirtyfour/llama-model-manager
- Repository: https://github.com/noelthirtyfour/llama-model-manager

## Overview

llama-model-manager is a Linux command-line toolkit for managing llama.cpp models and adapting runtime settings to available hardware. The principal workflow is to maintain model presets, select a backend and memory policy, then run llama-server through the llama-main service. It also covers model acquisition and tuning, llama.cpp updates, and OpenCode configuration export. The available evidence is the README and file tree only; relationships below are limited to documented behavior, and the implementation details inside the two scripts could not be inspected.

Main entry points: [`bin/llama-modelctl`](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl) (Model CLI), [`bin/llama-hw-select`](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-hw-select) (Hardware selector), [`systemd/10-auto-hardware.conf`](https://github.com/noelthirtyfour/llama-model-manager/blob/main/systemd/10-auto-hardware.conf) (Service hook)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_model_management["Model management"]
  node_modelctl["Model CLI"]
  node_catalog["Model catalog"]
  node_model_files[("Model files")]
  node_model_fetch["Model acquisition"]
  node_context_params["Model parameters"]
  node_tuning["Adaptive tuning"]
end

subgraph group_hardware_runtime["Hardware and runtime"]
  node_hardware_selector["Hardware selector"]
  node_hardware_hook["Service hook"]
  node_runtime_policy["Backend and profiles"]
  node_state[("Runtime state")]
  node_service["llama-main"]
  node_server["llama-server"]
end

subgraph group_operations["Operations and integrations"]
  node_llama_cpp_update["llama.cpp updater"]
  node_opencode_export["OpenCode exporter"]
end

node_user(("Operator"))
node_device(("Host hardware"))
node_huggingface["Hugging Face"]
node_remote_opencode["Remote OpenCode"]

node_user -->|"runs commands"| node_modelctl
node_modelctl -->|"manages presets"| node_catalog
node_modelctl -->|"adds models"| node_model_fetch
node_model_fetch -->|"downloads from"| node_huggingface
node_model_fetch -->|"stores models"| node_model_files
node_modelctl -->|"sets parameters"| node_context_params
node_context_params -->|"updates presets"| node_catalog
node_modelctl -->|"runs tuning"| node_tuning
node_tuning -->|"benchmarks with"| node_server
node_user -->|"runs selection"| node_hardware_selector
node_hardware_hook -->|"invokes at start"| node_hardware_selector
node_hardware_selector -->|"detects devices"| node_device
node_hardware_selector -->|"rewrites runtime settings"| node_catalog
node_modelctl -->|"sets policy"| node_runtime_policy
node_runtime_policy -->|"persists preferences"| node_state
node_hardware_selector -->|"uses policy"| node_state
node_service -->|"runs"| node_server
node_user -->|"requests update"| node_llama_cpp_update
node_llama_cpp_update -->|"restarts"| node_service
node_user -->|"requests export"| node_opencode_export
node_opencode_export -->|"generates configuration for"| node_remote_opencode

click node_modelctl "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl"
click node_model_fetch "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl"
click node_context_params "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl"
click node_tuning "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl"
click node_hardware_selector "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-hw-select"
click node_hardware_hook "https://github.com/noelthirtyfour/llama-model-manager/blob/main/systemd/10-auto-hardware.conf"
click node_runtime_policy "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl"
click node_llama_cpp_update "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl"
click node_opencode_export "https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_modelctl,node_catalog,node_model_files,node_model_fetch,node_context_params,node_tuning toneBlue
class node_hardware_selector,node_hardware_hook,node_runtime_policy,node_state,node_service,node_server toneAmber
class node_llama_cpp_update,node_opencode_export toneMint
class node_user,node_device,node_huggingface,node_remote_opencode toneIndigo
```

## Components

### Model management

- [Model CLI](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl): `bin/llama-modelctl`
- **Model catalog**
- **Model files**
- [Model acquisition](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl): `bin/llama-modelctl`
- [Model parameters](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl): `bin/llama-modelctl`
- [Adaptive tuning](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl): `bin/llama-modelctl`

### Hardware and runtime

- [Hardware selector](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-hw-select): `bin/llama-hw-select`
- [Service hook](https://github.com/noelthirtyfour/llama-model-manager/blob/main/systemd/10-auto-hardware.conf): `systemd/10-auto-hardware.conf`
- [Backend and profiles](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl): `bin/llama-modelctl`
- **Runtime state**
- **llama-main**
- **llama-server**

### Operations and integrations

- [llama.cpp updater](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl): `bin/llama-modelctl`
- [OpenCode exporter](https://github.com/noelthirtyfour/llama-model-manager/blob/main/bin/llama-modelctl): `bin/llama-modelctl`

### Other components

- **Operator**
- **Host hardware**
- **Hugging Face**
- **Remote OpenCode**

## Connections

- Operator → Model CLI: runs commands (evidence: `README.md`)
- Model CLI → Model catalog: manages presets (evidence: `README.md`)
- Model CLI → Model acquisition: adds models (evidence: `README.md`)
- Model acquisition → Hugging Face: downloads from (evidence: `README.md`)
- Model acquisition → Model files: stores models (evidence: `README.md`)
- Model CLI → Model parameters: sets parameters (evidence: `README.md`)
- Model parameters → Model catalog: updates presets (evidence: `README.md`)
- Model CLI → Adaptive tuning: runs tuning (evidence: `README.md`)
- Adaptive tuning → llama-server: benchmarks with (evidence: `README.md`)
- Operator → Hardware selector: runs selection (evidence: `README.md`)
- Service hook → Hardware selector: invokes at start (evidence: `README.md`)
- Hardware selector → Host hardware: detects devices (evidence: `README.md`)
- Hardware selector → Model catalog: rewrites runtime settings (evidence: `README.md`)
- Model CLI → Backend and profiles: sets policy (evidence: `README.md`)
- Backend and profiles → Runtime state: persists preferences (evidence: `README.md`)
- Hardware selector → Runtime state: uses policy (evidence: `README.md`)
- llama-main → llama-server: runs (evidence: `README.md`)
- Operator → llama.cpp updater: requests update (evidence: `README.md`)
- llama.cpp updater → llama-main: restarts (evidence: `README.md`)
- Operator → OpenCode exporter: requests export (evidence: `README.md`)
- OpenCode exporter → Remote OpenCode: generates configuration for (evidence: `README.md`)
