dotagent

CLI-Toolkit für AI-Agent-Infrastruktur: .agent-Ordner, Tool-Discovery, Credential-Management, Knowledgebase, Vision-Tool und Bildgenerierung – alles in einem Paket.

Quickstart

1. Installation

# Empfohlen: via pipx (isolierte Installation)
pipx install "dot-agent[all]"

# Oder via pip
pip install dot-agent          # Basis (CLI, init, tools, setup)
pip install "dot-agent[all]"   # Alles: Knowledgebase + Vision + Bildgenerierung

Oder via Repo:

# Aus dem Repository (Entwicklungsmodus)
git clone <repo-url>
cd dotagent
pip install -e ".[dev]"

2. Globales Setup

# Globalen ~/.agent/-Ordner mit Templates anlegen
dotagent init

Das erstellt ~/.agent/ mit rules.md, functional.md, projects.md und config.toml.

Sicher für bestehende Setups: Bereits vorhandene Dateien werden nie überschrieben – nur fehlende Dateien werden angelegt. Der Output zeigt genau, was erstellt und was übersprungen wurde.

3. Credentials einrichten

# Status aller Credentials prüfen
dotagent setup --check

# Interaktiver Wizard für fehlende Credentials
dotagent setup

# Einzelnes Credential einrichten
dotagent setup openai

4. Projekt einrichten

cd mein-projekt

# Projektlokalen .agent/-Ordner anlegen
dotagent init .

# Mit Projektname (für ~/.agent/projects.md)
dotagent init . --name "Mein Projekt"

Das erstellt .agent/ mit agent.md, status.md, log.md, specification.md, plans/ und Symlinks auf die globalen rules.md / functional.md.

Auch hier gilt: Bestehende Dateien und Symlinks werden nicht angetastet.

5. Loslegen

# Verfügbare Tools anzeigen
dotagent tools

# Projektstatus
dotagent status

# Projektübersicht
dotagent projects

---

CLI-Referenz

Infrastruktur

Befehl	Beschreibung
dotagent init	Globalen ~/.agent/-Ordner anlegen
dotagent init .	Projektlokalen .agent/-Ordner anlegen
dotagent init . --name "Name"	Mit Projektname für projects.md
dotagent setup --check	Credential-Status prüfen
dotagent setup	Interaktiver Setup-Wizard
dotagent setup <provider>	Einzelnes Credential einrichten
dotagent setup --write-zshrc	Export-Befehle direkt in ~/.zshrc schreiben
dotagent tools	Alle verfügbaren Tools auflisten
dotagent tools --json	JSON-Output (maschinell)
dotagent tools --agent	Markdown für Agent-System-Prompt
dotagent projects	Projektübersicht aus ~/.agent/projects.md
dotagent status	Status des aktuellen Projekts

Knowledgebase (dotagent kb)

Semantische Suche über E-Books und Dokumente (benötigt pip install "dot-agent[kb]").

Befehl	Beschreibung
dotagent kb init <pfad> --name <name>	Neue Knowledgebase aus Ordner erstellen
dotagent kb search "query" --name <name>	Semantisch suchen
dotagent kb search "query" --name <name> --json	Suchergebnisse als JSON
dotagent kb ask "Frage" --name <name>	RAG-basierte Antwort
dotagent kb kbs	Alle Knowledgebases auflisten

Vision-Tool (dotagent vision)

Bilderkennung für AI-Agents – Screenshots, Diagramme, Fotos beschreiben (benötigt pip install "dot-agent[vision]").

Befehl	Beschreibung
dotagent vision describe bild.png	Bild beschreiben
dotagent vision describe bild.png --prompt "Was zeigt dieser Fehler?"	Gezielte Analyse
dotagent vision describe https://example.com/img.png	URL-Support
dotagent vision describe bild.png --json	JSON-Output
dotagent vision describe bild.png --model gpt-4.1	Anderes Modell

Bildgenerierung (dotagent beuys)

KI-Bildgenerierung via OpenAI gpt-image-1-mini (benötigt pip install "dot-agent[beuys]").

Befehl	Beschreibung
dotagent beuys generate "Prompt"	Bild generieren und öffnen
dotagent beuys generate "Prompt" --no-open	Ohne automatisches Öffnen
dotagent beuys generate "Prompt" -o ./images	Ausgabeverzeichnis festlegen

---

Überschreibschutz

dotagent init ist idempotent und sicher für bestehende Setups:

• Dateien: Werden nur erstellt, wenn sie noch nicht existieren (_write_if_missing)
• Symlinks: Werden nur erstellt, wenn weder Datei noch Symlink vorhanden
• Verzeichnisse: Werden nur erstellt, wenn sie noch nicht existieren
• Output: Zeigt für jede Datei an, ob sie erstellt oder übersprungen wurde

✅ Globales Init (~/.agent/)

  Übersprungen (existiert bereits):
    • /Users/.../.agent/rules.md
    • /Users/.../.agent/functional.md
    • /Users/.../.agent/projects.md
    • /Users/.../.agent/config.toml

Das bedeutet: dotagent init kann jederzeit erneut ausgeführt werden – bestehende Konfigurationen, Projekte und Agent-Anweisungen bleiben unverändert.

---

Architektur

src/dotagent/
├── cli.py              # Typer CLI: Hauptgruppe mit Subcommand-Gruppen
├── config.py           # Globale Konfiguration
├── core/
│   ├── init.py         # .agent-Ordner anlegen (global + projektlokal)
│   ├── tools.py        # Tool-Registry: Discovery, Dokumentation
│   ├── config_toml.py  # TOML-basierte Konfiguration
│   └── credentials.py  # API-Key-Management
├── kb/                 # Knowledgebase (Subcommand-Gruppe)
│   ├── cli.py
│   └── core/
├── beuys/              # Bildgenerierung (Subcommand-Gruppe)
│   ├── cli.py
│   └── core/
└── templates/          # Templates für agent.md, rules.md, functional.md, status.md

.agent-Ordner-Struktur

Global (~/.agent/)

Datei	Funktion
rules.md	Coding-Standards, Architektur, Workflow
functional.md	FP-Regeln für Code-Generierung
projects.md	Zentrale Projektübersicht
config.toml	Konfiguration und Credential-Specs
tools.d/	Externe Tool-Definitionen (.toml-Dateien)

Projektlokal (<projekt>/.agent/)

Datei	Funktion
agent.md	Projektspezifische Agent-Anweisungen
rules.md	Symlink → ~/.agent/rules.md
functional.md	Symlink → ~/.agent/functional.md
status.md	Projektstatus (maschinenlesbar)
log.md	Änderungsprotokoll
specification.md	Projektspezifikation
plans/	Pläne und Feature-Dokumente

Credentials

Unterstützte Provider:

Provider	Env-Vars	Benötigt für
OpenAI	OPENAI_API_KEY	kb, beuys
Atlassian	JIRA_USER_EMAIL, JIRA_API_TOKEN	Jira/Confluence
GitLab	GITLAB_TOKEN, GITLAB_URL	GitLab API

Externe Tools registrieren

Eigene Tools können als .toml-Dateien in ~/.agent/tools.d/ registriert werden:

# ~/.agent/tools.d/mein-tool.toml
[tool]
name = "mein-tool"
description = "Beschreibung"
commands = ["mein-tool run", "mein-tool status"]

Diese erscheinen dann in dotagent tools und dotagent tools --agent.

Entwicklung

# Installation für Entwicklung
pip install -e ".[dev]"

# Tests ausführen
pytest

# Mit Coverage
pytest --cov=dotagent

# Einzelne Test-Datei
pytest tests/test_init.py -v

Voraussetzungen

• Python ≥ 3.11
• Für kb: OpenAI API Key, faiss-cpu, pymupdf
• Für beuys: OpenAI API Key

Lizenz

MIT