Claude Code einrichten — Installation, Berechtigungen, Hooks, MCP in der ersten Stunde

Claude Code ist Anthropics offizielle agentische CLI. Nach der Einrichtung ist sie äußerst leistungsstark — wer beim Installieren jedoch das Berechtigungsmodell, CLAUDE.md, Hooks und MCP überspringt, wiederholt täglich dieselbe manuelle Arbeit. Dieser Leitfaden führt durch macOS / Linux / Windows (Git Bash oder WSL2): Install → Auth → Projektanleitung → Berechtigungen → Hooks → MCP — in dieser Reihenfolge.

Ich glaube, was Claude Code von anderen CLI-Tools unterscheidet, ist nicht die bloße Fähigkeit zur Code-Generierung, sondern das Berechtigungs- und Hook-System — weil es das erste Tool ist, das Sicherheit und Automatisierung als gleichwertige Erstklassenbürger behandelt. Anfangs hatte ich es ohne CLAUDE.md verwendet und festgestellt, dass jede Sitzung von vorne beginnen musste; heute ist die Projektkonfiguration das Erste, was ich einrichte.

Er richtet sich an Entwicklerinnen und Entwickler, die git und Node.js bereits komfortabel einsetzen, aber entweder neu bei Claude Code sind oder es bisher ohne saubere Einrichtung nutzen.

TL;DR

1. Node.js 20+ → npm install -g @anthropic-ai/claude-code → claude → Browser-Auth
2. CLAUDE.md (1–2 Bildschirme) + .claude/settings.json (Berechtigungen/Umgebung/Hooks) im Projektstamm ablegen
3. Drei Slash-Commands zum Start: /help, /config, /init
4. Wenn ein Befehl ständig abgelehnt wird, das Muster zu permissions.allow hinzufügen
5. MCP-Server nur hinzufügen, wenn wirklich benötigt — lokales stdio bevorzugen, Tokens in Umgebungsvariablen halten

Voraussetzungen

• Node.js 20+ — node -v. Älter? Per mise oder nvm aktualisieren
• Anthropic-Konto — console.anthropic.com oder ein Claude.ai Pro/Max-Abonnement
• Git — von der CLI zur Projektinspektion verwendet. Auf macOS: /mac/initial-setup
• Betriebssystem: macOS / Linux / Windows (Git Bash oder WSL2 empfohlen; rohes PowerShell funktioniert, reduziert aber sh-basierte Hook-Kompatibilität)

1. Installation — 5 Minuten

1.1 npm global installieren

npm install -g @anthropic-ai/claude-code

Berechtigungsfehler? Statt sudo das npm-Präfix ins Home-Verzeichnis verschieben:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

1.2 Erster Start + Auth

In das gewünschte Projekt wechseln und starten:

cd ~/projects/my-repo
claude

Beim ersten Start öffnet sich ein Browser-Tab für die Anthropic-Authentifizierung. Nach der Anmeldung startet die CLI einen Chat. Das Token wird im OS-Keychain gespeichert — eine erneute Authentifizierung ist daher nicht nötig.

1.3 Überprüfen

claude --version
# Gibt etwas wie 0.x.x aus

2. Drei Slash-Commands, die man zuerst kennen sollte

In der CLI beginnen Befehle mit /. Drei genügen für den Einstieg:

/init einmal pro neuem Projekt ausführen — es prüft Ordnerstruktur, Sprache und Build-Tools und erstellt einen soliden Startentwurf, der anschließend verfeinert werden kann.

3. CLAUDE.md — Projektanleitung (das Wichtigste)

CLAUDE.md ist eine Markdown-Datei im Projektstamm, die zu Beginn jeder Sitzung automatisch geladen wird. Darin definierte Regeln haben für die gesamte Sitzung höchste Priorität.

Eine gute CLAUDE.md

# Projekt — Claude-Anleitung
 
## Persona
(optional) Rollentipp, z. B. „Als erfahrener Ingenieur Diffs kritisch prüfen."
 
## Stack
- Framework: Next.js 16 (App Router)
- Sprache: TypeScript strict
- DB: Supabase
 
## Befehle
- Dev-Server: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test`
 
## Konventionen
- Kein `any` (TS strict)
- Dateinamen: kebab-case (Routen), camelCase (Utils)
- Niemals Secrets hardcoden
 
## Git
- Commits: `[Projekt] {Typ}: {Beschreibung}` — feat/fix/refactor/...
- Direkter Push nach main: OK (solo) / PR erforderlich (Team)
 
## Arbeitsprinzipien
1. Erst planen bei Änderungen mit 5+ Dateien / neuem Modul / Architektur
2. Nach Code-Änderungen nicht „fertig" melden, bis lint+build+tests bestanden haben
3. Secrets · DB-Migrationen · externe Pushes erfordern explizite Genehmigung

Tipps

• Kurz halten — 1–2 Bildschirme. Längeres gehört in memory/rules/{Thema}.md und wird von CLAUDE.md verlinkt.
• Projektspezifische Datei verwenden; projektübergreifende Anweisungen in ~/.claude/CLAUDE.md ablegen.
• CLAUDE.md in git einchecken, damit Teammitglieder und andere Maschinen sie automatisch übernehmen.

4. .claude/settings.json — Berechtigungen, Umgebung, Hooks

Diese Datei steuert das Laufzeitverhalten. Der am häufigsten bearbeitete Block ist permissions.

4.1 Grundgerüst

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(pnpm test:*)",
      "Read(/Users/me/projects/**)"
    ],
    "deny": [
      "Bash(rm -rf /:*)",
      "Bash(sudo *)"
    ]
  },
  "env": {
    "EDITOR": "code --wait"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "echo '[Sitzungsstart] $(date)'" }
        ]
      }
    ]
  }
}

4.2 Berechtigungsregeln (permissions.allow / deny)

• Wenn ein Bash(...)-Befehl ständig abgelehnt wird, ihn als Muster zu allow hinzufügen
• Muster werden als Präfix abgeglichen — Bash(pnpm:*) erlaubt alles, was mit pnpm beginnt
• Gefährliche Muster (rm -rf, sudo, curl … | bash) sicherheitshalber in deny aufnehmen

💡 Um häufige Read-Only-Befehle per Batch hinzuzufügen, den eingebauten Skill /fewer-permission-prompts in der CLI ausführen — er scannt Transkripte und schlägt eine Allow-List vor.

4.3 Herunterladbares Template

Dieselbe Konfiguration als fertige Datei (vor Verwendung prüfen):

# 1. Herunterladen
curl -fsSL https://devalice.jaceclub.com/assets/ai-agents/claude-code/settings.example.json -o .claude/settings.example.json
 
# 2. SHA-256 prüfen
shasum -a 256 .claude/settings.example.json
# Erwartet: 22898a20ade2b3497f8299a8ca6139112c476e0a0a4075e1a05123a02c8266ac
 
# 3. Prüfen, dann an die richtige Stelle kopieren
less .claude/settings.example.json
cp .claude/settings.example.json .claude/settings.json

Keine Secrets (API-Keys etc.) direkt in settings.json eintragen. Aus der OS-Umgebung oder einer gitignorierten .env-Datei lesen.

4.4 Global vs. Projekt vs. lokal

5. Hooks — automatische Auslöser

Hooks führen Shell-Befehle bei bestimmten Ereignissen aus. Die wichtigsten:

Beispiel 1: Umgebung beim Sitzungsstart ausgeben

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "printf '[Sitzungsstart] %s\\nBranch: %s\\n' \"$(date '+%F %T')\" \"$(git branch --show-current 2>/dev/null || echo keiner)\""
          }
        ]
      }
    ]
  }
}

Beispiel 2: Schreiben in sensible Dateien blockieren

PreToolUse kann per Exit-Code blockieren. (1 = warnen, 2 = blockieren.)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '\\.env$|secrets/|private_key' && { echo 'BLOCKIERT: Secret-Datei'; exit 2; } || exit 0"
          }
        ]
      }
    ]
  }
}

Spezifikationsdetails: /help → Docs-Link, oder die offiziellen Docs. Beim Debuggen mit einem einzeiligen echo-Hook beginnen, um zu bestätigen, dass er überhaupt feuert.

6. MCP-Server — nur wenn wirklich benötigt

MCP (Model Context Protocol) ist der Standard, um externe Tools für Claude Code verfügbar zu machen. Integrationen gibt es für GitHub, Slack, Linear, Figma — eigene Server lassen sich ebenfalls schreiben.

Registrierung

In mcpServers in .claude/settings.json eintragen:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

${GITHUB_TOKEN} wird aus der Shell-Umgebung expandiert — export GITHUB_TOKEN=... in .zshrc oder .envrc (direnv) eintragen, um den Token aus settings.json herauszuhalten.

Sicherheit

• Lokale stdio-Server bevorzugen (command: "npx" oder eine lokale Binary) — kleinere Angriffsfläche als vernetzte RPC-Server
• Nur verifizierte Pakete — @modelcontextprotocol/*, @upstash/* usw. Unbekannte Pakete zuerst prüfen
• Secrets per Umgebungsvariable — settings.json wird oft in git eingecheckt; Tokens niemals direkt eintragen

7. IDE-Integration — VS Code · Cursor

Claude Code ist eine CLI, lässt sich aber gut in IDEs einbinden:

• VS Code / Cursor — integriertes Terminal — einfach claude ausführen. Dateien in der IDE bearbeiten, im Terminal chatten. Einfachste Option.
• VS Code-Erweiterung — „Claude Code" im Marketplace suchen, um es in einem Seitenbereich zu öffnen.
• JetBrains (IntelliJ/PyCharm/…) — Plugin im JetBrains Marketplace verfügbar.

Wer bereits einen KI-nativen Editor (Cursor, Windsurf) nutzt, sollte Claude Code für Aufgaben wie „viele Dateien / Shell / git" einsetzen und den Editor-KI für Inline-Coding reservieren.

8. Überprüfen — ist die Einrichtung vollständig?

# 1. Installation
claude --version
 
# 2. Projekteinrichtungsdateien
ls -la CLAUDE.md .claude/settings.json
 
# 3. Globale Einrichtung (optional)
ls -la ~/.claude/settings.json 2>/dev/null && echo "global OK" || echo "kein global"
 
# 4. Auth — `claude` ausführen und nach dem Willkommens-Banner suchen
#    > claude
#    │ Welcome to Claude Code!

Wenn alle vier Punkte grün sind, ist die Einrichtung abgeschlossen. Erste echte Aufgabe: claude im Projektverzeichnis starten und z. B. fragen: „Beschreibe die Struktur dieses Repos in einem Absatz."

9. Fehlerbehebung

command not found: claude

• Das npm-Global-bin-Verzeichnis ist nicht im PATH. npm config get prefix ausführen → <prefix>/bin zu ~/.zshrc / ~/.bashrc hinzufügen
• Windows Git Bash: npm config get prefix sollte C:\Users\<Name>\AppData\Roaming\npm ausgeben — dieser Pfad muss im PATH stehen

Browser-Auth öffnet sich beim ersten Start nicht

• Headless-Umgebung (SSH, WSL2): URL aus der CLI manuell in einen Browser kopieren
• Falls die Auth danach weiterhin fehlschlägt, den Token-Cache unter ~/.claude/ löschen und erneut versuchen

Berechtigungsabfrage bei jedem Bash-Befehl

• Häufige Read-Only-Befehle zu permissions.allow in .claude/settings.json hinzufügen
• Oder /config → Berechtigungsmodus auf acceptEdits setzen (Bearbeitungen automatisch genehmigen, Shell weiterhin abfragen)

Hooks lösen nicht aus

# 1. JSON gültig?
cat .claude/settings.json | jq .
 
# 2. Befehl vereinfachen und prüfen
# command: "echo HOOK_FIRED >> /tmp/claude-hook.log"

Fehlerhaftes JSON deaktiviert den Hook-Abschnitt lautlos.

MCP-Server erscheint nicht

• /mcp in der CLI eingeben — registrierte Server und Status anzeigen
• Prüfen, ob command im PATH verfügbar ist (which npx)
• Logs unter ~/.claude/logs/ oder in stderr prüfen

10. Was als Nächstes kommt

Dieser Leitfaden endet mit „Claude Code ist täglich einsatzbereit". Was danach folgt:

• Workflow-Muster — Multi-Agenten, Plan-Modus, Subagents (demnächst)
• Cursor-Vergleich — /ai-agents/cursor-setup
• Erweiterte Hooks — SessionStart für Speicher-Sync, PreToolUse für Sicherheits-Gates
• Eigenen MCP-Server schreiben — interne Tools exponieren (demnächst)

Referenzen

• Claude Code offizielle Docs
• MCP offiziell
• Anthropic Console — API-Keys / Nutzung
• Claude Code GitHub Issues — Fehlerberichte

Changelog

• 2026-05-12 — Erste englische Übersetzung (devAlice M2 i18n Seed)