{"id":"6f0102d3-6b10-4c68-9d8f-862fd68d0310","slug":"llama-easy-gui","kind":"mcp","name":"llama-easy-gui","summary":"ocal llama.cpp GUI for privacy-sensitive professionals. Manifest-driven model management, chat with reasoning and images, MCP tools. Windows","owner":"paolodalprato","repoUrl":"https://github.com/paolodalprato/llama-easy-gui","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-07-15T11:05:58.000Z","addedAt":"2026-10-21T21:32:01.865Z","logoUrl":"https://avatars.githubusercontent.com/u/42892131?u=2777aa64fb9ab74bcfdf56bdb15a43389859f2c3&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication"],"tags":[],"runtime":"node","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T08:25:04.452Z","sample":false,"url":"https://conduits.dev/tools/llama-easy-gui","language":"JavaScript","transports":["stdio"],"install":{"npm":"llama-easy-gui"},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# llama-easy-gui\n\n**English** | [Italiano](README.it.md)\n\nA local GUI for [llama.cpp](https://github.com/ggml-org/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.\n\nThis is the llama.cpp counterpart of the approach already tested in [ollama-easy-gui](https://github.com/paolodalprato/ollama-easy-gui).\n\n**Status:** under development (v0.1.0). **Platform: Windows only**, the launcher relies on native Win32 APIs.\n\n![Model detail with capabilities and manifest editing](assets/manifest-edit.png)\n\n## What it does\n\n- **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.\n- **`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.\n- **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.\n- **External tools via MCP**: models with tool calling support can use local or remote [Model Context Protocol](https://modelcontextprotocol.io) servers. Every tool call requires explicit approval in chat, unless auto-approval is configured for a given server.\n\n![Chat with a reasoning block and an MCP tool call](assets/chat.png)\n\n## How it works: the manifest-driven approach\n\nUnlike 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:\n\n- `model`: intrinsic characteristics (architecture, parameters, context, capabilities). Portable across machines.\n- `launch`: `llama-server` launch parameters for this machine (GPU, context, KV cache). Local.\n- `prompts`: usage preferences (prompt profiles, reasoning directives).\n\nModel 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.\n\n## Requirements\n\n- Windows 10 or 11\n- [Node.js](https://nodejs.org) 18 or later\n- 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)\n- a C compiler, used once to build the launcher wrapper (MSYS2 with gcc, mingw-w64, or Visual Studio Build Tools)\n- models in GGUF format, downloadable for example with LM Studio or from Hugging Face\n\n## Installation\n\n```bash\ngit clone https://github.com/paolodalprato/llama-easy-gui.git\ncd llama-easy-gui\nnpm install\n```\n\nThen two steps:\n\n1. 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);\n2. 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).\n\nTo 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>`.\n\nStart with `run.bat` (opens the browser automatically) or `npm start`, then visit `http://127.0.0.1:3004`.\n\n## Model folder layout\n\nOne 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.\n\n```\nD:\\MODELS\\GGUF\\\n├── lmstudio-community\\\n│   └── Qwen3-32B-GGUF\\\n│       ├── Qwen3-32B-Q8_0.gguf\n│       └── Qwen3-32B-Q8_0.manifest.json\n├── ggml-org\\\n│   └── gpt-oss-20b-GGUF\\\n│       ├── gpt-oss-20b-mxfp4.gguf\n│       └── gpt-oss-20b-mxfp4.manifest.json\n└── ...\n```\n\nMultimodal projection files (`mmproj`) live in the same folder as their model and are attached automatically.\n\n## Reading a model's capabilities\n\n![Model list with capability filters](assets/model-list.png)\n\nThe detail panel of each model shows a capabilities section with three chips, each present or absent:\n\n- **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.\n- **Tool calling**: the model can call external tools (see the MCP section below).\n- **Multimodal**: the model can read images, provided a projection file is configured.\n\nThe 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.\n\n## Configuring a model (the essentials)\n\nOpen 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:\n\n- **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.\n- **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.\n- **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.\n\n### The system prompt: a layered design\n\nThe 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.\n\nThe 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.\n\n### Enabling image input\n\nThree conditions, checked automatically by the interface:\n\n1. the model must have the **Multimodal** capability;\n2. the manifest must point to a projection file (`mmproj`): the app proposes the one found in the model's folder, marked as recommended;\n3. the model must be (re)started after setting it, because the projector is loaded at launch.\n\nImages are then attached in chat with the paperclip button or by drag and drop, up to 10 MB each.\n\n### Enabling external tools (MCP)\n\nThree conditions here as well:\n\n1. a model with the **Tool calling** capability;\n2. the **Jinja** option active in the manifest (it enables the tool-aware chat template at launch, so the model needs a restart);\n3. at least one MCP server configured and enabled.\n\nServers 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.\n\n![MCP tab: server management](assets/mcp-server.png)\n\nEvery 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.\n\n## Command line utilities\n\n- `node bin/manifest-utility.js --scan <dir>` generates missing manifests; `--regenerate` rewrites an existing manifest from scratch (custom settings are lost).\n- `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).\n\n## Tests\n\n`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.\n\n## Dependencies\n\nThe core is plain Node.js with no npm dependencies, to minimize attack surface and bundle size. The single declared exception is [`@modelcontextprotocol/sdk`](https://github.com/modelcontextprotocol/typescript-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.\n\n## Known limitations\n\n- Windows only (the launcher wrapper uses Win32 Job Objects).\n- One active model at a time; switching stops the current model.\n- The interface is English-only for now (translations may come with the packaged release).\n- Remote MCP servers support static header authentication; the full OAuth flow is not available yet.\n- Model downloads are up to the user (LM Studio, Hugging Face).\n\n## Roadmap\n\n1. ✅ Native GGUF parser, family knowledge base, manifest generator\n2. ✅ HTTP server, frontend, model folder scanner\n3. ✅ `llama-server` launcher with healthcheck and orphan process protection\n4. ✅ Chat with streaming, reasoning, markdown, export\n5. ✅ Manifest editing from the interface\n6. ✅ Chat attachments (text files and images via mmproj)\n7. ✅ Full MCP integration (connections, tool calling loop with approval, management panel)\n\n## License\n\n[MIT](LICENSE)\n"}