Erweiterung

Claude Code lässt sich über verschiedene Mechanismen erweitern. Diese Guideline beschreibt zwei Kategorien - projektlokale Erweiterungen und globale Tool-Installationen - und wie beide im Setup eingebunden sind.

Projektlokale Erweiterungen

Projektlokale Claude-Konfigurationen funktionieren im Setup dieser Guideline ohne Einschränkung. Dazu gehören:

Dateien im .claude-Verzeichnis
Agents und Skills
Kontext-Dateien wie CLAUDE.md

Diese Dateien liegen im Projekt selbst und werden über den Workspace-Mount in die AI-Container eingebunden. Sie sind reine Projektdateien und benötigen keine zusätzliche Installation oder Konfiguration im Container.

Erweiterung durch Tool-Installationen

Tools wie etwa npx-basierte Skills können im ai-agent-Container zur Laufzeit installiert werden.

Laufzeit-Installationen im ai-agent-Container sind nicht im ai-Container verfügbar. Wer Tools in beiden Containern braucht, installiert sie pro Container - oder nimmt sie ins eigene abgeleitete AI Docker Image auf.

Dabei gelten zwei Regeln:

Persistente Tool-Installationen mit npm install erfolgen ausschließlich global mit dem -g-Flag
Installationen durch npm sowie Ausführung von npx werden analog zum Dependency Docker Image durch Socket Firewall (sfw) geschützt

Warum nur globale Installationen

Installationen im ai-agent-Container mit npm install (ohne -g) würden npm dazu veranlassen, in das Projektverzeichnis zu schreiben - konkret in node_modules und in die package.json bzw. das Lockfile des Projekts.

Die projektspezifischen node_modules sind jedoch ausschließlich dem Projekt vorbehalten (daher im ai- und ai-agent-Container auch als read-only Volume gemountet) und nicht für die Installation von weiteren AI-Tools vorgesehen.

Sollte die Installation mit npm install (ohne -g) ausgeführt werden, hätte das zwei unerwünschte Effekte:

npm würde package.json und das Lockfile im Workspace modifizieren, anschließend aber am Schreiben (auf Grund des read-only Volume) in node_modules scheitern → inkonsistenter Zustand
AI-spezifische Tools würden sich mit den Projekt-Dependencies vermischen und die saubere Trennung zwischen Projekt- und AI-Kontext aufweichen

Globale Installationen mit -g landen dagegen im hierfür vorgesehenen Pfad /usr/local/share/npm-global/ (siehe AI Docker Image) und berühren das Projekt nicht.

Persistenz

Globale Installationen im ai-agent-Container sind nicht persistent. Sie überleben einen Container-Neustart nicht.

Wenn Tools dauerhaft benötigt werden, können sie ins eigene abgeleitete Docker Image eingebaut werden.