Communitygithub.com

glyph

Glyph ist eine Werkbank, um die Formen der heutigen Intelligenz zu komponieren – und die Sprache zu entdecken, die sie morgen sprechen wird.

Was ist glyph?

Diese Skill befähigt KI-Agenten, einen Glyph-Server über dessen CLI zu steuern. Sie bildet das gesamte `glyph`-Befehlsfläche ab, einschließlich der nicht offensichtlichen Konventionen wie der Workspace-Scoping-Disziplin, die Befehle vor Konflikten mit anderen Clients schützt, und der Exit-Code/Error-Code-Disziplin, die mechanische Verzweigungen bei Fehlern ermöglicht. Der Agent kann Workspaces, Sitzungen, Aufgaben (Tasks), Zeitpläne (Schedules), Katalogeinträge, Workflows und Laufzeiten verwalten sowie Server-Health und Logs abfragen. Die Plattform setzt auf JSON-Ausgabe für stabile Datenverarbeitung und strukturierte Fehlermeldungen mit `fix:`-Anweisungen, die den nächsten CLI-Befehl direkt vorgeben. Referenzdokumente wie `references/commands.md`, `references/playbooks.md`, `references/json-shapes.md` und `references/error-codes.md` sind als unabdingbare Lektüre für nicht-triviale Arbeiten hinterlegt.

Funktioniert mit~Claude Code~Codex CLI~Cursor
npx skills add glyphs-ai/glyph

In Ihrer bevorzugten KI fragen

Öffnet einen neuen Chat, in dem dieser Agent-Skill bereits geladen ist.

Dokumentation

Skill für offizielle CLI

Du bist eine KI, die einen Glyph-Server über seine CLI steuert. Diese Skill ist eine Karte der gesamten glyph-Befehlsfläche plus der Konventionen, die aus --help nicht ersichtlich sind – insbesondere die Workspace-Scoping-Disziplin, die verhindert, dass deine Befehle mit anderen Clients in Konflikt geraten, und die Exit-Code/Error-Code-Disziplin, die es dir erlaubt, mechanisch auf Fehler zu reagieren.

Einrichtung

glyph injiziert bei der Erstellung einer Aufgabe oder Sitzung die benötigten Umgebungsvariablen:

  • GLYPH_SERVER – Server-URL (von der CLI automatisch verwendet)
  • GLYPH_WORKSPACE – Workspace-UUID (Workspace-begrenzte Befehle erben sie)

Schnellüberprüfung:

glyph health         # Exit-Code 0 ⇒ CLI funktioniert + Server erreichbar
glyph workspace current --json | jq   # bestätigt aufgelösten Workspace

Befehlsfläche auf einen Blick

Jeder Workspace-begrenzte Befehl erbt --server / --workspace-id / --output / --json und folgt der untenstehenden gemeinsamen Exit-Code-Tabelle. Die Befehlsgruppen:

GruppeZweckReferenz
workspaceWorkspaces erstellen / auflisten / anzeigen / aktualisieren / entfernen / neu laden; aktuelle ID ausgebenreferences/commands.md#workspace
sessionInteraktive Sitzungen verwalten (auflisten / neu / anzeigen / löschen / Terminal starten)references/commands.md#session
taskEinmalige Aufgaben ausführen, auflisten (auch gefiltert nach --origin), inspizieren, Aktivität verfolgen, abbrechen, entfernenreferences/commands.md#task
scheduleCron-gesteuerte Aufgabenplaner (erstellen / auflisten / patchen / aktivieren / deaktivieren / ausführen / Vorschau / Aufgaben auflisten)references/commands.md#schedule
catalogAgents, Skills, MCPs installieren / synchronisieren / aktivieren / deaktivierenreferences/commands.md#catalog
workflowWorkflow starten, dessen Live-DAG lesen/ändern (expandieren, Knotenspezifikation eines not_started-Knotens via update-spec patchen), auf menschliche Knoten antworten, beendenreferences/commands.md#workflow
runtimeRegistrierte Laufzeiten auflisten (Copilot, etc.)references/commands.md#runtime
Server-Inspektionhealth, config, status, logs – kein Lebenszyklusreferences/commands.md#server-inspection
Server-Lebenszyklusserve / start / stop / restart – nicht Bestandteil dieser Skill—

Workspace-Disziplin

Jeder Workspace-begrenzte Befehl benötigt einen expliziten Selektor. Die CLI liest GLYPH_WORKSPACE aus deiner Umgebung (bereits gesetzt), daher funktionieren Befehle direkt:

glyph task dispatch --agent writer --brief "..."

Um auf einem anderen Workspace zu arbeiten, übergib --workspace-id <id> pro Befehl:

glyph task list --workspace-id ws-Y

Die CLI konsultiert keinen serverseitigen, gemeinsamen "aktuellen Workspace"-Zustand – Selektoren sind prozesslokal und immun gegen Störungen durch andere Clients (andere CLI-Sitzungen, Dashboard-Tabs, KI-Agenten auf demselben Server).

Ausgabe-Disziplin

  • Für die maschinelle Verarbeitung immer --json übergeben. Das menschenlesbare / Tabellenformat ist kein stabiler Vertrag – Spaltenreihenfolge und -überschriften ändern sich zwischen Versionen.
  • Für Streaming-Aktivitäten mit jq -c weiterleiten, um ein Ereignis pro Zeile zu erhalten.
  • Jede --json-Form, die du wahrscheinlich verwenden wirst, ist in references/json-shapes.md dokumentiert. Konsultiere sie, bevor du einen jq-Filter schreibst – die meisten Formen haben optionale Felder (vorhanden, wenn die zugrunde liegende Zeile nicht null ist), die du als Ankerpunkte verwenden solltest.

Fehler-Disziplin

Fehler auf stderr enthalten immer einen code:

agent "writer" is not ready: prereqs not acknowledged (HTTP 409, EntryNotReadyError)
  agent: acme/writer
  cause: prereqs not acknowledged
  fix:   glyph catalog agent ack-prereqs acme/writer

Die Zeile fix: ist dein nächster Befehl, unverändert. Der vollständige code-Katalog (alle Fehlernamen + typischer HTTP-Status + Abhilfe) befindet sich in references/error-codes.md. Insbesondere:

  • EntryNotReadyError ist der mit Abstand häufigste Verzweigungspunkt – er enthält einen strukturierten reason, der beschreibt, ob der Agent ack-prereqs benötigt, disabled ist, missingDeps oder blockedDeps (rekursiv) hat. Die Tabelle der Gründe befindet sich in references/error-codes.md#entrynotreadyerror-reasons.

Exit-Codes

CodeBedeutungVorgehen
0Erfolgfortsetzen
1Generischer Fehler (inkl. fehlender Workspace)stderr lesen; meist fehlendes Flag/Env
2Nutzungsfehler (fehlendes Pflicht-Flag, entfernte Untergruppe)Aufruf korrigieren; nicht unverändert wiederholen
3Server nicht erreichbarBenutzer bitten, glyph start auszuführen oder --server zu prüfen
4Server hat 4xx/5xx zurückgegebencode in stderr lesen; references/error-codes.md konsultieren

Exit-Code 2 bedeutet "der Befehl selbst ist falsch" – wiederhole ihn niemals, ohne den Aufruf zu ändern. Exit-Code 4 bedeutet "der Server hat dies abgelehnt" – lies das code-Feld, es sagt dir den nächsten Schritt.

Fallstricke

  • Um auf eine Aufgabe zu warten, verwende glyph task activity <tid> --follow (Echtzeit-SSE). Das Abfragen von task list in einer Shell-Schleife verschwendet Zyklen und hinkt den echten Ereignissen hinterher.
  • Für eine einmalige "Was ist bisher passiert?"-Momentaufnahme entferne --follow – glyph task activity <tid> --json gibt die aktuelle Aktivität plus totalItems in einem Aufruf zurück. --follow blockiert, bis die Aufgabe beendet ist.
  • Beende vor dem Entfernen. Ein einfaches task rm <tid> setzt voraus, dass die Aufgabe in einem Endzustand ist (succeeded / failed / cancelled); wenn sie noch läuft, rufe zuerst glyph task cancel <tid> auf, dann task rm. Greife nur zu --purge, wenn du auch das Arbeitsverzeichnis und den Laufzeitzustand entfernen möchtest (dann ist stderr.log für die Nachlese verloren). Gleiche Unterscheidung bei session rm und workspace rm.
  • Setze --follow immer mit der ausgegebenen last seq: fort. Bei jedem sauberen Exit (event: end oder Stream geschlossen) UND bei einem Fehler mitten im Stream gibt die CLI last seq: <N> auf stderr aus – übergib --after <N> beim nächsten --follow-Aufruf, um ohne Lücken oder Duplikate fortzusetzen. Strg+C ist die Ausnahme (stderr wird nicht geleert); leite die Seq aus dem letzten stdout-NDJSON-Element ab (... | tail -1 | jq .seq). Das vollständige Wiederaufnahme-Playbook befindet sich in references/playbooks.md#monitor-a-long-running-task.
  • Workspace-IDs immer von glyph workspace list --json | jq beziehen. Dashboard-URL-Fragmente driften zwischen Versionen und sind kein stabiler Vertrag.
  • schedule patch ist dünn besiedelt – nur die übergebenen Flags werden auf die Leitung gelegt. Um ein Feld zu entfernen, übergib --clear-details / --clear-runtime (ein leeres --details "" wird als weggelassen behandelt, nicht als Löschung).

Referenzen (obligatorische Lektüre vor nicht-trivialen Arbeiten)

  • references/commands.md – Referenz der Unterbefehle pro Gruppe (workspace / session / task / schedule / catalog / workflow / runtime / server inspection). Einmal überfliegen, als Nachschlagewerk behalten.
  • references/playbooks.md – Mehrschrittige, zielorientierte Playbooks (Agent installieren und verifizieren, Aufgabe ausführen und warten, Aufgabe überwachen, Eintrag synchronisieren, aufräumen, neuen Workspace einrichten, lokalen Agenten spontan erstellen).
  • references/json-shapes.md – Die gängigen --json-Payload-Formen mit konkreten Feldlisten und Hinweisen zur Optionalität.
  • references/error-codes.md – Jeder code-Wert, den der Server ausgibt, plus der passende glyph-Befehl zur Behebung.

Verwandte Skills