Agents maison,
une ligne de JSON.

Dans un terminal, avec Gnista lancé :

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

Une session de « Ralph » apparaît, qui vous attend. Cliquez dessus et vous revoilà dans ce terminal. Ensuite :

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

L’utilitaire sort toujours avec 0 et n’attend jamais : il ne peut pas bloquer votre outil. Si ce que vous envoyez cloche, il le dit sur stderr et n’envoie rien.

gnista hook custom <name> [event]

<name> est le nom de votre agent : jusqu’à 32 lettres minuscules, chiffres, - et _, en commençant par une lettre ou un chiffre. Les noms des agents intégrés (claude, codex et les autres) sont pris. L’événement peut être donné ici plutôt que dans le JSON, pour les outils qui lancent une commande différente par événement.

Un objet JSON par appel, sur stdin :

Sans tenir compte de la casse ni des séparateurs : needs-you, NeedsYou et needs_you reviennent au même.

Une session au travail qui ne dit plus rien passe au repos après quelques minutes (Réglages ▸ Général ▸ Inactif après).

Facultatif. Placez-le dans  /Library/Application Support/Gnista/Agents/<name>.json. Chaque clé est facultative :

{
  "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"]
}

Un fichier de plus de 1 Mo, ou avec la moindre erreur (une clé inconnue, un chemin qui n’en est pas un, un événement que Gnista n’a pas), est ignoré en entier. Réglages ▸ Agents ▸ Agents personnalisés l’affiche avec la raison, et l’utilitaire le dit sur stderr. Le format simple ci-dessus fonctionne toujours en attendant.

Avec "version": 2, le fichier peut aussi dire à Gnista comment connecter votre agent, comme il connecte ceux qui sont intégrés : quels hooks mettre dans la configuration de l’agent, comment lire ce qu’ils envoient, si ses demandes d’autorisation peuvent recevoir une réponse depuis l’encoche, et où se trouve sa transcription, pour que sa ligne affiche votre prompt, sa réponse et le coût. Les clés de la version 1 gardent leur sens.

{
  "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"
}

Réglages ▸ Agents liste alors votre agent avec les autres : le connecter ajoute les hooks de Gnista au fichier que vous avez indiqué, et le déconnecter les retire. Gnista ne modifie que ses propres entrées, et sauvegarde le fichier d’abord. Les hooks appellent gnista hook custom <name>, avec l’événement.

Quand vous cliquez sur une session, Gnista vous emmène à son onglet ou à sa fenêtre de terminal. Pour les apps où il n’a aucun moyen d’entrer, une règle de saut lui donne une URL à ouvrir à la place : après avoir essayé l’onglet et la fenêtre exacts, et avant de simplement mettre l’app au premier plan.

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

Utilisez-la comme "jump" dans un fichier d’agent, ou pour toutes les sessions d’une app, dans  /Library/Application Support/Gnista/JumpRules/<bundle id>.json (par exemple com.example.Editor.json). La règle propre à un agent passe en premier.

Chaque valeur est encodée en entier (/ devient %2F) : elle ne peut pas changer la forme de l’URL. Une règle dont les marqueurs n’ont pas tous une valeur n’est pas utilisée. Les URL qui ouvrent des fichiers ou exécutent du code (file:, javascript:, data: et consorts) sont refusées.

Réglages ▸ Agents ▸ Agents personnalisés liste chaque agent qui a un fichier ou qui s’est déjà signalé, et quand Gnista a eu de ses nouvelles pour la dernière fois.