Hugmunn

Huginn and Muninn are Odin’s two ravens in Norse mythology. Their names mean “thought” and “memory”: they travel through the world and return to tell Odin what they have seen. Hugmunn takes its name from the pair.

Hugmunn is a desktop application and Python library for working with language models. It connects to local models through llama.cpp and to cloud models through the Anthropic and OpenAI APIs.

You can chat, attach instruction packs, let a model read files or run tools, and return to saved conversations. The desktop application and Python API use the same model clients and tool policies. Local model weights and llama-server are separate downloads; they are not included in the Python package or desktop installers.

Install

Install from PyPI with Python 3.10 or newer in a separate environment:

python -m venv .venv
source .venv/bin/activate          # Windows: .venv\Scripts\activate
python -m pip install hugmunn
hugmunn

Or install directly from GitHub:

python -m pip install "hugmunn @ git+https://github.com/EinarOlafsson/hugmunn.git"
hugmunn

python -m hugmunn also launches the application. hugmunn --version prints the installed version without opening a window. For development, install a checkout with python -m pip install -e ..

Download desktop packages from GitHub Releases: a Linux .deb, Windows setup .exe, or macOS .dmg. These bundle Python and Qt. See the installer guide for installation, portable bundles, and platform requirements.

First conversation

1. Launch hugmunn and choose a provider in the Model tab.
2. For a local model, choose a registry entry and download its weights. If you already have them, use hugmunn → Find my models…. Use hugmunn → Set up llama-server… to select an existing runtime or install one.
3. For a cloud model, sign in through Accounts, then select a model from your account’s list. This requires an API key; a chat subscription alone does not provide API access.
4. Enter a message and send it with Ctrl+Enter.

Local models need enough RAM, GPU memory, and disk space for their weights and context. The model picker shows estimated requirements. Start with a model that fits your machine; cloud models do not need a local GPU.

The Run tab selects a working directory, enables tools, and controls approval behavior. With the default Ask before changing anything setting, read tools run directly and writes or shell commands ask for approval. Higher autonomy levels permit more actions without asking. This policy is not an operating-system sandbox.

Cloud requests send prompts and tool results to the selected provider. Local inference stays on the local server, but web tools and downloads still use the network when requested.

Desktop controls

Effort controls instructions and supported provider reasoning settings. Persistence sets the tool-round budget. Autonomy decides which tool calls need approval. These are separate settings.

Conversations are saved as you work. Ctrl+L starts a new one. Type /help for commands, or /remote to open the same conversation in a browser through a local, token-protected page. See the desktop guide for details.

Python API

Discover the models known to the installation:

import hugmunn

for model in hugmunn.models("local"):
    print(model.key, model.label, model.size_gb, model.downloaded)

After downloading a model and setting up llama-server, use its registry key:

import hugmunn

with hugmunn.agent("code-glm") as chat:
    print(chat.ask("Explain Python context managers with an example."))
    chat.save("conversation.json")

Stream a response with access to a limited set of read tools:

import hugmunn

with hugmunn.agent(
    "code-glm",
    workdir="/path/to/project",
    tools=["list_directory", "read_file", "search_text"],
) as chat:
    for event in chat.run("Read the README and describe this project."):
        if event.kind == "content":
            print(event.text, end="", flush=True)
        elif event.kind == "error":
            raise hugmunn.HugmunnError(event.text)

Tools are disabled by default in the Python API. When enabled, calls requiring approval raise ApprovalRequired unless you supply an approve callback. An agent closes the local server it started when its context exits; an already running server is left running. Library conversations are saved explicitly with save().

The API guide covers cloud models, approval callbacks, streaming, cancellation, and sessions. The reference is generated from the public docstrings. Runnable examples are in examples/.

Configuration and documentation

Settings and sessions normally live in ~/.config/hugmunn/; model weights default to ~/.claude/models/. Override these with HUGMUNN_CONFIG_DIR and HUGMUNN_MODELS_ROOT. Set LLAMA_SERVER to use an existing runtime.

Hugmunn’s themes and packaging take inspiration from spacr, my microscopy analysis project. The applications are installed separately.

Development

python -m pip install -e ".[dev,docs,build]"
QT_QPA_PLATFORM=offscreen python -m pytest
python -m sphinx -W --keep-going -b html docs docs/_build/html
python -m build
python -m twine check dist/*.whl dist/*.tar.gz

Tests use fake model clients and offscreen Qt windows; they do not require model downloads or paid API calls. See CHANGELOG.md for changes.

License

Hugmunn’s source and raven artwork are distributed under the PolyForm Noncommercial License 1.0.0. It permits noncommercial use, modification, and redistribution under its terms. Commercial use requires separate permission from Einar Olafsson; contact einar.olafsson@gmail.com.

These terms apply to new releases beginning with 0.0.0.9. Previously published versions retain the license supplied with those versions. Model weights, llama.cpp, Qt, and other dependencies retain their own licenses; see the third-party notices.