Mitmachen
An Ancilo mitarbeiten
Ancilo ist ein Open-Source-Projekt von Stefan Grunert. Beiträge können Code, Tests und Übersetzungen sein, aber ebenso eine nachvollziehbare Fehlermeldung oder ein konkreter Verbesserungsvorschlag. Dafür musst du nicht programmieren können.
Fehler melden
Schau zuerst in die vorhandenen GitHub Issues. Gibt es bereits einen Bericht zu deinem Problem, ergänze dort deine Beobachtung. Andernfalls eröffne ein neues Issue. Ohne GitHub-Konto kannst du an [email protected] schreiben; eine kurze Beschreibung in deinen eigenen Worten genügt für den Anfang.
Ein hilfreicher Bericht nennt die Ancilo-Version, die macOS-Version, den Chip und den Arbeitsspeicher deines Computers. Bei Problemen mit Antworten oder Aufgaben gehören auch Modellname und Ressourcenprofil dazu. Beschreibe die Schritte bis zum Fehler, das erwartete Ergebnis und das tatsächlich beobachtete Verhalten. Die genaue Fehlermeldung oder ein Screenshot hilft, die Stelle wiederzufinden.
GitHub Issues sind öffentlich. Entferne persönliche Inhalte aus Screenshots und verwende nach Möglichkeit ein kleines, anonymisiertes Beispieldokument. Zugangsschlüssel und vollständige private Chats werden für einen Fehlerbericht nicht benötigt.
Funktionen und Verbesserungen vorschlagen
Funktionswünsche gehören ebenfalls in GitHub Issues oder können per E-Mail geschickt werden. Beschreibe vor allem die Aufgabe, die du erledigen möchtest, und die Stelle, an der Ancilo dich dabei noch nicht unterstützt. Ein konkretes Beispiel macht den Bedarf verständlicher als ein Funktionsname allein.
Wenn du bereits eine Lösung im Kopf hast, ergänze sie als Vorschlag. Auch Hinweise auf unverständliche Beschriftungen, fehlende Anleitungen oder Übersetzungsfehler sind Beiträge. Größere Code-Änderungen sollten zuerst in einem Issue besprochen werden, damit Ziel und Umfang vor der Umsetzung klar sind.
Tech-Stack und Aufbau
- HintergrunddienstRust (Edition 2024) mit tokio, axum und SQLite (rusqlite) – inklusive Kommandozeile ancilo
- Modellellama.cpp (llama-server) mit GGUF-Modellen von Hugging Face
- OberflächeReact 19, TypeScript, Vite, TanStack Query
- Desktop-AppTauri 2, macOS auf Apple Silicon
- SchnittstellenHTTP-API mit OpenAPI, MCP, OpenAI- und Anthropic-kompatible Modell-API
- SicherheitSandbox mit Seatbelt (macOS) bzw. bubblewrap (Linux)
- TexterkennungSwift mit Apples Vision
- Tests und Buildcargo-nextest, Vitest, Playwright; just bündelt alle Befehle
Ancilo besteht aus einem Hintergrunddienst, der auf dem eigenen Rechner läuft und nur unter 127.0.0.1 erreichbar ist, geschützt durch ein Token. Alles, was Ancilo kann, ist eine Operation in einem gemeinsamen Register. Dieselbe Operation erreichen die App, die Kommandozeile, die HTTP-API, MCP für Claude Code und Codex und Ancilos eingebaute Hilfe. Eine neue Funktion wird also einmal gebaut und steht überall zur Verfügung. unsafe ist im gesamten Rust-Workspace verboten.
Der Modellmanager plant Kontextgröße und Speicherbedarf, lädt und entlädt Modelle und achtet darauf, dass der Rechner benutzbar bleibt; llama.cpp ist auf eine Version festgelegt. Ein Gateway verteilt die Anfragen an die Modelle. Die Suche in Dokumenten und Code nutzt ein kleines Embedding-Modell und eine hybride Suche aus Vektoren und Volltext.
Die Agenten für Coding und Aufgaben arbeiten in einer gemeinsamen Schleife mit Werkzeugen; ihre Befehle laufen in der Sandbox. Dokumente liest ein eigener, abgeschotteter Prozess. Die macOS-App startet den Dienst und zeigt die Oberfläche, die der Dienst selbst ausliefert; deren API-Typen werden aus der OpenAPI-Beschreibung erzeugt.
Ein skriptbares Fake-Modell macht Verhalten, das von Modellantworten abhängt, deterministisch prüfbar; Hugging Face, Claude Code und Codex werden in Tests ebenfalls simuliert. Die Übersicht zeigt, was im Repository wo liegt.
crates/core Typen, Fehler, Ereignisse, Operations-Register
crates/daemon Hintergrunddienst – verbindet alle Teile
crates/server HTTP-API, Ereignisse (SSE), OpenAPI
crates/cli Kommandozeile ancilo
crates/models Modelle: Planung, Downloads, llama.cpp-Prozesse
crates/gateway Anfragen an Modelle: Routing, OpenAI-/Anthropic-API
crates/agent Agenten-Schleife, Werkzeuge, Sandbox
crates/sessions Coding und Aufgaben in der App
crates/tasks delegierte Coding Tasks, Worktrees
crates/mcp MCP-Server für Claude Code und Codex
crates/connect Claude Code und Codex verbinden
crates/docs Dokumente lesen, Texterkennung
crates/index Code- und Wissenssuche
crates/web Websuche
crates/assistant Ancilos eingebaute Hilfe
crates/compare Modellvergleiche
crates/eval Evaluierungen
crates/storage SQLite und Migrationen
crates/testkit Fake-Modelle und Testhilfen
app/ Oberfläche (React, TypeScript, Vite)
app/src-tauri/ macOS-App (Tauri 2)
packaging/ Pakete, Signierung, DMG, ReleaseEntwicklungsumgebung
Stefans Entwicklungsumgebung ist ein Mac mit Apple Silicon; Claude Code, Codex und Ancilo gehören zu den verwendeten Werkzeugen. Die Anbindung über MCP erlaubt es, abgegrenzte Arbeiten wie Tests, Dokumentation oder kleine Änderungen an ein lokales Modell zu delegieren. Die Ergebnisse werden anschließend am Code und durch Tests geprüft. Für einen eigenen Beitrag ist kein bestimmter KI-Assistent erforderlich.
Neben dem Ancilo-Projekt hat Stefan die Quellcode-Repositories von Codex und OpenCode in benachbarten Verzeichnissen ausgecheckt. Sie dienen ihm und seinem Coding-Agenten Claude Code als Referenz: Vorhandene Implementierungen geben Anregungen für die eigene Entwicklung und zeigen, wie andere Projekte ähnliche Probleme lösen. So lässt sich auf bestehende Erfahrungen aufbauen, statt das Rad ein zweites Mal zu erfinden.
Für den dokumentierten macOS-Entwicklungsweg brauchst du Git, Rust über rustup, Node.js 22 oder neuer mit npm, just und cargo-nextest. Die Rust-Version ist in rust-toolchain.toml festgelegt. Dazu kommen Apples Command Line Tools mit Swift: Daraus entsteht das kleine Hilfsprogramm für die Texterkennung; ohne Swift baut Ancilo trotzdem, nur ohne Texterkennung. Der native App-Build verwendet außerdem CMake und Ninja für llama.cpp. Abhängigkeiten müssen beim ersten Einrichten heruntergeladen werden.
Die Prüfungen laufen auch unter Linux, wie in der Continuous Integration; der abgeschottete Dokumentenleser braucht dort bubblewrap. Die Desktop-App selbst gibt es nur für macOS.
Ancilo Dev neben der normalen App
Erstelle für einen Code-Beitrag einen Fork auf GitHub und klone ihn lokal. Lege für die Änderung einen eigenen Branch an. Im Projektverzeichnis baut und installiert just app-dev die separate Anwendung „Ancilo Dev“. Dieser Befehl ersetzt eine vorhandene Dev-Version, lässt die normale Ancilo-App aber bestehen.
Die Dev-App hat ein eigenes Datenverzeichnis unter ~/Library/Application Support/ancilo-dev, den Port 7425 und einen eigenen Start bei der Anmeldung. Ihre Kommandozeile heißt ancilo-dev und wird nach ~/.local/bin installiert; dieses Verzeichnis sollte im PATH liegen. Automatische App-Updates sind in der Dev-App deaktiviert. So können Änderungen ausprobiert werden, während die veröffentlichte Version separat verfügbar bleibt.
Ein Apple-Developer-Zertifikat ist für diesen lokalen Build nicht erforderlich: Das Skript verwendet eine vorhandene Signieridentität oder signiert ad hoc. Signierung und Notarisierung einer öffentlichen Veröffentlichung gehören zum Release-Prozess des Maintainers.
git switch -c fix/short-description
just app-devÄnderungen prüfen und einreichen
just verify prüft Formatierung, Clippy, Rust-Tests sowie Typen und Tests der Oberfläche und installiert dabei die Abhängigkeiten der Oberfläche selbst. Die deterministischen Tests ersetzen Modelle und externe Dienste durch kontrollierbare Testimplementierungen. Nach dem Laden der Abhängigkeiten benötigen diese Prüfungen weder eine GPU noch einen laufenden Cloud-Dienst. Der erste Testlauf nach einem Build kann auf macOS spürbar länger dauern, weil XProtect neue Testprogramme einmal prüft.
just app-e2e prüft die Oberfläche in Chromium und WebKit gegen einen echten Ancilo-Hintergrunddienst mit simulierten externen Diensten. Die Browser müssen einmal über Playwright installiert werden. Bei Änderungen an Modellen, Delegation oder der API kommen die Prüfungen mit echten kleinen Modellen über just test-real hinzu; dabei können Modelldownloads nötig sein.
Wer Operationen oder Antworten des Hintergrunddiensts ändert, erzeugt mit just app-api die TypeScript-Typen der Oberfläche neu; sonst schlagen die Prüfungen der Oberfläche fehl.
Ein Pull Request sollte das Problem, die Änderung und die ausgeführten Prüfungen beschreiben und gegebenenfalls auf das Issue verweisen. Code, Kommentare und Commit-Nachrichten sind auf Englisch; das Projekt verwendet Conventional Commits. Auch KI-generierter Code braucht eine eigene Prüfung und passende Tests. Maßgeblich sind die aktuellen Hinweise in CONTRIBUTING.md.
just verify
cd app && npx playwright install chromium webkit && cd ..
just app-e2e