thomasansems/heysummon

HeySummon -- Human in the Loop (Gemini CLI)

See GEMINI.md for Gemini CLI native instructions with @./ includes.

HeySummon has two distinct verbs. Pick the one that matches your intent:

• Use help() when: the agent is stuck, needs approval, or needs human judgment before continuing. The script blocks until the expert replies.
• Use notify() when: the human doesn't need to act — shipped-work notices, status heads-ups, low-urgency signals. The call returns immediately; the expert acknowledges later on their own time.

For setup and usage, run:

bash $SKILL_DIR/scripts/setup.sh

Prompts for your HeySummon base URL and API key, validates the key, and registers the expert.

Quick reference

# help — ask a specific expert (blocking)
bash $SKILL_DIR/scripts/ask.sh "Your question here" "" "ExpertName"

# help — approval (Approve/Deny buttons)
bash $SKILL_DIR/scripts/ask.sh "I want to proceed." "" "ExpertName" --requires-approval

Approval requests: To request a yes/no decision (Approve/Deny buttons instead of a free-text reply), pass --requires-approval explicitly. The response will be APPROVED or DENIED.

Notify (fire-and-forget)

Trigger phrase: notify <name> <message>.

SDK example (from @heysummon/consumer-sdk):

import { HeySummonClient } from "@heysummon/consumer-sdk";

const client = new HeySummonClient({ baseUrl, apiKey });

// Fire-and-forget heads-up — no response is polled for.
await client.notify({
  question: "Deployed v1.4.2 to production. No errors so far.",
  expertName: "Ops",
});

Pick notify when the human would otherwise find out later by checking a dashboard. Pick help when you can't move forward until they reply.