llamactl
A terminal UI for launching, monitoring and chatting with local llama.cpp servers. It scans your model directories, parses GGUF headers, estimates memory budgets, recommends launch profiles and manages running servers.
Requirements
- Python 3.11+
- A llama.cpp build (llama-server / llama-cli on disk)
- NVIDIA GPU optional (CPU-only hosts work; recommendations adapt)
Install and run
Install the published package in an isolated environment with uv:
uv tool install llama-tui
llamactl
Or use pip in a virtual environment: python -m pip install llama-tui.
llama.cpp binaries and model files are not bundled; configure their paths in Settings.
The PyPI distribution is named llama-tui; the command and Python module remain
llamactl. The published installation commands become available after the first
PyPI release.
Develop from source
uv sync --extra dev --locked
uv run --locked python -m llamactl
uv run --locked pytest -q
uv build
Version: 0.1.3 (development release). See CHANGELOG.md and release instructions for Semantic Versioning and PyPI setup.
Keyboard cheat-sheet
Global: 1-4 switch view, r rescan models, q quit. Enter on the sidebar
also activates a view.
Models
| Key | Action |
|---|---|
| Enter / l | Launch llama-server |
| c | Chat in llama-cli |
| e | Edit profile |
| d | Edit default profile |
| F2 / R | Recommended profile |
| Delete | Delete the model's profile |
Sessions
| Key | Action |
|---|---|
| t | Chat (llama-cli --url) |
| s | Stop / forget |
| a | Attach a running server by URL |
| o | Open the full log |
| y | Copy URL |
Hugging Face
| Key | Action |
|---|---|
| / | Focus search |
| Enter | Search / list files / download |
| k | Set access token |
| x | Cancel download |
Profile editor
ctrl+s save, Esc cancel, F1 help for the focused field,
F2 apply recommended, ctrl+r reset field, +/- step values.
How recommendations work
llamactl parses the GGUF header (architecture, layers, head dims, trained ctx, MoE expert count, weights size) and builds a budget:
budget = weights + KV + compute + overhead
KV = kv_per_token(ctx_type) * ctx_size # shared across all slots
It keeps headroom_pct% of total VRAM free (min 512 MiB), picks the largest
ctx tier that fits, upgrades to q8_0 KV cache when it unlocks a bigger ctx,
offloads MoE experts or dense layers as needed, and reports a verdict:
GPU / GPU+CPU / CPU / NO. See docs/SPEC.md section 7 for the full algorithm.
Files
All state lives in ~/.config/llamactl/:
config.json- settings, default profile, per-model profilessessions.json- managed and attached sessionsgguf_cache.json- parsed GGUF headers keyed by path+mtimeseen.json- models already offered a recommendationhf_token- Hugging Face access tokenlogs/- per-session llama-server logs
Design spec: docs/SPEC.md
Metadata
Release files for llama-tui 0.1.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| llama_tui-0.1.3.tar.gz | 73.7 kB | With provenance | Details for llama_tui-0.1.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| llama_tui-0.1.3-py3-none-any.whl | Python 3 | none | any | Details for llama_tui-0.1.3-py3-none-any.whl |
Total release size: 130.2 kB
Release files / llama_tui-0.1.3.tar.gz
| Download URL | llama_tui-0.1.3.tar.gz |
|---|---|
| Size | 73.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
1b122a65ad2815f10268460b11c39d26a389d72ca5a9d1ff4974dd39630a622a
|
|
BLAKE2b-256 checksum How to use checksums |
395e03b681f61016dca812e2dae83745ce2e5fb4e7f0dde39c33f32a799f0100
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logRelease files / llama_tui-0.1.3-py3-none-any.whl
| Download URL | llama_tui-0.1.3-py3-none-any.whl |
|---|---|
| Size | 56.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e322b630e5e09f4d5640759fcf23ffc66b044f5e65ca06ffa3087c2e27d67552
|
|
BLAKE2b-256 checksum How to use checksums |
ddb50c7bf1316ae3213b415f352fe82ced39b9ecc950234015b94cae08c94b7d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logSecurity for llama-tui 0.1.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for llama_tui-0.1.3.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Oct 7, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.