Einstieg: von null zu einem funktionierenden Harness

Dieses Tutorial führt Sie durch Ihre gesamte erste Apothem-Einrichtung. Sie beginnen ohne jede Installation und schließen mit einer echten Harness-Konfiguration ab — erzeugt aus einem Profil, das Sie geschrieben haben, verifiziert und als funktionierend bestätigt. Planen Sie etwa fünfzehn Minuten ein. Jeder Befehl unten ist echt und lässt sich per Kopieren und Einfügen ausführen.

Am Ende haben Sie:

1. Apothem über den Skript-Installer installiert.
2. Das gemeinsame Profil bearbeitet, das jeden Harness steuert.
3. Die native Konfiguration eines Harness materialisiert.
4. Diese Konfiguration verifiziert und einen funktionierenden ersten Lauf bestätigt.

Wir verwenden durchgehend Claude Code als Beispiel-Harness, weil es die Voreinstellung des Installers ist. Dieselben Schritte gelten für jeden unterstützten Harness — tauschen Sie den Namen aus, wenn Sie die Harness-Liste erreichen.

Was Sie zuerst brauchenCopy Anchor Link

• Eine Unix-artige Shell (macOS, Linux oder WSL). Der PowerShell-Installer deckt Windows ab; dieses Tutorial zeigt den bash-Weg.
• Python 3.10 oder neuer in Ihrem PATH. Prüfen Sie dies mit python3 --version.
• Die zwei Laufzeitbibliotheken, die die Engine aus Ihrem Interpreter importiert: click und rich. Der Rest des Stacks (pyyaml, jsonschema) ist in den Baum vendort, daher müssen nur diese beiden importierbar sein. Fehlt click oder rich, bricht der Installer ab und gibt den Installationsbefehl aus. Der einzeilige Befehl leitet das Skript an bash weiter und kann daher nicht nachfragen; setzen Sie APOTHEM_AUTO_INSTALL_DEPS=1 (zum Beispiel curl -fsSL https://apothem.ahmedgad.com/install.sh | APOTHEM_AUTO_INSTALL_DEPS=1 bash) oder installieren Sie zuvor die beiden Pakete.

Apothem wird als gebündelter Quellbaum statt als veröffentlichtes Paket ausgeliefert — es gibt keinen pip install-Schritt. Der Installer klont den Baum und führt die Engine direkt daraus aus.

Schritt 1 — Apothem installierenCopy Anchor Link

Führen Sie den Netzwerk-Installer aus:

curl -fsSL https://apothem.ahmedgad.com/install.sh | bash

Der Installer führt diese Schritte aus:

1. Prüfung der Voraussetzungen. Der Installer findet einen echten Python-3.10+-Interpreter und bestätigt, dass die beiden Laufzeitbibliotheken (click und rich) importierbar sind. Fehlt eine davon, nennt er sie, bricht ab und gibt den Installationsbefehl aus. Setzen Sie APOTHEM_AUTO_INSTALL_DEPS=1, um ohne Nachfrage zu installieren, da ein Lauf über eine Pipe nicht nachfragen kann.
2. Ablage des Quellcodes. Der gebündelte Baum wird nach ~/.apothem geklont (überschreibbar über die Umgebungsvariable APOTHEM_HOME). Ein erneuter Lauf checkt im bestehenden Klon das Release-Tag aus, statt ihn zu duplizieren.
3. Profil-Bootstrap. Wenn Sie noch kein Profil haben, kopiert der Installer das Beispielprofil nach ~/.config/apothem/profile.yaml, installiert und verifiziert daraus Claude Code im selben Lauf und warnt, dass die Identitätsfelder Platzhalter sind.

Sie können die Installation mit Umgebungsvariablen steuern. Diejenigen, die Sie am wahrscheinlichsten verwenden:

# Install a different user-scope harness and name the profile path explicitly.
# Put the variables on the `bash` side of the pipe: a variable placed before
# `curl` reaches only curl, not the installer.
curl -fsSL https://apothem.ahmedgad.com/install.sh | \
  APOTHEM_HARNESS=codex \
  APOTHEM_PROFILE="$HOME/.config/apothem/profile.yaml" \
  bash

Der Installer installiert nur benutzerbezogene Harnesses. Installieren Sie einen projektbezogenen Harness anschließend und nennen Sie dabei das Projekt:

apothem install --harness cursor --project /path/to/project

Weitere erkannte Variablen sind APOTHEM_REPO und APOTHEM_REF (welches Remote geklont und welche Git-Ref ausgecheckt wird — ungesetzt wird das neueste signierte Release-Tag aufgelöst und verifiziert; setzen Sie ein Tag, um es festzulegen, oder main für den beweglichen Branch (ein Branch ist kein signiertes Tag, daher braucht er zusätzlich APOTHEM_ALLOW_UNVERIFIED=1)), APOTHEM_ALLOW_UNVERIFIED=1 (stuft einen Fehlschlag der Tag-Signaturprüfung zu einer Warnung herab und erlaubt eine Nicht-Tag-Ref wie main), APOTHEM_SOURCE (verwendet einen vorhandenen lokalen Checkout statt eines Klons) und APOTHEM_SKIP_VERIFY=1 (überspringt die Verifizierung nach der Installation, die wir ausführen wollen; lassen Sie die Variable daher ungesetzt).

Wenn der Installer einen vollständigen Lauf abschließt, gibt er ein Banner aus, das zeigt, wie die Engine aufgerufen wird. Er legt einen apothem-Shim in Ihren PATH (POSIX: $HOME/.local/bin; Windows: %LOCALAPPDATA%\Microsoft\WindowsApps), sodass Sie die Engine direkt ausführen, sobald dieses Verzeichnis im PATH liegt:

apothem <command>

Falls der Shim nicht abgelegt werden konnte — oder sein Verzeichnis noch nicht im PATH liegt —, gibt das Banner eine eigenständige Ausweichlösung aus, die keinen Shim benötigt:

PYTHONPATH="$HOME/.apothem/src" python3 -m apothem <command>

Der Rest dieses Tutorials schreibt apothem <command>; wenn Sie die Ausweichform verwenden, stellen Sie das exakte Präfix voran, das Ihr Installer-Banner ausgegeben hat.

Schritt 2 — Das Profil zu Ihrem eigenen machenCopy Anchor Link

Das gemeinsame Profil unter ~/.config/apothem/profile.yaml ist die einzige Quelle der Wahrheit. Jeder Harness-Adapter liest es und leitet daraus die native Konfiguration seines Harness ab. Bearbeiten Sie es einmal, und jeder Harness, den Sie installieren, bleibt konsistent.

Öffnen Sie es im Editor der Engine oder in einem beliebigen Texteditor:

apothem profile edit

Ein minimales, gültiges Profil sieht so aus:

identity:
  name: "Example User"
preferences:
  style: "concise"
rules:
  - "Validate external input before writing files."

Ersetzen Sie den Platzhalter name durch Ihren eigenen Namen und fügen Sie alle Regeln hinzu, die jeder Harness durchsetzen soll. Halten Sie Beispielwerte fiktiv — das Profil ist dafür gedacht, gefahrlos geteilt werden zu können.

Bestätigen Sie, dass die Engine Ihre Bearbeitungen sauber zurückliest:

apothem profile show --json

Ist das YAML fehlerhaft, sehen Sie es an dieser Stelle — beheben Sie den Fehler und führen Sie den Befehl erneut aus, bevor Sie weitermachen.

Schritt 3 — Eine Harness-Konfiguration materialisierenCopy Anchor Link

Hat Ihr Lauf in Schritt 1 das Profil angelegt, hat er Claude Code bereits mit der Platzhalter-Identität installiert. Bearbeiten Sie das Profil in Schritt 2 und übernehmen Sie danach Ihre Identität mit:

apothem update --harness claude-code

apothem install --harness claude-code

Dies liest Ihr Profil und schreibt die native Konfiguration von Claude Code. So sehen Sie jeden Harness, den Sie ansprechen können:

apothem harnesses list

Einige Harnesses sind projektbezogen statt benutzerbezogen, und diese benötigen einen --project-Pfad, damit der Adapter weiß, wohin er schreiben soll:

apothem install --harness cursor --project .

Schritt 4 — Verifizieren und einen ersten Lauf bestätigenCopy Anchor Link

Das Materialisieren ist nur die halbe Geschichte. Bestätigen Sie nun, dass die Konfiguration korrekt angekommen ist:

apothem verify --harness claude-code

verify prüft, dass die verwalteten Konfigurationsdateien des Harness existieren und sich parsen lassen. Fügen Sie --profile PATH hinzu, schlägt er zusätzlich fehl, wenn eine installierte Datei von dem abgewichen ist, was dieses Profil erzeugen würde. Ein sauberer Lauf bedeutet, dass die Materialisierung erfolgreich war.

Für eine Zustandsprüfung der gesamten Maschine über jeden registrierten Adapter führen Sie Folgendes aus:

apothem doctor

doctor prüft jeden installierten Harness (er muss die Verifizierung bestehen, und seine registrierten Hook-Befehle müssen starten) und endet mit einem Exit-Code ungleich null, wenn eine Prüfung fehlschlägt. Harnesses, die Sie nicht installiert haben, werden aufgeführt, lassen den Befehl aber nicht fehlschlagen; damit ist er ein nützliches Gate in einem Einrichtungsskript.

Ihr erster Lauf. Öffnen Sie den Harness, den Sie gerade konfiguriert haben — in unserem Beispiel Claude Code —, und starten Sie eine Sitzung in einem beliebigen Projekt. Die Regeln und Präferenzen, die Sie in das Profil geschrieben haben, sind nun Teil des Verhaltens dieses Werkzeugs. Das ist der funktionierende erste Lauf: Das Profil, das Sie in Schritt 2 bearbeitet haben, prägt eine echte Sitzung.

Was Sie gebaut habenCopy Anchor Link

Ausgehend von einer leeren Maschine haben Sie Apothem installiert, ein gemeinsames Profil verfasst, daraus die native Konfiguration eines Harness materialisiert, das Ergebnis verifiziert und als funktionierend bestätigt. Das Profil ist das dauerhafte Artefakt — ändern Sie es einmal und führen Sie apothem update --harness <name> erneut aus, um die Änderung an jeden beliebigen Harness weiterzugeben.

Wie es weitergehtCopy Anchor Link

• Ein weiteres Werkzeug hinzufügen. Die Harness-Liste deckt jede unterstützte Plattform und ihren Adapternamen ab. Wiederholen Sie Schritt 3 mit einem neuen --harness.
• Bei einer einzelnen Aufgabe in die Tiefe gehen. Die How-to-Rezepte behandeln das Hinzufügen eines Harness, das Bearbeiten des Profils und das Steuern des Installers. Die Nutzungsanleitungen behandeln das Schreiben von Regeln, das Verfassen von Plänen und das Ausführen des Konformitäts-Gates.
• Details nachschlagen. Die Referenz dokumentiert jede Artefaktklasse und das Profilschema, und die CLI-Referenz deckt jeden Befehl ab. Jeder Adapter hat seine eigene Seite unter Harnesses.
• Arbeit planen, die eine Sitzung überdauert. Fortsetzbare Planung erklärt, wie Apothem lang laufende Arbeit in eine projektlokale .apothem/plans/-Suite auslagert, sodass eine neue Sitzung auf jeder beliebigen Maschine sie an Ort und Stelle fortsetzt.

Empfohlener nächster SchrittCopy Anchor Link

Führen Sie apothem doctor aus, um Ihre Einrichtung zu prüfen — es meldet den Zustand jedes registrierten Adapters, sodass der gerade installierte Harness als gesund erscheint, während die übrigen als noch nicht installiert erscheinen —, bevor Sie dazu übergehen, weitere Harnesses hinzuzufügen.