Custom agents,
one line of JSON.

In a terminal, with Gnista running:

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

A session from “Ralph” appears, asking for you. Click it and you’re back in this terminal. Then:

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

The helper always exits 0 and never waits, so it can’t hold your tool up. If something is wrong with what you sent, it says so on stderr and sends nothing.

gnista hook custom <name> [event]

<name> is your agent’s name: up to 32 lowercase letters, digits, - and _, starting with a letter or digit. Built-in agents’ names (claude, codex and the others) are taken. The event can be given here instead of in the JSON, for tools that run a different command for each event.

One JSON object per call, on stdin:

Matched without regard to case or separators: needs-you, NeedsYou and needs_you are the same.

A working session that goes quiet turns idle after a few minutes (Settings ▸ General ▸ Idle after).

Optional. Put it at ~/Library/Application Support/Gnista/Agents/<name>.json. Every key is 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"]
}

A file over 1 MB, or with anything wrong in it (an unknown key, a path that isn’t one, an event Gnista doesn’t have), is ignored as a whole. Settings ▸ Agents ▸ Custom agents lists it with the reason, and the helper says so on stderr. The plain format above still works meanwhile.

With "version": 2, the file can also tell Gnista how to connect your agent, as it connects the built-in ones: which hooks to put in the agent’s own config, how to read what they send, whether its permission requests can be answered from the notch, and where its transcript is, so its row shows your prompt, its reply and the cost. Version 1’s keys keep their meaning.

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

Settings ▸ Agents then lists your agent with the others: connecting it there adds Gnista’s hooks to the file you named, and disconnecting takes them out. Gnista changes only its own entries, and backs the file up first. The hooks call gnista hook custom <name>, with the event.

When you click a session, Gnista takes you to its terminal tab or window. For apps it has no way into, a jump rule gives it a URL to open instead, after the exact tab and window have been tried and before simply bringing the app forward.

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

Use it as "jump" in an agent file, or for every session in an app, as ~/Library/Application Support/Gnista/JumpRules/<bundle id>.json (for example com.example.Editor.json). An agent’s own rule comes first.

Every value is percent-encoded as a whole (/ becomes %2F), so it can’t change the URL’s shape. A rule whose placeholders don’t all have a value isn’t used. URLs that open files or run code (file:, javascript:, data: and the like) are refused.

Settings ▸ Agents ▸ Custom agents lists every agent with a file or that has reported, and when Gnista last heard from it.