Wir bauen eine Open-Source-Alternative zu Claude Code in Python

Claude Code hat verändert, wie Entwickler über KI-Coding-Assistenten denken. Ein Agent, der in Ihrem Terminal lebt, Ihre Codebasis liest, Dateien bearbeitet, Befehle ausführt — kein Browser-Tab, kein Copy-Paste, keine Kontextfenster-Akrobatik.

Aber hier ist das Problem: Es ist ein geschlossener Monolith. Sie können das Modell nicht austauschen. Sie können das Toolset nicht erweitern. Sie können es nicht in Ihrer eigenen Infrastruktur deployen. Und wenn Sie Agenten für Kunden bauen — können Sie Claude Code nicht als Ihr Produkt ausliefern.

Wir wollten dieselbe Architektur — Planung, Checkpointing, Dateibearbeitung, Human-in-the-Loop — aber modular, Open-Source und auf Pydantic AI aufgebaut. Also haben wir es gebaut.

Was pydantic-deepagents wirklich ist

pydantic-deepagents (pydantic-deep) ist ein Python-Framework zum Erstellen von Deep Agents im Claude-Code-Stil — die Art, die plant, delegiert, sich erinnert und sich selbst korrigiert. Es wird in zwei Formen ausgeliefert:

1. Ein Framework — create_deep_agent() mit 30+ optionalen Features, die Sie ein- und ausschalten
2. Eine CLI — pydantic-deep chat — ein vollständig interaktiver Terminal-Assistent

Beides basiert auf Pydantic AI und folgt demselben Deep-Agent-Muster, das von Claude Code, Devin und Manus AI verwendet wird.

Der entscheidende Unterschied: Alles ist modular. Das Framework ist in 5 unabhängige Open-Source-Pakete aufgeteilt:

pydantic-deep              — Core-Agent + CLI
├── pydantic-ai-backend    — Dateispeicher (lokal, State, Docker, Daytona)
├── pydantic-ai-todo       — Aufgabenplanung mit Abhängigkeiten
├── subagents-pydantic-ai  — synchrone/asynchrone Agent-Delegation
├── summarization-pydantic-ai — Kontextmanagement + Sliding Window
└── pydantic-ai-middleware — Lifecycle-Hooks, Berechtigungen, Kostentracking

Jedes Paket funktioniert eigenständig. Sie können pydantic-ai-todo ohne den Rest verwenden. Sie können pydantic-ai-backend durch Ihre eigene Speicherschicht ersetzen. Das Framework kombiniert sie — Sie wählen, was Sie brauchen.

Die Ein-Funktions-API

Einen Agenten mit allen Features zu erstellen, erfordert einen einzigen Funktionsaufruf:

from pydantic_deep import create_deep_agent, DeepAgentDeps, StateBackend

agent = create_deep_agent(
    model="openai:gpt-4.1",
    instructions="You are a helpful coding assistant",
    include_plan=True,           # Planning subagent
    include_checkpoints=True,    # Save/rewind state
    include_memory=True,         # Persistent MEMORY.md
    include_skills=True,         # Slash commands
    cost_tracking=True,          # Budget enforcement
    cost_budget_usd=5.0,
)

deps = DeepAgentDeps(backend=StateBackend())
result = await agent.run("Refactor the auth module", deps=deps)

Jedes Feature ist ein Boolean-Flag. Brauchen Sie Teams? Fügen Sie include_teams=True hinzu. Wollen Sie Hooks? Übergeben Sie eine hooks-Liste. Das Framework stellt automatisch die richtigen Toolsets, Middleware und System-Prompt-Abschnitte zusammen.

Checkpointing und Rewind

Dies ist das Feature, das Ihre Arbeitsweise mit Agenten verändert. Jeder Tool-Aufruf erzeugt einen Checkpoint — einen Snapshot des Gesprächszustands. Wenn der Agent den falschen Weg einschlägt (und das wird er), spulen Sie zurück:

from pydantic_deep import InMemoryCheckpointStore, RewindRequested

store = InMemoryCheckpointStore()
agent = create_deep_agent(
    include_checkpoints=True,
    checkpoint_store=store,
    checkpoint_frequency="every_tool",
)

while True:
    try:
        result = await agent.run(user_input, deps=deps, message_history=history)
        history = result.all_messages()
    except RewindRequested as e:
        print(f"Rewinding to '{e.label}'...")
        history = e.messages

Der Agent sagt “save_checkpoint(‘before refactor’)” vor riskanten Operationen. Sie sagen “rewind to ‘before refactor’”, wenn etwas kaputt geht. Der Gesprächszustand wird zurückgesetzt — kein verlorener Kontext, kein erneutes Erklären der Aufgabe.

In der CLI erscheinen Checkpoints als benannte Snapshots, zwischen denen Sie hin- und herspringen können. Wie Git-Commits für Ihre Agent-Konversation.

Agent-Teams

Einzelne Agenten stoßen bei komplexen Aufgaben an ihre Grenzen. Unsere Lösung: flache Teams mit geteiltem Zustand.

from pydantic_deep.toolsets.teams import AgentTeam, TeamMember

team = AgentTeam(
    name="backend-team",
    members=[
        TeamMember(name="alice", role="api-designer",
                   instructions="Focus on clean REST API design"),
        TeamMember(name="bob", role="db-architect",
                   instructions="Design efficient database schema"),
    ],
)

# Assign tasks with dependencies
task_a = await team.todos.add("Design the API schema", created_by="lead")
task_b = await team.todos.add("Implement endpoints",
                               blocked_by=[task_a], created_by="lead")

Jedes Teammitglied teilt sich eine SharedTodoList (asyncio-sichere Aufgabenzuweisung mit Abhängigkeiten) und einen TeamMessageBus für Peer-to-Peer-Kommunikation. Keine hierarchischen Subagent-Ketten — Agenten koordinieren sich als Gleichgestellte, beanspruchen Aufgaben und senden sich gegenseitig Nachrichten, wenn sie Input benötigen.

Hooks — Lifecycle-Events im Claude-Code-Stil

Jeder Tool-Aufruf in pydantic-deep löst Lifecycle-Events aus. Sie fangen diese mit Hooks ab:

from pydantic_deep import Hook, HookEvent, HookInput, HookResult

async def safety_gate(hook_input: HookInput) -> HookResult:
    if "rm -rf" in str(hook_input.tool_input):
        return HookResult(allow=False, reason="Dangerous command blocked")
    return HookResult(allow=True)

agent = create_deep_agent(
    hooks=[
        Hook(
            event=HookEvent.PRE_TOOL_USE,
            handler=safety_gate,
            matcher="execute",
        ),
        Hook(
            event=HookEvent.POST_TOOL_USE,
            command="echo '$TOOL_NAME' >> /tmp/audit.log",
        ),
    ],
)

Drei Event-Typen: PRE_TOOL_USE, POST_TOOL_USE, POST_TOOL_USE_FAILURE. Hooks können Python-Handler oder Shell-Befehle sein. Exit-Code 0 = erlauben, Exit-Code 2 = ablehnen.

Benutzerdefinierte Slash-Commands

Legen Sie eine Markdown-Datei in .pydantic-deep/commands/ ab, und sie wird zu einem Slash-Command:

# /commit

Create a conventional git commit for the current changes.

## Instructions
1. Run `git diff --staged` to see what's staged
2. If nothing is staged, run `git add -A`
3. Generate a commit message following Conventional Commits
4. Run `git commit -m "..."` with the generated message

Die CLI wird mit eingebauten Commands ausgeliefert: /commit, /pr, /review, /test, /fix, /explain. Drei-Ebenen-Erkennung: eingebaut, Benutzerebene (~/.pydantic-deep/commands/) und Projektebene (.pydantic-deep/commands/).

Die CLI-Terminal-UX

Die CLI (pydantic-deep chat) ist der Ort, an dem alles zusammenkommt:

Diff-Viewer für Datei-Freigaben. Wenn der Agent eine Datei bearbeiten will, sehen Sie vor der Freigabe einen farbigen Unified-Diff mit Randmarkierungen.

Kontext-Fortschrittsbalken. Die Statusleiste zeigt Modellname, aufgelaufene Kosten und einen visuellen Kontextauslastungs-Indikator. Schwellenwert-Farben: Grün unter 60%, Gelb bei 60–85%, Rot über 85%.

Streaming mit Braille-Spinner. Text wird mit einem nahtlosen Übergang gestreamt — Braille-Spinner während des Denkens, dann Live-Markdown-Rendering.

@file-Erwähnungen mit Tab-Vervollständigung. Tippen Sie @src/ ein und erhalten Sie Autovervollständigung für Dateien, die in den Kontext aufgenommen werden sollen.

Persistenter Speicher

Der Agent pflegt eine MEMORY.md-Datei — persistente Notizen, die über Sitzungen hinweg erhalten bleiben:

agent = create_deep_agent(include_memory=True)
# Agent can call: read_memory, write_memory, update_memory
# MEMORY.md auto-injected into system prompt (first 200 lines)

In der CLI verwenden Sie /remember, um Präferenzen zu speichern: “immer pytest verwenden, niemals unittest.” In der nächsten Sitzung weiß der Agent bereits Bescheid. Dasselbe Muster wie bei Claude Codes Memory, mit derselben 200-Zeilen-Auto-Injection.

Wichtigste Erkenntnisse

• Deep Agents sind ein Muster, kein Produkt — Claude Code hat die Architektur bewiesen, aber Sie brauchen kein geschlossenes Tool, um sie zu bauen
• Modularität gewinnt — 5 Pakete, die sich zusammensetzen lassen, statt 1 Monolith bedeutet, dass Sie jede Schicht austauschen können, ohne alles neu zu schreiben
• Checkpointing verändert den Workflow — Agent-Sitzungen wie Git-Branches zu behandeln (speichern, zurückspulen, forken) macht KI-Coding-Assistenten dramatisch nützlicher
• Die CLI ist das Interface — für Coding-Aufgaben schlägt ein Terminal-Agent jedes Chat-Fenster

Ausprobieren: pydantic-deepagents auf GitHub — pip install pydantic-deep[cli]