커스텀 에이전트,
JSON 한 줄이면.

Gnista를 켜 둔 채로, 터미널에서:

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

‘Ralph’ 세션이 나타나 응답을 기다려요. 클릭하면 이 터미널로 돌아와요. 이어서:

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

헬퍼는 항상 0으로 끝나고 기다리지 않아서, 도구를 붙잡아 둘 일이 없어요. 보낸 내용에 문제가 있으면 stderr에 알려 주고 아무것도 보내지 않아요.

gnista hook custom <name> [event]

<name>은 에이전트의 이름이에요. 영문 소문자, 숫자, -, _로 32자까지, 첫 글자는 영문자나 숫자예요. 기본 제공 에이전트의 이름(claude, codex 등)은 쓸 수 없어요. 이벤트는 JSON 대신 여기서 넘겨도 돼요. 이벤트마다 다른 명령을 실행하는 도구를 위한 거예요.

호출 한 번에 JSON 객체 하나를, stdin으로:

대소문자와 구분 기호는 따지지 않아요. needs-you, NeedsYou, needs_you는 모두 같아요.

작업 중이던 세션이 조용해지면 몇 분 뒤 유휴 상태가 돼요(설정 ▸ 일반 ▸ 유휴 전환).

선택 사항이에요. ~/Library/Application Support/Gnista/Agents/<name>.json에 두세요. 모든 키가 선택 사항이에요:

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

1MB가 넘거나 어디든 잘못된 곳이 있는 파일(모르는 키, 경로가 아닌 경로, Gnista에 없는 이벤트)은 통째로 무시돼요. 설정 ▸ 에이전트 ▸ 커스텀 에이전트에 이유와 함께 표시되고, 헬퍼도 stderr에 알려 줘요. 그동안에도 위의 기본 형식은 그대로 작동해요.

"version": 2로 하면 파일이 에이전트를 어떻게 연결할지도 Gnista에 알려 줄 수 있어요. 기본 제공 에이전트를 연결할 때처럼요. 에이전트 자신의 설정에 어떤 훅을 넣을지, 훅이 보내는 내용을 어떻게 읽을지, 권한 요청에 노치에서 답할 수 있는지, 트랜스크립트가 어디 있는지를 정하면 줄에 내 프롬프트와 에이전트의 답, 비용이 표시돼요. 버전 1의 키는 뜻이 그대로예요.

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

그러면 설정 ▸ 에이전트에 내 에이전트가 다른 에이전트와 함께 나와요. 거기서 연결하면 지정한 파일에 Gnista의 훅이 추가되고, 연결을 끊으면 제거돼요. Gnista는 자기 항목만 바꾸고, 먼저 파일을 백업해요. 훅은 이벤트와 함께 gnista hook custom <name>을 호출해요.

세션을 클릭하면 그 터미널 탭이나 윈도우로 이동해요. 들어갈 방법이 없는 앱이라면, 이동 규칙이 대신 열 URL을 알려 줘요. 정확한 탭과 윈도우를 먼저 시도한 다음, 앱을 앞으로 가져오기만 하기 전에 쓰여요.

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

에이전트 파일의 "jump"로 쓰거나, 한 앱의 모든 세션에 쓰려면 ~/Library/Application Support/Gnista/JumpRules/<bundle id>.json(예: com.example.Editor.json)에 두세요. 에이전트 자신의 규칙이 먼저예요.

모든 값은 통째로 퍼센트 인코딩돼서(/는 %2F가 돼요) URL의 구조를 바꿀 수 없어요. 플레이스홀더 중 하나라도 값이 없으면 그 규칙은 쓰이지 않아요. 파일을 열거나 코드를 실행하는 URL(file:, javascript:, data: 등)은 거부돼요.

설정 ▸ 에이전트 ▸ 커스텀 에이전트에는 파일이 있거나 상태를 알린 적 있는 에이전트가 모두 나오고, Gnista가 마지막으로 소식을 받은 때도 보여요.