Eigene Agents,
eine Zeile JSON.

In einem Terminal, während Gnista läuft:

G=/Applications/Gnista.app/Contents/Helpers/gnista
echo '{"session":"demo","event":"needs-you","message":"Ralph wants to deploy","cwd":"'"$PWD"'"}' | "$G" hook custom ralph

Eine Sitzung von „Ralph“ taucht auf und braucht dich. Klick sie an, und du bist zurück in diesem Terminal. Dann:

echo '{"session":"demo","event":"done","message":"Deployed"}' | "$G" hook custom ralph
echo '{"session":"demo","event":"end"}' | "$G" hook custom ralph

Der Helper endet immer mit 0 und wartet nie, er kann dein Tool also nicht aufhalten. Stimmt etwas mit dem Gesendeten nicht, sagt er es auf stderr und schickt nichts.

gnista hook custom <name> [event]

<name> ist der Name deines Agents: bis zu 32 Kleinbuchstaben, Ziffern, - und _, am Anfang ein Buchstabe oder eine Ziffer. Die Namen der eingebauten Agents (claude, codex und die anderen) sind vergeben. Das Event kann statt im JSON auch hier stehen, für Tools, die für jedes Event einen anderen Befehl ausführen.

Ein JSON-Objekt pro Aufruf, auf stdin:

Groß- und Kleinschreibung und Trennzeichen sind egal: needs-you, NeedsYou und needs_you sind dasselbe.

Eine Sitzung, die arbeitet und dann still wird, gilt nach ein paar Minuten als untätig (Einstellungen ▸ Allgemein ▸ Inaktiv nach).

Optional. Sie liegt unter ~/Library/Application Support/Gnista/Agents/<name>.json. Jeder Schlüssel ist optional:

{
  "name": "Ralph",
  "icon": "ralph.svg",
  "fields": {
    "session": "$.conversation_id",
    "event": "$.hook_event_name",
    "cwd": "$.workspace_roots[0]",
    "tool": "$.tool.name"
  },
  "events": {
    "beforeSubmitPrompt": "prompt",
    "afterToolUse": "tool-done",
    "stop": "done",
    "heartbeat": "ignore"
  },
  "host": "com.example.Ralph",
  "jump": { "url": "ralph://open?session={session}" },
  "doneAfterTools": ["attempt_completion"]
}

Eine Datei über 1 MB, oder mit irgendeinem Fehler darin (ein unbekannter Schlüssel, ein Pfad, der keiner ist, ein Event, das Gnista nicht kennt), wird als Ganzes ignoriert. Einstellungen ▸ Agents ▸ Eigene Agents zeigt sie mit dem Grund, und der Helper sagt es auf stderr. Das einfache Format von oben funktioniert so lange weiter.

Mit "version": 2 kann die Datei Gnista auch sagen, wie es deinen Agent verbindet, so wie es die eingebauten verbindet: welche Hooks in die eigene Konfiguration des Agents kommen, wie Gnista liest, was sie senden, ob sich seine Berechtigungsanfragen von der Notch aus beantworten lassen und wo sein Transkript liegt, damit seine Zeile deine Eingabe, seine Antwort und die Kosten zeigt. Die Schlüssel von Version 1 behalten ihre Bedeutung.

{
  "version": 2,
  "name": "Ralph",
  "colour": "#2EB872",
  "adapter": "claude-style",
  "hooks": {
    "format": "claude-table",
    "file": ".ralph/settings.json",
    "events": ["UserPromptSubmit", "PreToolUse", "PostToolUse", "PermissionRequest", "Stop", "SessionEnd"],
    "timeout": 5
  },
  "approvals": "plain",
  "details": "claude"
}

Einstellungen ▸ Agents listet deinen Agent dann zu den anderen: Verbindest du ihn dort, fügt Gnista seine Hooks in die Datei ein, die du genannt hast, und beim Trennen nimmt es sie wieder heraus. Gnista ändert nur seine eigenen Einträge und legt vorher eine Sicherung der Datei an. Die Hooks rufen gnista hook custom <name> auf, mit dem Event.

Klickst du auf eine Sitzung, bringt Gnista dich zu ihrem Terminal-Tab oder Fenster. Für Apps, in die es keinen Weg hinein hat, gibt ihm eine Sprungregel stattdessen eine URL zum Öffnen: nachdem der genaue Tab und das Fenster versucht wurden und bevor die App einfach nach vorn geholt wird.

{ "url": "myeditor://focus?folder={cwd}&pane={tmux_pane}" }

Nutze sie als "jump" in einer Agent-Datei, oder für jede Sitzung in einer App als ~/Library/Application Support/Gnista/JumpRules/<bundle id>.json (zum Beispiel com.example.Editor.json). Die eigene Regel eines Agents geht vor.

Jeder Wert wird als Ganzes prozentkodiert (aus / wird %2F), er kann die Form der URL also nicht ändern. Eine Regel, deren Platzhalter nicht alle einen Wert haben, wird nicht benutzt. URLs, die Dateien öffnen oder Code ausführen (file:, javascript:, data: und Ähnliche), werden abgelehnt.

Einstellungen ▸ Agents ▸ Eigene Agents zeigt jeden Agent mit Datei oder der sich schon gemeldet hat, und wann Gnista zuletzt von ihm gehört hat.