- Python 56.1%
- QML 36.9%
- Shell 3.2%
- Nix 2%
- JavaScript 1.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
CI / check (push) Successful in 4m57s
Pakete / package (rpm, fedora:44, fedora-44, python3) (push) Successful in 3m37s
Pakete / package (deb, ubuntu:26.04, ubuntu-26.04, python3) (push) Successful in 4m35s
Pakete / package (rpm, fedora:45, fedora-45, python3.14) (push) Successful in 4m31s
Seit dem Web-Tab startet das Fenster QtWebEngine. Als root (CI-Container) verweigert Chromium seine Sandbox („Running as root without --no-sandbox“), deshalb schlug test_window_loads_without_daemon in der CI fehl. Der Test setzt jetzt wie der Webview-Test QTWEBENGINE_DISABLE_SANDBOX=1. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> |
||
| .forgejo/workflows | ||
| backend | ||
| desktop | ||
| docs/screenshots | ||
| nix | ||
| packaging | ||
| plasmoid/org.trayagent.plasmoid | ||
| qml-shared | ||
| scripts | ||
| tests/qml | ||
| .gitignore | ||
| flake.lock | ||
| flake.nix | ||
| install.sh | ||
| LICENSE | ||
| PLAN.md | ||
| README.md | ||
Tray-Agent
Ein LLM-Agent für den Systemabschnitt der KDE-Plasma-Kontrollleiste. Ein Klick auf das Icon öffnet über dem Tray ein Chatfenster. Angebunden wird das Modell über eine OpenAI-kompatible API, etwa Ollama, llama.cpp, vLLM, OpenAI oder OpenRouter.
Der Agent kann:
- Dateien in einem festgelegten Arbeitsverzeichnis bearbeiten,
- Bilder ansehen,
- MCP-Server nutzen,
- Linux-Werkzeuge bedienen.
Alles, was etwas verändert oder Privates liest, zeigt er vorher an und führt es erst nach deiner Bestätigung aus.
| Hell | Dunkel |
|---|---|
![]() |
![]() |
Version 1.0 · Plasma 6 · Python ≥ 3.13 · Entstehung und Architektur: PLAN.md
Funktionen
- Chat
- Streaming, Markdown, Codeblöcke mit Kopier-Button, live sichtbarer Gedankengang von Reasoning-Modellen.
- Abbrechen, Verlauf, Neu generieren, Fragen bearbeiten, Export als Markdown.
- Modelle
- Profile für mehrere Verbindungen (z. B. „Lokal“ und „Cloud“) mit Schnellwechsel in der Kopfzeile.
- Token-Anzeige, optional mit Kosten, und eine Kontextgrenze für lange Verläufe.
- Arbeitsverzeichnis (Standard
~/Agent)- Lesen, Suchen, Schreiben, gezieltes Bearbeiten, Verschieben, Löschen in einen Papierkorb (
.trash). - Änderungen erscheinen vorher als Diff.
- Lesen, Suchen, Schreiben, gezieltes Bearbeiten, Verschieben, Löschen in einen Papierkorb (
- Bilder
- Per Büroklammer, Ziehen, Strg+V oder Screenshot (Bereich, Bildschirm, alle Bildschirme).
- Vision-Modelle bekommen das Bild, andere den per OCR (tesseract) erkannten Text.
- Bilder werden verkleinert und ohne Metadaten (GPS, Kamera) gespeichert.
- MCP-Server
- Lokal (stdio, standardmäßig in einer Sandbox), Streamable HTTP oder SSE.
- Verwaltung im Popup, Import einer
claude_desktop_config.json. - MCP-Prompts erscheinen als
/-Befehle.
- Linux-Werkzeuge, einzeln abschaltbar
- Zwischenablage, Benachrichtigungen, Screenshot, Systeminfo, Logs und Dienste, Medien-Player, Erinnerungen (systemd-Timer), Links und Dateien öffnen.
- PDF-Text, Dokument- und Bildumwandlung, Medieninfos.
- Eine Kommandozeile für freigegebene Programme.
- Status im Tray-Icon: bereit · antwortet · wartet auf Bestätigung · nicht verbunden.
- Desktop-Fenster (optional, eigenes Paket):
- Links die Chats mit Suche, in der Mitte Chat oder Einstellungen.
- Rechts die Tabs Web, Dateien (Arbeitsverzeichnis), Vorschau (Markdown, Text, Bilder, PDF), Werkzeug-Protokoll und MCP.
- Teilt Chats, Einstellungen und Bestätigungen mit dem Popup. „Im Fenster öffnen“ im Popup übernimmt den aktuellen Chat.
- Webview im Desktop-Fenster:
- Eigenes Browser-Profil, getrennt vom normalen Browser; Tabs, Adressleiste, Downloads ins Arbeitsverzeichnis unter
downloads/. - Der Agent kann Seiten öffnen, lesen, Bildschirmfotos machen, klicken, Felder ausfüllen und Formulare absenden. Du siehst dabei zu; eine farbige Umrandung zeigt, wenn er steuert.
- Der Schalter „Agent steuert“ nimmt ihm die Webview-Werkzeuge; klickst du selbst in die Seite, während er arbeitet, pausiert er.
- Knopf zum Vergrößern auf das ganze Fenster, Tabs mit Schließen-Kreuz (Strg+T, Strg+W, Strg+L).
- Meldet sich standardmäßig wie ein normales Chromium (ohne „QtWebEngine“); unter ⋮ → „User-Agent …“ einstellbar.
- Eigenes Browser-Profil, getrennt vom normalen Browser; Tabs, Adressleiste, Downloads ins Arbeitsverzeichnis unter
- Logins aus dem Browser übernehmen (⋮ im Web-Tab):
- Ausgewählte Cookies aus Firefox (auch Flatpak/Snap, mit Containern) oder Chrome/Chromium (auch Flatpak), damit der Webview dort angemeldet ist. Nichts ist vorausgewählt, Passwörter werden nie übernommen.
- Pro Site legst du fest, was der Agent darf: „Nur ich“, „Agent darf lesen“ (Standard) oder „Agent darf interagieren“ (bei Bank- und Zahlungs-Sites nur lesen).
- „Importiert“ listet die Sites mit „Neu importieren“, „Entfernen“ (meldet ab) und „Alle Web-Daten löschen“.
Installation
NixOS mit Home Manager (empfohlen)
# flake.nix der eigenen Konfiguration
inputs.tray-agent.url = "git+https://<dein-git-server>/<benutzer>/tray-agent";
# in der Home-Manager-Konfiguration
imports = [ inputs.tray-agent.homeManagerModules.default ];
services.tray-agent = {
enable = true;
# optional: Desktop-Fenster (PySide6, nicht im Standardpaket)
desktop.enable = true;
# optional: zusätzliche Programme für MCP-Server, pandoc …
extraPackages = [ pkgs.mcp-server-fetch ];
# optional, nur beim ersten Start (danach verwaltet die App die Datei):
initialSettings.llm = { base_url = "http://localhost:11434/v1"; model = "qwen3-vl:8b"; };
};
Das Modul installiert Daemon und Plasmoid und richtet den systemd-User-Dienst tray-agentd ein. tesseract, wl-clipboard, bubblewrap, poppler-utils, ffmpeg und playerctl bringt das Paket selbst mit.
NixOS ohne Home Manager
packages.<system>.default enthält bin/tray-agentd, das Plasmoid (share/plasma/plasmoids) und die Unit (share/systemd/user/tray-agentd.service). Das Desktop-Fenster ist ein eigenes Paket, packages.<system>.desktop. Das Paket kommt in environment.systemPackages oder users.users.<name>.packages, danach:
systemctl --user enable --now tray-agentd.service
Ubuntu 26.04 und Fedora 44/45 (Pakete)
Die Pakete liegen in der Paket-Registry von Forgejo. <server> und <owner> sind der Forgejo-Server und der Eigentümer des Repositorys.
Ubuntu:
sudo curl -fsSL https://<server>/api/packages/<owner>/debian/repository.key -o /etc/apt/keyrings/tray-agent.asc
echo "deb [signed-by=/etc/apt/keyrings/tray-agent.asc] https://<server>/api/packages/<owner>/debian $(. /etc/os-release && echo "$VERSION_CODENAME") main" | sudo tee /etc/apt/sources.list.d/tray-agent.list
sudo apt update && sudo apt install tray-agent
Fedora (fedora-44 bzw. fedora-45):
sudo dnf config-manager addrepo --from-repofile=https://<server>/api/packages/<owner>/rpm/fedora-$(rpm -E %fedora).repo
sudo dnf install tray-agent
Die Pakete bringen den Daemon mit einer eigenen Python-Umgebung unter /opt/tray-agent mit, dazu das Plasmoid und den User-Dienst. Der Dienst ist für alle Benutzer aktiviert und startet bei der nächsten Anmeldung. Für die laufende Sitzung:
systemctl --user start tray-agentd
Desktop-Fenster (optional): ein eigenes Paket, das nur bei Bedarf dazukommt.
sudo apt install tray-agent-desktop
sudo dnf install tray-agent-desktop
Es läuft mit dem Python, PySide6 und Qt der Distribution (passend zu deren Kirigami und Plasma-Stil) und erscheint im Anwendungsmenü als „Tray-Agent“. Im Popup taucht dann der Knopf „Im Fenster öffnen“ auf.
Externe Programme wie bubblewrap, tesseract und wl-clipboard kommen als normale Paketabhängigkeiten. Jedes Paket gehört zu genau der Python-Version, mit der es gebaut wurde. Bei Fedora 45 ist das python3.14, das als Abhängigkeit mitinstalliert wird, weil es für das dortige Standard-Python 3.15 noch nicht alle Abhängigkeiten fertig gibt.
Andere Distributionen
Voraussetzungen sind Python ≥ 3.13 mit venv und Plasma 6.
./install.sh
Das Skript legt eine Python-Umgebung unter ~/.local/share/tray-agent/venv an, installiert Plasmoid und Dienst und meldet fehlende optionale Programme, zum Beispiel bubblewrap, tesseract-ocr, wl-clipboard oder poppler-utils. Mit --desktop kommt das Desktop-Fenster dazu; es braucht PySide6 mit QtWebEngine, Kirigami und den Plasma-Stil aus der Distribution. Entfernen geht so, Konfiguration und Verlauf bleiben dabei erhalten:
./install.sh --uninstall
Danach
- Das Widget erscheint im Systemabschnitt. Falls nicht: Rechtsklick auf den Pfeil im Systemabschnitt → „Systemabschnitt konfigurieren“ → „Einträge“ → Tray-Agent auf „Immer anzeigen“ stellen.
- Im Popup auf das Zahnrad klicken und API-Endpunkt, Modell und gegebenenfalls den API-Key eintragen. Der Key landet im Schlüsselbund (KWallet).
- Tastenkürzel: Auf derselben Seite „Einträge“ in der Spalte „Tastenkürzel“, zum Beispiel Meta+Alt+A.
Bedienung in Kürze
- Enter sendet, Umschalt+Enter macht eine neue Zeile, Esc stoppt eine laufende Antwort.
- Strg+V fügt Text ein und hängt zusätzlich ein Bild aus der Zwischenablage an.
/listet die Prompts der MCP-Server, zum Beispiel/server:prompt Argument.- Bestätigung:
- „Erlauben“ führt den Aufruf einmal aus.
- „Für diesen Chat“ erlaubt das Werkzeug ohne weitere Nachfrage, bis der Daemon neu startet.
- „Ablehnen“ meldet dem Modell, dass du nicht willst.
- ⋮-Menü: Export als Markdown nach
~/Agent/exports/, Neu generieren, Token-Summe des Chats. - ⋮ an jedem Chat in der Liste (oder Rechtsklick): Umbenennen, Exportieren, im Fenster öffnen, Löschen.
Konfiguration
| Was | Wo |
|---|---|
| Einstellungen | ~/.config/tray-agent/config.toml (schreibt die App; Handänderungen werden übernommen, Kommentare nicht) |
| API-Keys, Secrets der MCP-Server | Schlüsselbund (Secret Service/KWallet); ohne Schlüsselbund ~/.config/tray-agent/secrets.json (0600) |
| Verlauf, Bilder | ~/.local/share/tray-agent/ (history.sqlite3, attachments/) |
| Webview-Profil (Cookies, Cache), übernommene Logins | ~/.local/share/tray-agent/web/ (imported.json nur mit Sites, Quellen, Berechtigungen) |
| Verbindung Widget ↔ Daemon | $XDG_RUNTIME_DIR/tray-agent/conn.json (Port und Token, 0600) |
Die wichtigsten Abschnitte in config.toml sind [llm] (inklusive profiles), [workspace], [tools] (Nachfrage-Regel, Werkzeug-Gruppen, Allowlist der Kommandozeile) und [[mcp.servers]].
Sicherheit
- Daemon nur lokal: Er lauscht nur auf
127.0.0.1. Jede Anfrage braucht das Token ausconn.json, das nur dein Benutzer lesen kann. FremdeHost-Header werden abgewiesen (Schutz gegen DNS-Rebinding). - Dateizugriff: Er ist auf das Arbeitsverzeichnis beschränkt. Der Kernel prüft das beim Öffnen per
openat2(RESOLVE_BENEATH), damit sind Ausbrüche über..oder Symlinks auch bei Race-Conditions ausgeschlossen. Verschieben überschreibt nichts, Löschen landet im Papierkorb. - Nachfragen: Standard ist, bei allem nachzufragen, was etwas ändert oder Privates liest. Das betrifft Schreiben, Befehle, Öffnen, Kopieren, Zwischenablage lesen, Screenshot und das System-Journal. MCP-Werkzeuge fragen grundsätzlich nach, außer du gibst sie einzeln frei. Die Bestätigung zeigt den Diff oder die Argumente, die hinausgehen.
- Sandbox: Lokale MCP-Server, Dateikonvertierung (PDF, Office, Bilder, Medien) und die Kommandozeile laufen in
bubblewrap. Sie sehen nur Systempfade (lesend), ein leeres Home und das Arbeitsverzeichnis. Sie haben kein Netz, außer du erlaubst es pro Server bzw. für die Kommandozeile. Server mitnpx/uvxlegt der Import ohne Sandbox an, das zeigt die Verwaltung an. - Webview:
- Eine neue Domain öffnet oder lädt der Agent erst nach deiner Bestätigung; danach gilt sie für diesen Chat.
- Klicken und Ausfüllen zeigen vorher das betroffene Element. Absenden fragt immer nach, auch bei „nie nachfragen“, und zeigt Ziel und Felder. Knöpfe wie „Bestellen“, „Senden“ oder „Löschen“ lassen sich nur so auslösen.
- Passwort-, Karten- und Code-Felder füllt der Agent nie aus, Dateiauswahl gibt es für ihn nicht.
- Nur
http(s);file:und interne Seiten sind gesperrt. Kamera, Mikrofon, Standort, Benachrichtigungen werden verweigert. - Seiteninhalte gehen als fremde Daten markiert an das Modell. Die Hilfsfunktionen laufen in einer isolierten Skript-Umgebung, die Seite kann sie nicht sehen oder fälschen.
- Übernommene Logins: Nur auf deinen Klick, kein Werkzeug des Agenten liest oder importiert Cookies. Cookie-Werte gehen direkt in das Webview-Profil, nie an das Modell, in Protokolle oder in
imported.json. Chrome/Chromium-Cookies entschlüsselt die App mit dem Schlüssel aus KWallet bzw. dem Schlüsselbund; KWallet fragt dabei selbst um Erlaubnis. - Kommandozeile: Sie startet nur Programme aus der Allowlist, ohne Shell. Shells und Interpreter stehen bewusst nicht in der Standardliste.
- Prompt-Injection: Inhalte aus Dateien, Webseiten und Tool-Ergebnissen gelten im Systemprompt als Daten, nicht als Anweisungen. Verlassen solltest du dich darauf nicht. Die eigentliche Absicherung sind die Bestätigungen und die Sandbox.
- Was nicht abgedeckt ist:
- Hardlinks auf Dateien außerhalb, die schon im Arbeitsverzeichnis liegen.
- Was ein freigegebener MCP-Server mit seinen eigenen Rechten tut.
- Was das Modell aus den Daten macht, die du ihm gibst. Bei Cloud-Anbietern verlassen Chat-Inhalte deinen Rechner.
Entwicklung
nix develop
scripts/check.sh # ruff, mypy, pytest, qmllint und QML-Verhaltenstests
nix flake check # Paket bauen (mit Tests) und Home-Manager-Modul auswerten
scripts/dev-install.sh # Daemon (./result) und Plasmoid für den eigenen Benutzer installieren
scripts/dev-install.sh --no-daemon --desktop # zusätzlich das Desktop-Fenster (~/.local/bin)
plasmawindowed org.trayagent.plasmoid
systemctl --user restart plasma-plasmashell.service # plasmashell lädt geänderte QML-Dateien erst danach
QML-Logs landen im Journal, mit QT_FORCE_STDERR_LOGGING=1 auf der Konsole.
CI und Pakete (Forgejo Actions):
ci.ymlprüft jeden Push.packages.ymlbaut bei Tagsv*die Pakete für Ubuntu 26.04, Fedora 45 und Fedora 44. Jedes wird im Container der Distribution mit deren Python-Version getestet und in die Paket-Registry geladen.- Manuell gestartet baut
packages.ymlnur, die Pakete hängen dann als Artefakte am Lauf. - Für den Upload braucht das Repository das Secret
PACKAGES_TOKEN: ein Token des Eigentümers mit dem Recht „package: Lesen und Schreiben“. - Weitere Distributionen kommen als Eintrag in die Matrix.
Lokal baut man ein Paket so (im Container der Zieldistribution):
scripts/package.sh deb --test
Die Python-Abhängigkeiten der Pakete und von install.sh sind über packaging/constraints.txt auf die getesteten Versionen festgelegt. Nach einem nixpkgs-Update erzeugt scripts/update-constraints.sh die Datei neu.
Aufbau:
backend/: Daemon (Python, aiohttp), REST-API intray_agent/api.py, Events als NDJSON-Stream unter/api/events.plasmoid/: Plasma-6-Widget.qml-shared/: QML-Komponenten für Popup und Desktop-Fenster.desktop/: Desktop-Fenster (PySide6, QML/Kirigami), eigenes Paket.nix/: Pakete und Home-Manager-Modul.packaging/,scripts/,install.sh.
Bekannte Grenzen
- Die Oberfläche ist nur auf Deutsch, eine Übersetzung ist vorbereitet, aber nicht umgesetzt.
- Die Kontextgrenze kürzt alte Runden, statt sie zusammenzufassen.
- Fehlerausgaben (stderr) lokaler MCP-Server werden verworfen.
- Kleine lokale Modelle sind für Agent-Aufgaben oft langsam (Minuten Bedenkzeit) oder ignorieren die Werkzeuge. Rund 30 Werkzeuge kosten gut 6 000 Tokens Kontext. Nicht benötigte Gruppen lassen sich abschalten.
Lizenz
Copyright © 2026 Jochen Welzel
Tray-Agent ist freie Software: Du kannst sie unter den Bedingungen der GNU General Public License, Version 3 oder (nach deiner Wahl) jeder späteren Version, weitergeben und verändern. Das Programm wird ohne jede Gewährleistung verbreitet. Die Einzelheiten stehen in LICENSE. Jede Quelldatei trägt die Kennung SPDX-License-Identifier: GPL-3.0-or-later.

