Skip to main content

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 profiles
  • sessions.json - managed and attached sessions
  • gguf_cache.json - parsed GGUF headers keyed by path+mtime
  • seen.json - models already offered a recommendation
  • hf_token - Hugging Face access token
  • logs/ - 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)

Source distribution for llama-tui 0.1.3
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)

Table of built distributions (wheels) for llama-tui 0.1.3
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

A 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.

Release history Release notifications | RSS feed

This release

0.1.3 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page