A tiny friend in your Mac's notch and on your iPhone that keeps an eye on your AI coding agents: Claude Code, Codex, Cursor, Gemini CLI, Antigravity and more. Approve from the notch or your Lock Screen.
Swift ai-agentsanthropicantigravityclaudeclaude-codecodexcursordynamic-islandgemini-cliiosiphonlinuxmacosmacos-appmenubar-appnotchopen-sourceswiftswiftuiwindows
// Hook events from Claude Code and every other agent → island state.
// Port of HookServer.processEvent / processPermissionRequest from the macOS app.
// Difference from macOS: no terminal filter. On Windows the hook fires from any
// terminal (Windows Terminal, VS Code, PowerShell…) and all of them are handled.
// The relay has already mapped every agent's events and fields onto Claude
// Code's (hook/src/normalize.rs), so one handler serves them all.
import { Bridge, onEvent } from "../core/bridge";
import { buildFileDiff, fileName, makeDiffStep, toOneLine } from "../core/diff";
import { Sound } from "../core/sound";
import { State, type ApprovalInfo, type AskedQuestion } from "../core/state";
import { pillDefinition } from "../core/pills";
import { APPROVAL_AGENTS, agentColor, agentName, validateAgent } from "./agents";
import type { Island } from "./island";
import { parseClaudePlan, restorePlanUsage } from "../core/plan";
import { setClaudePlanUsage, storedClaudePlanUsage } from "../views/usage";
import { N_, t } from "../i18n/i18n";
const CLAUDE_ID = "integration_claude";
const CURSOR_ID = "agent_cursor";
/** Most requests waiting at once, the one on the card included (Mac ApprovalQueue.maxPending). */
const MAX_PENDING = 5;
/**
* Each request gives up on its own clock: 110 s after it arrived, whether it
* is on the card or still in line, it goes (the relay has stopped waiting by
* then). Checked by id, so it can never take down a request that came later.
*/
function armRequestTimeout(island: Island, requestId: string) {
window.setTimeout(() => {
if (State.pendingApproval?.requestId === requestId) dropPendingCard(island);
else dropQueued((x) => x.requestId === requestId);
}, 110_000);
}
/** Takes requests out of the line (their relay is released by the caller or gone). */
function dropQueued(match: (x: ApprovalInfo) => boolean): ApprovalInfo[] {
const gone = State.approvalQueue.filter(match);
if (gone.length === 0) return gone;
State.approvalQueue = State.approvalQueue.filter((x) => !match(x));
for (const pill of new Set(gone.map((x) => x.pillId))) {
if (!State.approvalQueue.some((x) => x.pillId === pill)) State.setPillBadge(pill, null);
}
State.notify();
return gone;
}
/** Takes the approval or question card down and gives the island back. */
export function dropPendingCard(island: Island): void {
if (!State.pendingApproval) return;
State.endApproval();
if (State.pendingApproval) {
// The next request in line takes the card, the way a new one comes up.
const view = State.pendingApproval.questions ? "question" : "approval";
Sound.play(view);
island.alert(view);
State.notify();
return;
}
island.dropPin();
if (State.view === "approval" || State.view === "question") {
island.setView(State.defaultView());
}
State.notify();
}
/** The return to idle that Stop arms, per pill, so the next turn can cancel it. */
const stopTimers = new Map<string, number>();
function cancelStopTimer(id: string): boolean {
const timer = stopTimers.get(id);
if (timer == null) return false;
window.clearTimeout(timer);
stopTimers.delete(id);
return true;
}
/** The pill that was focused before another pill's alert borrowed the front. */
let focusBeforeAlert: string | null = null;
let alertPill: string | null = null;
function showsAlert(pill: string, focused: boolean): boolean {
if (State.pendingApproval) return false;
if (focused) return true;
if (!State.settings.alertsFromAllPills) return false;
if (State.mode === "expanded" && !["overview", "finished", "error", "empty"].includes(State.view)) {
return false;
}
if (focusBeforeAlert == null) focusBeforeAlert = State.focusId;
alertPill = pill;
State.setFocus(pill);
return true;
}
export function restoreAlertFocus(): void {
if (!focusBeforeAlert) return;
const prev = focusBeforeAlert;
const borrowed = alertPill;
focusBeforeAlert = null;
alertPill = null;
if (
!State.pendingApproval &&
State.focusId === borrowed &&
borrowed !== prev &&
State.tasks.some((t) => t.id === prev)
) {
State.setFocus(prev);
}
}
/** Events after which a pending permission request of the same session is moot. */
const TURN_OVER = new Set(["Stop", "StopFailure", "UserPromptSubmit", "SessionEnd", "Interrupt"]);
interface HookPayload {
hook_event_name?: string;
request_id?: string;
session_id?: string;
cwd?: string;
message?: string;
/** UserPromptSubmit carries `prompt`; `message` belongs to Notification/Stop. */
prompt?: string;
/** Stop: the turn's final answer (Markdown) — Claude Code's, Hermes's, Codex's. */
last_assistant_message?: string;
tool_name?: string;
tool_input?: Record<string, unknown>;
/** Set by the relay when an edit was too big to forward whole (> 256 KB). */
coucou_diff_truncated?: boolean;
/** Optional agent tag: lowercase, digits and hyphens, ≤ 24 chars. */
coucou_agent?: string;
/** Hermes: where the session runs (telegram, discord…; "cli" in a terminal). */
platform?: string;
/** "cursor" when Claude Code runs in Cursor's terminal (set by the relay). */
term_editor?: string;
/** StatusLine (the plan usage relay): Claude Code's 5-hour and weekly limits. */
rate_limits?: unknown;
/** SubagentStart / SubagentStop: "Explore", "general-purpose"…; "" for Claude Code's own helpers. */
agent_type?: string;
}
const PROJECT_ALIASES: Record<string, string> = {
"notch-buddy": "Notch Buddy",
notchbuddy: "Notch Buddy",
notch_buddy: "Notch Buddy",
};
function aliasProjectName(name: string): string {
return PROJECT_ALIASES[name.toLowerCase()] ?? name;
}
function lastPathComponent(p: string): string {
const cleaned = p.replace(/[\\/]+$/, "");
const idx = Math.max(cleaned.lastIndexOf("\\"), cleaned.lastIndexOf("/"));
return idx >= 0 ? cleaned.slice(idx + 1) : cleaned;
}
/**
* localizedStep() — same labels as the macOS app, in English and shown in the
* interface language (src/i18n) when the step is recorded.
*/
const TOOL_LABELS: Record<string, string> = {
Bash: N_("Runs"),
Read: N_("Reads"),
Write: N_("Writes"),
Edit: N_("Edits"),
Glob: N_("Searches"),
Grep: N_("Searches"),
WebSearch: N_("Searches the web"),
WebFetch: N_("Fetches"),
TodoWrite: N_("Tasks"),
Task: N_("Agent"),
LS: N_("Lists"),
MultiEdit: N_("Edits"),
NotebookEdit: N_("Notebook"),
PowerShell: N_("Runs"),
// Antigravity's tools (#298).
run_command: N_("Runs"),
view_file: N_("Reads"),
write_to_file: N_("Writes"),
replace_file_content: N_("Edits"),
read_url_content: N_("Fetches"),
search_web: N_("Searches the web"),
ask_question: N_("Needs input"),
};
function stepLabel(tool: string, input: Record<string, unknown>): string {
const labelTool = tool === "ask_question" || tool.endsWith(":ask_question") ? "ask_question" : tool;
const label = TOOL_LABELS[labelTool] ? t(TOOL_LABELS[labelTool]) : tool;
const str = (k: string) => (typeof input[k] === "string" ? (input[k] as string) : null);
const cmd = str("command");
if (cmd) return `${label} · ${cmd.slice(0, 40)}`;
const path = str("path");
if (path) return `${label} · ${lastPathComponent(path)}`;
const file = str("file_path");
if (file) return `${label} · ${lastPathComponent(file)}`;
const query = str("query");
if (query) return `${label} · ${query.slice(0, 40)}`;
if (
(tool === "ask_question" || tool.endsWith(":ask_question")) &&
Array.isArray(input.questions) &&
input.questions.length > 0
) {
const firstQ = input.questions[0];
if (typeof firstQ === "object" && firstQ !== null && typeof (firstQ as Record<string, unknown>).question === "string") {
const q = ((firstQ as Record<string, unknown>).question as string).trim();
if (q) return `${label} · ${q.slice(0, 40)}`;
}
}
return label;
}
/**
* What the Allow button actually authorises. Approving "Write" tells you nothing
* — approving `Write · C:\…\.env` tells you everything, and the difference is
* the whole point of approving from the island rather than blind.
*
* Ordered by how specific the field is, so an unfamiliar tool still shows
* whatever identifying string it carries instead of falling back to its name.
*/
const APPROVAL_FIELDS = [
"command", // Bash, PowerShell
"file_path", // Write, Edit, MultiEdit, NotebookEdit
"path", // Read, LS
"url", // WebFetch
"query", // WebSearch
"pattern", // Glob, Grep
"prompt", // Task
] as const;
function approvalTarget(tool: string, input: Record<string, unknown>): string {
for (const field of APPROVAL_FIELDS) {
const value = input[field];
if (typeof value === "string" && value.trim()) {
return `${tool} · ${value.trim()}`;
}
}
return tool;
}
/**
* The questions of an AskUserQuestion call, if the island can show all of them
* as options to pick from. Anything it cannot is left to the terminal.
*/
function askedQuestions(tool: string, input: Record<string, unknown>): AskedQuestion[] | null {
if (tool !== "AskUserQuestion" || !Array.isArray(input.questions)) return null;
const out: AskedQuestion[] = [];
for (const raw of input.questions as Record<string, unknown>[]) {
const question = typeof raw?.question === "string" ? raw.question : "";
const options = (Array.isArray(raw?.options) ? (raw.options as Record<string, unknown>[]) : [])
.filter((o) => typeof o?.label === "string" && o.label)
.map((o) => ({
label: o.label as string,
description: typeof o.description === "string" ? o.description : "",
}));
// A question cut short by the relay would be answered under the wrong text.
if (!question || question.endsWith("…") || options.length < 2) return null;
out.push({ question, options, multiSelect: raw.multiSelect === true });
}
return out.length > 0 ? out : null;
}
/** The Claude Code session's pill, named after its project for the session. */
function upsert(id: string, projectName: string, cwd: string, sessionId: string) {
const t = State.upsertWorkspacePill(id, projectName, cwd);
if (t && sessionId) t.sessionId = sessionId;
}
/** The session is over: the pill goes back as it was, or away if it was only there for it. */
function clearSession(id: string) {
const t = State.tasks.find((x) => x.id === id);
if (!t) return;
if (!State.isKept(id)) {
State.removeTask(id);
return;
}
t.state = "idle";
t.steps = [];
t.stepIndex = 0;
delete t.stepSeq;
t.name = pillDefinition(id)?.name ?? t.name;
t.pillBadge = null;
t.sessionId = null;
t.finalLine = null;
}
/** The final message stays on the card until the next turn starts. */
function clearFinalLine(id: string) {
const t = State.tasks.find((x) => x.id === id);
if (t) t.finalLine = null;
}
/**
* PostToolUse of Edit / MultiEdit / Write → a diff stored for the pill and a
* ticker step with its +N −M counts. Nothing is kept for a pill that does not
* exist, so a stray event cannot grow memory. An edit the relay had to cut
* would give wrong counts: the PreToolUse step ("Edits · file") stands alone.
*/
function recordDiff(agentId: string, payload: HookPayload) {
if (payload.coucou_diff_truncated) return;
if (!State.tasks.some((t) => t.id === agentId)) return;
const diff = buildFileDiff(payload.tool_name ?? "", payload.tool_input ?? {});
if (!diff) return;
const id = State.appendSessionDiff(agentId, diff);
State.appendStep(agentId, makeDiffStep(fileName(diff.path), diff.added, diff.removed, id));
}
export function registerHookHandlers(island: Island) {
// The last plan numbers seen survive a restart, as on the Mac.
State.planUsage ??= restorePlanUsage(storedClaudePlanUsage());
void onEvent<HookPayload>("hook", (payload) => handleHook(island, payload));
// The relay stopped waiting without a decision and the terminal has taken
// over: a card still up for that request would be lying (#857).
void onEvent<string>("approval-expired", (requestId) => {
dropQueued((x) => x.requestId === requestId);
if (State.pendingApproval?.requestId !== requestId) return;
dropPendingCard(island);
});
}
function handleHook(island: Island, payload: HookPayload) {
// Account-wide numbers from the status line relay, not part of any session:
// keep the latest, nothing else (no reveal, no sound), paused or not.
if (payload.hook_event_name === "StatusLine") {
const usage = parseClaudePlan(payload.rate_limits);
if (usage) setClaudePlanUsage(usage);
return;
}
if (State.paused) {
// Silence here used to cost Claude Code nearly two minutes: the relay waited
// for a decision from an island that had already decided not to look. Say so,
// and the terminal takes the question immediately.
if (payload.request_id) void Bridge.approvalDecline(payload.request_id);
return;
}
const name = payload.hook_event_name ?? "";
const cwd = payload.cwd ?? "";
const raw = lastPathComponent(cwd);
const projectName = aliasProjectName(raw || "Session");
// Route to the right pill. Valid coucou_agent → dynamic "agent_<name>" pill.
// "claude" is reserved; absent or invalid → Claude Code's own pill: Cursor's
// when it runs in Cursor's terminal (Mac #120), VS Code's otherwise.
const validAgent = validateAgent(payload.coucou_agent);
const workspaceId = payload.term_editor === "cursor" ? CURSOR_ID : CLAUDE_ID;
const agentId = validAgent ? `agent_${validAgent}` : workspaceId;
const isExternalAgent = validAgent !== null;
const sessionId = payload.session_id ?? "";
/** Alerts force the island open; work events only reveal the compact island. */
const surface = (view: Parameters<Island["alert"]>[0], isAlert: boolean) => {
if (State.mode === "expanded") {
if (isAlert) island.setView(view);
} else if (isAlert) {
island.alert(view);
} else if (State.mode === "hidden") {
island.reveal();
}
};
/** Ensure the agent pill exists (no-op for Claude Code). */
const ensurePill = () => {
if (isExternalAgent) {
State.upsertExternalAgent(agentId, agentName(validAgent!), agentColor(validAgent!));
const t = State.tasks.find((x) => x.id === agentId);
if (t && cwd) t.sessionCwd = cwd;
if (t && sessionId) t.sessionId = sessionId;
} else {
upsert(agentId, projectName, cwd, sessionId);
}
};
/**
* Called where a handler is about to replace `finished` with a newer state:
* the timer Stop armed would otherwise put the pill back to idle over it. The
* badge that timer was going to clear goes now.
*/
const supersedeStop = () => {
if (cancelStopTimer(agentId)) State.setPillBadge(agentId, null);
};
// Requests of a turn that is over still in line are moot: released at once,
// before the card below goes, so none of them can take its place.
if (TURN_OVER.has(name)) {
const moot = dropQueued((x) => x.pillId === agentId && x.sessionId === (payload.session_id ?? ""));
for (const x of moot) if (x.requestId) void Bridge.approvalDecline(x.requestId);
}
// The turn that asked for a permission is over — answered in the terminal,
// interrupted, or a new prompt — so the card would be lying. It goes, and the
// relay is released without a decision. Same rule as the Mac.
const pending = State.pendingApproval;
if (
pending &&
TURN_OVER.has(name) &&
pending.pillId === agentId &&
pending.sessionId === (payload.session_id ?? "")
) {
if (pending.requestId) void Bridge.approvalDecline(pending.requestId);
dropPendingCard(island);
}
// Read after the card above is dropped: its pill may have handed the front
// back to the pill you were on.
const focused = State.focusId === agentId;
switch (name) {
case "SessionStart":
ensurePill();
clearFinalLine(agentId);
// Hermes through its gateway says where the session comes from.
if (validAgent === "hermes" && payload.platform && payload.platform !== "cli") {
State.appendStep(agentId, payload.platform.charAt(0).toUpperCase() + payload.platform.slice(1));
}
surface("overview", false);
Sound.play("work");
break;
case "UserPromptSubmit": {
ensurePill();
supersedeStop();
clearFinalLine(agentId);
State.updateTask(agentId, "thinking");
// The field is `prompt`; reading `message` meant this step was always blank.
const asked = payload.prompt ?? payload.message;
if (asked) State.appendStep(agentId, asked.slice(0, 60));
surface("overview", false);
break;
}
case "PreToolUse": {
ensurePill();
supersedeStop();
clearFinalLine(agentId);
const tool = payload.tool_name ?? "Tool";
const isQuestion = tool === "ask_question" || tool.endsWith(":ask_question");
if (isQuestion) {
State.updateTask(agentId, "question");
State.appendStep(agentId, stepLabel(tool, payload.tool_input ?? {}));
Sound.play("question");
surface("overview", true);
} else {
State.updateTask(agentId, "working");
State.appendStep(agentId, stepLabel(tool, payload.tool_input ?? {}));
surface("overview", false);
}
break;
}
case "PostToolUse":
supersedeStop();
// The question was answered in the terminal: the card would be lying.
if (
payload.tool_name === "AskUserQuestion" &&
State.pendingApproval?.questions &&
State.pendingApproval.sessionId === (payload.session_id ?? "")
) {
dropPendingCard(island);
}
State.updateTask(agentId, "working");
recordDiff(agentId, payload);
break;
case "PostToolUseFailure":
supersedeStop();
State.updateTask(agentId, "working");
State.appendStep(agentId, t("⚠ failed"));
break;
case "Notification": {
const message = payload.message ?? "";
const lower = message.toLowerCase();
if (lower.includes("rate limit") || lower.includes("limite d")) {
supersedeStop();
State.updateTask(agentId, "ratelimit");
Sound.play("rate");
} else if (message.endsWith("?")) {
supersedeStop();
State.updateTask(agentId, "question");
State.appendStep(agentId, message);
}
break;
}
case "Stop": {
State.updateTask(agentId, "finished");
// Claude Code puts the turn's answer in the Stop payload itself, so there is
// no transcript to read (the relay does not even forward its path). Other
// agents report their last words the same way (Hermes, Codex) or as
// `message`.
const finalText = toOneLine(payload.last_assistant_message ?? payload.message ?? "");
if (finalText) {
State.appendStep(agentId, finalText);
const t = State.tasks.find((x) => x.id === agentId);
if (t) t.finalLine = finalText;
}
Sound.play("finish");
// A card waiting for an answer is never covered by another alert.
if (showsAlert(agentId, focused)) surface("finished", true);
else State.setPillBadge(agentId, "finished");
cancelStopTimer(agentId);
stopTimers.set(
agentId,
window.setTimeout(() => {
stopTimers.delete(agentId);
// While the island is open the alert's card stays on its own pill, and the
// pill you had comes back when it closes (island.ts), as on the Mac. An agent
// pill about to go hands the front back now.
if (isExternalAgent || State.mode !== "expanded") restoreAlertFocus();
if (isExternalAgent) {
State.removeTask(agentId);
} else {
State.updateTask(agentId, "idle");
State.setPillBadge(agentId, null);
}
}, 5200),
);
break;
}
case "Interrupt":
// Codex: the user stopped the turn. Back to idle, nothing to celebrate.
supersedeStop();
State.updateTask(agentId, "idle");
State.setPillBadge(agentId, null);
break;
case "StopFailure":
supersedeStop();
State.updateTask(agentId, "error");
Sound.play("error");
if (showsAlert(agentId, focused)) surface("error", true);
else State.setPillBadge(agentId, "error");
break;
case "SessionEnd":
// Nothing left for the timer to do, and it must not outlive the session: a
// pill recreated within 5.2 s would be removed by it.
cancelStopTimer(agentId);
State.clearSessionDiffs(agentId);
if (isExternalAgent) {
State.removeTask(agentId);
} else {
State.updateTask(agentId, "idle");
clearSession(agentId);
}
break;
case "SubagentStart":
State.appendStep(agentId, t("+ subagent"));
break;
case "SubagentStop":
// Claude Code's own helpers (the prompt suggestion after each turn) end
// with a SubagentStop of empty agent_type and never start one. Shown, it
// pushed the turn's last edit off the ticker a few seconds after Stop.
if (payload.agent_type === "") break;
State.appendStep(agentId, t("• subagent done"));
break;
case "PermissionRequest": {
// Only Claude Code and the agents the relay can answer for (Codex, Copilot
// CLI, Muse Code — same as the Mac) get a card. Anyone else's request is
// declined at once, so the agent asks in its own terminal.
if (isExternalAgent && !APPROVAL_AGENTS.has(validAgent!)) {
if (payload.request_id) void Bridge.approvalDecline(payload.request_id);
break;
}
const requestId = payload.request_id ?? "";
// If this exact request is already showing or queued, ack again and leave it alone
if (State.pendingApproval?.requestId === requestId || State.approvalQueue.some((x) => x.requestId === requestId)) {
if (requestId) void Bridge.approvalAck(requestId);
break;
}
// Several requests can wait at once (several sessions or agents): they
// queue and the card shows the oldest. Past the cap, the newest goes back
// to its own terminal.
const totalPending = (State.pendingApproval ? 1 : 0) + State.approvalQueue.length;
if (totalPending >= MAX_PENDING) {
if (requestId) void Bridge.approvalDecline(requestId);
break;
}
ensurePill();
supersedeStop();
const tool = payload.tool_name ?? "Tool";
const input = payload.tool_input ?? {};
// Claude Code (including Claude Desktop) asking a question is not a permission to grant: the island
// shows the options and sends back the one that was picked.
const isClaude = !isExternalAgent || validAgent === "claude-desktop";
const questions = isClaude ? askedQuestions(tool, input) : null;
const view = questions ? "question" : "approval";
const info: ApprovalInfo = {
requestId,
sessionId,
pillId: agentId,
tool,
command: approvalTarget(tool, input),
...(questions ? { questions } : {}),
};
// Coucou answers within 108 s or not at all; after that the terminal has
// taken over and the card would be lying.
armRequestTimeout(island, requestId);
Sound.play(view);
if (State.pendingApproval) {
// Another card is up: this one waits in line, its pill badged, and the
// card on screen stays as it is.
State.approvalQueue.push(info);
State.setPillBadge(agentId, "approval");
if (requestId) void Bridge.approvalAck(requestId);
break;
}
// The card always comes up, even over another pill or an island that is
// already open: its pill comes to the front, and the one you were on
// comes back once you answer (Mac #117, #120).
State.beginApproval(info);
// The relay's short ack window closes in 800 ms; everything below this
// line is synchronous, so the card really is up by the time it lands.
if (requestId) void Bridge.approvalAck(requestId);
State.updateTask(agentId, view);
// Any agent's card (Claude Code, Codex, Copilot CLI, Muse Code) comes up
// the same way: beginApproval brought its pill to the front.
island.alert(view);
break;
}
default:
break;
}
State.notify();
}