Claude Code verhält sich seltsam, und du weißt nicht warum. Ein Hook reagiert nicht. Ein Skill überschneidet sich mit einem anderen. Eine Session liefert inkonsistente Ergebnisse. Solche Probleme entstehen in komplexen Setups fast zwangsläufig, und sie sauber zu debuggen kostet Zeit. claude-doctor ist dafür gebaut, diese Fehlersuche zu verkürzen.
Was ist claude-doctor?
claude-doctor ist ein Open-Source CLI-Tool, das deine lokale Claude Code Umgebung analysiert und bekannte Problemquellen aufspürt. Die Analogie zum Befehl brew doctor auf dem Mac ist treffend: Du rufst es auf, bekommst eine strukturierte Ausgabe mit Warnungen und Fehlern, und weißt danach genau, wo du nachbessern musst.
Das Tool liest deine Konfigurationsdateien, prüft deine installierten Skills, kontrolliert Hooks und schaut sich den lokalen Speicherzustand von Claude Code an. Es schreibt dabei nichts, ändert nichts. Es meldet nur, was nicht stimmt, und gibt dir in den meisten Fällen direkt einen Hinweis, wie du das Problem beheben kannst.
Wer ein überschaubares Setup mit zwei oder drei Skills und ohne eigene Hooks betreibt, wird das Tool selten brauchen. Wer aber viele Skills parallel installiert hat, mehrere MCP-Server nutzt und eigene Hooks schreibt, kennt das Gefühl: Irgendwas stimmt nicht, aber was genau, ist aus dem Bauch heraus schwer zu sagen.
Welche Probleme erkennt claude-doctor?
Das Tool prüft vier Kategorien systematisch durch.
Skill-Konflikte: Wenn zwei Skills ähnliche Trigger oder Befehle definieren, kann das zu unerwartetem Verhalten führen. Claude Code wählt dann einen der beiden, ohne es dir zu erklären. claude-doctor meldet solche Überschneidungen, bevor sie in einer Session Verwirrung stiften.
Hook-Failures: Hooks sind Skripte, die Claude Code bei bestimmten Ereignissen ausführt. Schlägt ein Hook fehl, passiert das oft lautlos. Das Tool überprüft, ob deine Hooks erreichbar sind und korrekt aufgerufen werden können, bevor du in einer Session auf den Fehler stößt.
Memory-Inkonsistenzen: Claude Code hält zwischen Sessions einen Speicherzustand vor. Wenn dieser Zustand beschädigt oder widersprüchlich ist, trifft Claude Entscheidungen, die du nicht nachvollziehen kannst. claude-doctor prüft die Konsistenz dieser Daten und meldet Auffälligkeiten.
Permission-Issues: Falsche Dateiberechtigungen auf Konfigurationsdateien oder Tool-Verzeichnissen produzieren Fehler, die auf den ersten Blick nichts mit Berechtigungen zu tun haben. Das Tool erkennt gängige Berechtigungsprobleme und benennt sie klar.
So nutzt du claude-doctor
Die Installation läuft über npm, du brauchst Node.js auf deinem Rechner:
# Global installieren
npm install -g claude-doctor
# Diagnose starten
claude-doctor
Die Ausgabe ist in drei Stufen gegliedert. Grüne Punkte bedeuten: alles in Ordnung. Gelbe Warnungen weisen auf potenzielle Probleme hin, die du im Blick behalten solltest. Rote Fehler sind Dinge, die aktiv behoben werden sollten, bevor du mit einer langen Session startest.
Zu jedem Befund gibt das Tool einen Erklärungstext und, wenn möglich, einen konkreten Lösungshinweis. Das unterscheidet claude-doctor von einem simplen Statuscheck: Es diagnostiziert, nicht nur meldet. Du verlässt die Ausgabe mit einem klaren nächsten Schritt statt mit einer kryptischen Fehlermeldung.
Wann lohnt sich der Einsatz?
Für einfache Setups ist claude-doctor ein optionales Extra. Ein Durchlauf kostet wenig Zeit und gibt Sicherheit, aber du wirst selten überraschende Befunde sehen.
Für komplexe Setups wird es schnell unverzichtbar. Sobald viele Skills zusammenkommen, eigene Hooks im Einsatz sind und mehrere MCP-Server laufen, steigt die Wahrscheinlichkeit von Konfigurationsdrift. Konfigurationsdrift bedeutet: Kleine Änderungen an verschiedenen Stellen schaukeln sich auf. Irgendwann entsteht ein Problem, das sich aus keiner einzelnen Änderung direkt ableiten lässt.
Besonders sinnvoll ist ein Durchlauf nach Updates: nach einer neuen Claude Code Version, nach dem Installieren mehrerer neuer Skills auf einmal oder nach Anpassungen an bestehenden Hooks. So weißt du direkt, ob etwas durch das Update aus dem Takt geraten ist.
Ein ergänzendes Werkzeug: Wer viele Skills parallel verwaltet und die Übersicht behalten will, sollte sich das Tool skills-manage ansehen, das Claude Code Skills zentral verwaltet. Gut organisierte Skills bedeuten weniger Überschneidungen, die claude-doctor später erst finden muss.
Häufige Fragen zu claude-doctor
Muss ich claude-doctor regelmäßig ausführen? Nicht zwangsläufig. Ein guter Zeitpunkt ist nach größeren Änderungen am Setup, nach Updates oder wenn sich Claude Code in einer Session unerwartet verhält. Als fester Schritt nach der Installation eines neuen Skills oder Hooks ergibt es aber Sinn.
Verändert das Tool meine Konfiguration? Nein. claude-doctor liest deine Umgebung aus und analysiert sie, schreibt aber selbst nichts. Es gibt Empfehlungen, du entscheidest, was du damit machst.
Funktioniert claude-doctor auch auf Windows? Das Tool läuft über Node.js und ist grundsätzlich plattformübergreifend. Auf Windows kann die Pfadauflösung für Konfigurationsdateien in einzelnen Fällen abweichen. Im GitHub-Repository des Projekts gibt es dazu Hinweise speziell für Windows-Nutzer.
Dieser Artikel wurde von Marcel Porcher, newways.ai, verfasst.
Wenn du Claude Code und KI-Automatisierung mit Gleichgesinnten lernen und anwenden willst: Komm in die kostenlose Claude Business Community. Dort lernst du Claude, Automatisierung, Co-Work, Claude Code, App-Building und Agent-Coding. Zeit sparen, Kosten sparen, Business skalieren: skool.com/unternehmernetzwerk-2071