- Python 55.1%
- QML 39.1%
- Shell 2.5%
- JavaScript 1.7%
- Nix 1.6%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
|
All checks were successful
CI / check (push) Successful in 5m16s
Pakete / package (deb, ubuntu:26.04, ubuntu-26.04, python3) (push) Successful in 4m25s
Pakete / package (rpm, fedora:44, fedora-44, python3) (push) Successful in 4m59s
Pakete / package (rpm, fedora:45, fedora-45, python3.14) (push) Successful in 3m42s
Neuer Dialog „Website-Daten“ (⋮ im Web-Tab) listet die Sites mit Cookies oder gespeicherten Daten und löscht für ausgewählte Sites Cookies, Local/Session Storage, IndexedDB, Cache Storage, Service Worker und Berechtigungen. Den Seitenspeicher leert eine unsichtbare Ansicht, die je Herkunft eine leere Seite mit deren Adresse lädt; die Herkünfte merkt sich sitedata.SiteData (origins.json, nur Schema/Host/Port), ergänzt um QuotaManager-Buckets und Cookie-Domains. 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,
- Webseiten laden und über SearXNG im Web suchen,
- 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.
- Wird es eng, kürzt der Daemon zuerst ältere Werkzeug-Ausgaben, dann die ältesten Nachrichten; die aktuelle Frage und die letzten Werkzeug-Runden bleiben vollständig. Meldet der Server, dass die Anfrage nicht ins Kontextfenster passt, merkt er sich dessen Größe und versucht es einmal gekürzt erneut.
- Agenten
- Mehrere Agenten auf einer eigenen Seite (Einstellungen → Agenten → Verwalten), einer davon ist die Vorgabe für neue Chats.
- Je Agent: Name, Beschreibung, System-Prompt, Modell-Profil (Endpunkt und API-Key) und Modell, eigenes Arbeitsverzeichnis mit Schreibschutz, Nachfragen vor Werkzeugen, erlaubte Werkzeuge (Bereiche und einzelne Werkzeuge), erlaubte MCP-Server und Werkzeug-Runden pro Anfrage.
- Was in den allgemeinen Einstellungen ausgeschaltet ist, bleibt auch für jeden Agenten aus. MCP-Server laufen für alle Agenten im allgemeinen Arbeitsverzeichnis.
- Werkzeug-Runden: standardmäßig 25 pro Anfrage, bis 200 (für gründliche Recherchen). Ist das Limit erreicht, antwortet das Modell mit dem bisherigen Stand; „weiter“ setzt fort.
- Pro Chat über den Knopf neben der Eingabe wählbar und jederzeit wechselbar; der Wechsel gilt ab der nächsten Antwort.
- Web
fetch_urllädt Seiten direkt von diesem Rechner und liefert lesbaren Text als Markdown. Lange Seiten kommen abschnittsweise. Ohne JavaScript; dafür gibt es den Webview im Desktop-Fenster.web_searchsucht über eine eigene SearXNG-Instanz (Einstellungen → Web); dort muss das JSON-Format aktiviert sein (search.formats: [html, json]).- Lokale und private Adressen (localhost, 192.168.x, 10.x, …) sind gesperrt, damit eine Webseite das Modell nicht zum Abruf interner Dienste bringt. Ausnahmen trägt man unter „Lokale Adressen“ ein; Abrufe dorthin gelten als sensibel und werden bei „Bei Änderungen“ nachgefragt.
- Je Agent als Bereich „Web“ freizugeben.
- 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.
- Cookie-Banner und andere Overlays erkennt er auch in Shadow-DOMs (z. B. Usercentrics) und in eingebetteten Frames fremder Domains (z. B. Sourcepoint); was über der Seite liegt, steht im Snapshot zuerst.
- 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“.
- Website-Daten je Site löschen (⋮ im Web-Tab → „Daten dieser Website löschen …“ oder „Website-Daten verwalten …“):
- Listet die Sites, die im Webview Cookies oder andere Daten abgelegt haben, mit Suche und Mehrfachauswahl.
- Löscht für die gewählten Sites Cookies (auch importierte Logins), Local/Session Storage, IndexedDB, Cache Storage, Service Worker und gespeicherte Berechtigungen, für alle Subdomains. Andere Sites bleiben angemeldet; offene Tabs der Site werden neu geladen. Den HTTP-Cache leert es dabei ganz (QtWebEngine kann ihn nicht je Site leeren).
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; system_prompt ist der Agent „Standard“), [agents] (default und [[agents.items]] mit id, name, system_prompt, optional description, profile, model, workspace, read_only, confirm, tools, disabled_tools und mcp_servers), [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 Nachrichten und Werkzeug-Ausgaben, statt sie zusammenzufassen. Was der Daemon über das Kontextfenster eines Modells lernt, gilt bis zum Neustart.
- Fehlerausgaben (stderr) lokaler MCP-Server werden verworfen.
- „Website-Daten löschen“ erreicht keinen Speicher, den eine Site als eingebetteter Frame in anderen Sites ablegt (Partitionierung), und leert den HTTP-Cache immer ganz.
- 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.

