buhu

Android-Handys per KI steuern – mit DeepSeek über OpenRouter, mehreren Geräten, Zeitplänen, Dauerloops und menschlicher Eingabe-Rhythmik.

buhu ist eine Erweiterung für Ghost in the Droid (PyPI-Paket ghost-in-the-droid, kurz GITD). Es ersetzt GITD nicht, sondern hängt sich beim Start in dessen Server ein und behebt oder ergänzt dort, was für den Dauerbetrieb mit mehreren Handys fehlt. Code und Kommentare sind deutschsprachig.

---

Was drin ist

Datei	Zweck
gitd_deepseek.py	Startpunkt. Startet den GITD-Server mit DeepSeek-only-Guard (kein stiller Rückfall auf andere Anbieter), Vision-Fix für den OpenRouter-Pfad und hängt Persistenz, Loops, Scheduler-Korrekturen, Appium-Jobs und Flottenwache ein
gitd_llm.py	Hybrid-Router: drei DeepSeek-Modelle nach Rolle (Schleife, Planer, Screen-Leser)
gitd_persist.py	Datenbank, Skills und Aufnahmen landen in gitd_daten/ statt im uv-Cache und überleben so jedes Update
gitd_loops.py	Dauerloops mit Zeitscheiben und selbstverbessernden Prompts, beliebig viele parallel
gitd_loop_job.py	Bindeglied zwischen Scheduler und Loop-Betrieb
gitd_zeitplan.py, gitd_verlauf.py	Korrekturen am GITD-Scheduler: Startfenster, Verlauf, Benennung
gitd_tagesplan.py + tagesplan.yaml	Stundenplan je Handy als Datei statt Formular, mit Überschneidungsprüfung
gitd_flotte.py + flotte.yaml	Flottenwache: misst jedes Handy im Minutentakt, meldet Ausfälle, Hänger, Akku und Captchas per ntfy
gitd_streamwache.py	kein Bildschirmstream auf Geräte, die nicht angeschlossen sind
gitd_appium.py, gitd_skills.py	eigene Appium/WebdriverIO-Bots als geplante GITD-Jobs und als Skills im Skill Hub
gitd_human.py, patch_gitd_human.py, gitd_mcp.py	menschliche Eingabe-Rhythmik: Tippen Zeichen für Zeichen, natürliche Wischgesten, Lesepausen
gitd_captcha.py	Captcha-Wache: erkennt Bot-Prüfungen, hält an und übergibt an den Menschen – löst sie nicht
gitd_ghost.py	Ausführungsschicht über den GITD-MCP-Server (bin/android-agent-mcp)
gitd_env.py	zentrale Konfiguration: Gerät, Pfade, Modelle
gitd_agent.py	eine Aufgabe in Klartext an den laufenden Agenten geben
gitd_doctor.py	Selbsttest der Kette Gerät → MCP → DeepSeek, nur lesend
gitd_marktde.py, gitd_marktde_check.py	Beispiel-Routine für markt.de: Warmlauf, Anzeige aufgeben, Status prüfen
x_like_comment_test.py, x_reply_solana.py	Beispiele für die X-App
gitd_daten/skills/	Skill-Definitionen für die Appium-Bots
gitd_schluessel.py	API-Key über das Dashboard setzen (Knopf oben in der Kopfzeile)
frontend/	Quellcode des Dashboards (Vue 3 + Vite)
webchat/	das fertig gebaute Dashboard – der Server liefert es selbst aus

Nicht enthalten: die Appium-Bot-Skripte selbst und alle Zugangsdaten, Datenbanken und Logs.

---

Voraussetzungen

• Linux (entwickelt unter Ubuntu 24.04)
• uv
• adb aus den Android-Platform-Tools, ein Android-Handy mit USB-Debugging
• ein OpenRouter-API-Key
• optional: Appium + Node.js (für Appium-Jobs), Tailscale, ntfy

Schnellstart

git clone https://code.buhu.app/buhu_app/buhu.git
cd buhu
cp .env.example .env
adb devices                 # Handy muss als "device" erscheinen
uv run --with 'ghost-in-the-droid[ocr]' --with rapidocr python gitd_deepseek.py

Dann im Browser http://127.0.0.1:5055 öffnen. Oben rechts steht API-Key fehlt – draufklicken, den OpenRouter-Key einfügen, speichern. Fertig, ein Neustart ist nicht nötig. Die API-Dokumentation liegt unter http://127.0.0.1:5055/docs.

Nicht uvx ghost-in-the-droid up benutzen. Das umgeht den DeepSeek-Guard und die eingehängten Module.

Für den Start ohne Terminal (Desktop-Icon) gibt es bin/gitd-start-laptop.sh und bin/icon-installieren.sh – das Skript legt beim ersten Start auch die .env aus der Vorlage an. bin/gitd-start.sh startet zusätzlich den vite-Dev-Server aus frontend/, sobald dort npm install gelaufen ist.

Gerät wählen

In keinem Skript steht eine Seriennummer. gitd_env.device() nimmt das einzige angeschlossene Gerät und bricht bei mehreren mit der Liste ab, statt eins zu raten. Bei mehreren Handys:

export GITD_DEVICE=<serial>

Einzelne Skripte nehmen zusätzlich --device <serial>.

Selbsttest

python3 gitd_doctor.py            # alles
python3 gitd_doctor.py --no-llm   # ohne Modellaufrufe (kostenlos)

Tests ohne Gerät

python3 test_gitd_captcha.py
python3 test_gitd_loops.py
python3 test_gitd_schluessel.py

---

Dashboard

Das Dashboard ist eine Bearbeitung des GITD-Frontends: dunkles Thema, der buhu-Geist oben links zeigt den Gerätezustand (grau = kein Gerät, violett = bereit, pink = arbeitet, rot = Fehler). Die Reiter stehen in drei Gruppen:

Gruppe	Reiter
Betrieb	Flotte, Phone Agent, Loop, Scheduler, markt.de
Bauen	Skill Hub, Skill Creator, Skill-Miner, Tools
Prüfen	Manual Run, Tests, Device Health, Emulators, Benchmarks

API-Key oben in der Kopfzeile

Der Knopf API-Key setzt den OpenRouter-Key, ohne dass man die .env anfassen muss:

• Der Key wird bei OpenRouter geprüft und dann in die .env geschrieben (nur für den eigenen Benutzer lesbar). Er gilt sofort.
• Er wird nie wieder angezeigt – der Server meldet nur, ob einer gesetzt ist. Ersetzen geht jederzeit.
• Ändern geht nur am Rechner selbst (127.0.0.1) und nur aus dem Dashboard heraus. Andere Geräte im Netz und fremde Webseiten werden abgewiesen.

Am Dashboard weiterbauen

cd frontend
npm install
npm run dev                                      # http://localhost:6175, API über Proxy
npx vite build --outDir ../webchat --emptyOutDir  # neuen Stand nach webchat/ bauen

---

Appium-Bots als Jobs

gitd_appium.py startet eigene Appium/WebdriverIO-Bots als GITD-Jobs. Die Bots selbst sind nicht Teil dieses Repositorys. Erwartet werden sie unter ~/Schreibtisch/appium-chrome/bots/ mit dem Namensschema

<nr>_<typ>_<SERIAL>_<appium-port>.js      z. B. 1_cookies_generell_HANDY1_4722.js

python3 gitd_skills.py --bauen legt daraus die Skills unter gitd_daten/skills/ an, python3 gitd_tagesplan.py --sync überträgt tagesplan.yaml in den Scheduler. Die Seriennummern in tagesplan.yaml und den Skill-Definitionen sind Platzhalter (HANDY1 …) und müssen durch die eigenen aus adb devices ersetzt werden.

Wichtig: GITD und Appium nie gleichzeitig auf demselben Handy laufen lassen.

---

Sicherheit

• .env enthält Schlüssel und wird nie eingecheckt (.gitignore sperrt sie).
• Das Dashboard und die API haben keine Anmeldung. Ohne weitere Angabe lauscht der Server deshalb nur auf 127.0.0.1.
• Tailscale ist optional. Mit GITD_HOST=tailscale in der .env bindet der Server an die Tailscale-Adresse und ist dann für alle Geräte im eigenen Tailnet erreichbar. Läuft Tailscale nicht, bleibt er auf 127.0.0.1.
• Den API-Key kann auch dann nur der Rechner selbst setzen, auf dem buhu läuft – nicht das Handy oder ein anderes Gerät im Tailnet.

---

📜 Lizenz

Kostenlos für private, wissenschaftliche und gemeinnützige Nutzung. Jede kommerzielle Nutzung ist lizenzpflichtig.

Diese Software steht unter der PolyForm Noncommercial License 1.0.0.

✅ Erlaubt	Privatgebrauch, Lernen, Hobbyprojekte, Forschung und Lehre, gemeinnützige Organisationen und Behörden; Quellcode lesen, ändern und Änderungen weitergeben
❌ Lizenzpflichtig	Jede Nutzung mit Erwerbsbezug – insbesondere das Verwalten, Betreuen oder Automatisieren von Benutzerkonten für Dritte oder gegen Entgelt, der Betrieb als Dienst­leistung, betriebliche Nutzung in Unternehmen und die entgeltliche Weitergabe

Verbindliche Einzelheiten und Regelbeispiele: LIZENZ-HINWEISE.de.md Kommerzielle Lizenz anfragen: COMMERCIAL.md Beiträge und Rechteeinräumung: CONTRIBUTING.md

Bestandteile Dritter

buhu baut auf dem Projekt Ghost in the Droid (github.com/ghost-in-the-droid/android-agent) auf, das unter der MIT-Lizenz steht. Der vollständige Lizenztext und alle weiteren Hinweise stehen in THIRD-PARTY-NOTICES.md.

Hinweis: buhu ist eine eigenständige Erweiterung und steht in keiner Verbindung zum Projekt „Ghost in the Droid" oder zu ghostinthedroid.com. Es wird von diesen weder betrieben noch unterstützt oder gebilligt. Die MIT-Lizenz räumt keine Namens- oder Markenrechte ein.

Verantwortung beim Einsatz

Die Software automatisiert Endgeräte und Benutzerkonten. Ob ein konkreter Einsatz zulässig ist, richtet sich nach dem anwendbaren Recht und nach den Nutzungsbedingungen der jeweils angesteuerten Dienste. Die Prüfung und Einhaltung obliegt allein dem Nutzer.