llama-easy-gui

llama-easy-gui

English | Italiano

A local GUI for llama.cpp designed for professionals who need total data privacy (medical, legal, notarial practices). Everything runs on your own machine: no cloud, no data ever leaves your computer.

This is the llama.cpp counterpart of the approach already tested in ollama-easy-gui.

Status: under development (v0.1.0). Platform: Windows only, the launcher relies on native Win32 APIs.

What it does

• Local model management: the app scans your .gguf model folder and shows, for each model, its characteristics (size, context window, capabilities such as reasoning, images, tools) plus a plain-language description derived from the model name.
• llama-server launcher: start and stop models from the interface, with diagnostic logs and real-time status. A native wrapper guarantees that the model process never remains orphaned in memory, even if the app crashes.
• Full chat: streaming responses, a collapsible reasoning block for thinking models, markdown rendering, conversation export, text and image attachments (for multimodal models), named prompt profiles to use the same model in different roles.
• External tools via MCP: models with tool calling support can use local or remote Model Context Protocol servers. Every tool call requires explicit approval in chat, unless auto-approval is configured for a given server.

How it works: the manifest-driven approach

Unlike Ollama, llama.cpp has no centralized registry and every model needs its own launch configuration. For this reason each .gguf file is paired with an "identity card", the <name>.manifest.json file, generated by the app and refinable from the interface. The manifest has three sections:

• model: intrinsic characteristics (architecture, parameters, context, capabilities). Portable across machines.
• launch: llama-server launch parameters for this machine (GPU, context, KV cache). Local.
• prompts: usage preferences (prompt profiles, reasoning directives).

Model capabilities come from an internal knowledge base of known families (Qwen, Gemma, gpt-oss, Nemotron and others), integrated with the file's embedded metadata and, for unknown families, with an analysis of the embedded chat template. Everything happens offline.

Requirements

• Windows 10 or 11
• Node.js 18 or later
• a recent llama.cpp build with llama-server.exe (verified with b9781 or later; older builds do not accept some parameters used by the app)
• a C compiler, used once to build the launcher wrapper (MSYS2 with gcc, mingw-w64, or Visual Studio Build Tools)
• models in GGUF format, downloadable for example with LM Studio or from Hugging Face

Installation

git clone https://github.com/paolodalprato/llama-easy-gui.git
cd llama-easy-gui
npm install

Then two steps:

1. copy config.example.json to config.json and set llama_server_path (full path of llama-server.exe) and models_dir (your GGUF model folder);
2. run setup.bat (double click, or node bin/setup.js), which builds the launcher wrapper and generates the model manifests by scanning models_dir. Building the wrapper needs a C compiler the first time (see Requirements).

To do step 2 by hand instead, build the wrapper with native\build.bat, then generate the manifests with node bin/manifest-utility.js --scan <model folder>.

Start with run.bat (opens the browser automatically) or npm start, then visit http://127.0.0.1:3004.

Model folder layout

One subfolder per model, with the .gguf file and its manifest side by side. The two-level <publisher>\<model> layout used by LM Studio is supported natively: scanning is recursive, so the same folder can serve as a library for both applications.

D:\MODELS\GGUF\
├── lmstudio-community\
│   └── Qwen3-32B-GGUF\
│       ├── Qwen3-32B-Q8_0.gguf
│       └── Qwen3-32B-Q8_0.manifest.json
├── ggml-org\
│   └── gpt-oss-20b-GGUF\
│       ├── gpt-oss-20b-mxfp4.gguf
│       └── gpt-oss-20b-mxfp4.manifest.json
└── ...

Multimodal projection files (mmproj) live in the same folder as their model and are attached automatically.

Reading a model's capabilities

The detail panel of each model shows a capabilities section with three chips, each present or absent:

• Reasoning: the model produces an internal reasoning block before the final answer. The chat shows it collapsed. The notes explain whether and how reasoning can be disabled for that family.
• Tool calling: the model can call external tools (see the MCP section below).
• Multimodal: the model can read images, provided a projection file is configured.

The notes below the chips also report the maximum context window and whether a chat template is embedded in the file. These values come from the internal knowledge base; for families the knowledge base does not recognize, tool calling and reasoning are inferred from the embedded chat template, conservatively and offline. Everything can be corrected in the edit form: for known families the capability checkboxes are locked to prevent accidental errors, with an explicit "force" override for special cases such as capable finetunes.

Configuring a model (the essentials)

Open the edit form from the model's detail panel. The defaults are designed not to fail, so in most cases nothing needs to be touched. The points worth knowing:

• GPU: leave the automatic fit alone. With the GPU fields empty, llama-server distributes the model between GPU and CPU by itself, and a model larger than your VRAM still starts. Forcing full GPU offload on a model that does not fit causes an out-of-memory failure at startup.
• Prompt profiles: a model can have several named system prompts (for example one for drafting documents and one for answering clients). The first profile is the default; when a model has two or more, a selector appears in the chat.
• Model introduction: the "What is this model" text is computed from the model name in plain language; a custom text can replace it via the introduction field.

The system prompt: a layered design

The system prompt sent to the model is not a single text but the composition of up to three layers, joined in this order: an optional reasoning directive (when the family allows disabling its native reasoning and the manifest asks for it), the application-level global_prompt set in config.json, and the active prompt profile from the model's manifest. Empty layers are skipped, and if all of them are empty no system message is sent at all.

The value of this design is the separation of concerns. global_prompt holds what should apply to every model, whichever one is loaded, for example a working language or a reminder that the tool is used in a professional context, and it lives in a single place. The manifest profile holds what belongs to a specific model or role. The two stack instead of overriding each other, so a shared instruction and a model-specific one coexist without being rewritten each time. Changing the model or the profile recomposes the system prompt automatically, on every request.

Enabling image input

Three conditions, checked automatically by the interface:

1. the model must have the Multimodal capability;
2. the manifest must point to a projection file (mmproj): the app proposes the one found in the model's folder, marked as recommended;
3. the model must be (re)started after setting it, because the projector is loaded at launch.

Images are then attached in chat with the paperclip button or by drag and drop, up to 10 MB each.

Enabling external tools (MCP)

Three conditions here as well:

1. a model with the Tool calling capability;
2. the Jinja option active in the manifest (it enables the tool-aware chat template at launch, so the model needs a restart);
3. at least one MCP server configured and enabled.

Servers are managed from the MCP tab (add, remove, enable, connect, choose which tools are exposed to the model) or by copying mcp-config.example.json to mcp-config.json; the schema is the same as claude_desktop_config.json, so existing configurations can be reused. Without these conditions the chat works normally, just without tools.

Every tool call appears in the chat as a card with the tool name and arguments, and waits for approval. Auto-approval is opt-in, per server. Practical tip for npm-based servers: install them globally (npm install -g) and point the config to the installed command, because a cold npx download can exceed the connection timeout on first use.

Command line utilities

• node bin/manifest-utility.js --scan <dir> generates missing manifests; --regenerate rewrites an existing manifest from scratch (custom settings are lost).
• node bin/manifest-migrate.js --dry-run aligns existing manifests to a new knowledge base version without touching your customizations; run it without --dry-run to apply (automatic backups are created).

Tests

npm test runs the suites that require neither GPU nor network (8 suites, 170+ checks on the parser, manifests, chat, attachments, profiles, MCP module and tool calling loop) and prints an overall summary.

Dependencies

The core is plain Node.js with no npm dependencies, to minimize attack surface and bundle size. The single declared exception is @modelcontextprotocol/sdk, the official Model Context Protocol SDK, used for MCP support (local stdio servers and remote Streamable HTTP servers). The SDK is confined to a single module (src/server/mcp/mcp-connection.js), auditable and replaceable.

Known limitations

• Windows only (the launcher wrapper uses Win32 Job Objects).
• One active model at a time; switching stops the current model.
• The interface is English-only for now (translations may come with the packaged release).
• Remote MCP servers support static header authentication; the full OAuth flow is not available yet.
• Model downloads are up to the user (LM Studio, Hugging Face).

Roadmap

1. ✅ Native GGUF parser, family knowledge base, manifest generator
2. ✅ HTTP server, frontend, model folder scanner
3. ✅ llama-server launcher with healthcheck and orphan process protection
4. ✅ Chat with streaming, reasoning, markdown, export
5. ✅ Manifest editing from the interface
6. ✅ Chat attachments (text files and images via mmproj)
7. ✅ Full MCP integration (connections, tool calling loop with approval, management panel)

License

MIT