Notifications

crystl uses floating glass notification panels to keep you informed without interrupting your flow. Notifications appear as translucent panels near your workspace and dismiss automatically or on click.

Watching a shard silences its panels. If crystl is focused and the shard is on screen, you’re already reading its terminal, so crystl doesn’t float a copy over it. See Panels you’re already watching for the exact rule.

Approval cards

When Claude or another agent needs permission to run a tool, an approval card appears with:

• The tool name and working directory
• Allow and Deny buttons
• A session-colored glow so you know which shard is asking
• A shimmer animation while waiting for your response

When two or more requests are queued, an Allow All bar appears to approve everything at once.

Answering from the keyboard

You don’t need to use your mouse. These shortcuts work on the approval card for the project in front of you:

Shortcut	Action
Cmd + Return	Allow the focused project’s pending approvals
Cmd + Esc	Deny them

The chords are scoped to the focused project: one press answers every approval queued for the gem in front of you, and a pending approval sitting in another gem can’t be answered by accident. Bring that gem forward first.

Plain Return in the terminal no longer approves anything. In older versions it did. Now Return only sends what you typed, so a stray keypress while an approval is waiting can’t allow a tool call. Answer with the chords above, click Allow or Deny on the panel, or use the agent’s own menu in the terminal. See the keyboard reference for the full list.

Question cards

When Claude asks multiple-choice questions via AskUserQuestion, a question card appears. Each panel shows the project icon, project name, and shard name at the top so you know which session is asking.

• Multi-question flows show prev/next dot navigation within a single panel. Answers are preserved when you navigate between questions
• Type an answer or enter a number to select an option, then click Next or Submit
• Skip sends the question to the terminal for manual answering
• Configure the alert sound in settings, agents > defaults, under NEEDS YOU · QUESTIONS

Denial panels

When a tool is denied under auto-approval in gem, an orange denial panel appears showing the denied tool name and a summary of its input. This lets you see what was blocked without digging through terminal output.

• Retry re-attempts the denied tool
• Dismiss closes the panel
• Configure the alert sound in settings, agents > defaults, under NEEDS YOU · DENIALS

Activity notifications

crystl can notify you when an agent finishes a turn, when a turn fails, when a subagent finishes, and when a tool call finishes. About a minute after a turn ends, Claude Code also sends a “waiting for your input” reminder. crystl shows it only when it has no other card up for that turn, so you don’t get the same news twice.

Choosing what reaches you

Settings, agents > defaults, NOTIFICATIONS has one master switch and five groups. Each switch covers the cards on your Mac and the pushes to your phone. Your agents’ safety warnings, such as “approval supervision ended”, answer to none of the five groups: a warning that a tool ran with nobody asked shows even with needs you off. Only the master switch hides them.

Switch	Covers	Default
notifications	Everything below, on your Mac and your phone	on
needs you	Approvals, questions and denials	on
agent finished	A turn ended or failed, a subagent finished, and the idle reminder. With it off, crystl still notices a turn that failed because the agent is out of quota or signed out, and shows that shard as blocked	on
tool activity	Every tool call that finishes. Noisy	off
messages to you	crystl card, quest mentions, sequence and schedule results, and crystl’s own cards, such as “process finished”	on
other terminals	Agents running outside crystl, approvals included	off

With needs you off, your agent asks in its own terminal. crystl hands each approval and question back to the agent, so you answer it at the prompt as you would without crystl, and a denial gets no retry. Nothing else tells you the agent is waiting, so check its terminal. Nothing waits on a card that never appears. goose is the exception: in auto mode it has no prompt of its own, so its approval cards stay on even with the switch off.

Agents can read these switches with crystl settings. They can’t change notifications or needs you themselves: those decide whether you hear from an agent at all, so only you can change them. When an agent asks to, crystl shows you a card that says which shard asked and what it wants. Click turn off (or turn on) to apply it, open settings to go to the switch, or dismiss to leave it as it is. The change is applied only on your Mac. On your phone the card can be dismissed but not applied.

The sounds follow the same groups: NEEDS YOU · APPROVALS AND SAFETY WARNINGS, NEEDS YOU · QUESTIONS, NEEDS YOU · DENIALS, and one for AGENT FINISHED, TOOL ACTIVITY, MESSAGES.

Agent cards

Any CLI agent can raise its own floating card with crystl card "…" — the attention-grabber for a host with no notification-hook integration, so it works for agents like Codex or Antigravity CLI too, not only Claude Code. The card names the gem and shard that raised it and lands in the phone’s notification list as well as the desktop.

An agent can attach a one-click button to the card instead of just describing what it found. Pressing the button runs the given command in that same shard, so a diagnosis becomes something you can act on straight from the notification, with no need to switch to the terminal first. The button stays on screen until you press it or dismiss the card — it doesn’t fold away on a timer. See the card command reference for the full flag list.

Panels you’re already watching

crystl withholds a panel when it would duplicate something already in front of you. If you’re looking at the shard that raised it, the terminal is the notification, and a floating card over the top is noise.

The rule. A panel is withheld only when both of these are true:

1. The crystl window is focused (it’s the frontmost, active window), and
2. The source shard is on screen: it’s the selected shard in the front gem, or, in a split view, the shard in either pane.

Miss either condition and the panel appears exactly as before. crystl in the background, a different gem in front, a different shard selected, the shard scrolled off in a side pane you closed. Every one of those is the case notifications exist for, and every one of them still fires.

What each panel type does

Panel	Withheld while you watch the shard
Activity notifications	Yes, all types: task complete, agent finished, session ended, quest mentions, scheduled agents
Question cards	Yes, but only when the same question is already up in the terminal
Approval cards	Yes, but only when the agent’s own approval menu is already up in the terminal
Denial panels	No, denials always show

Questions and approvals have an extra guard on purpose: they need an answer, so crystl withholds the panel only after confirming the terminal is showing the same prompt. That prompt is the second place you can answer. If a question or approval arrives with no in-terminal prompt to answer it, leaving the panel as the only way to respond, the panel appears no matter what you’re watching.

Your terminal is untouched

Suppression only affects the floating glass panels. Nothing about the agent’s session changes:

• Everything the agent prints still prints, in full, in the terminal
• In-terminal approval menus and question prompts still appear, and answering there works normally
• Nothing is dropped, queued, or deferred; a withheld card is simply not drawn

A withheld activity notification also doesn’t play its sound, since the event it would announce is on your screen already.

When a withheld panel comes back

Questions and approvals are withheld for as long as you’re watching, not discarded. Switch to another shard, switch gems, click away to another app, or let the in-terminal prompt clear while the request is still unanswered, and the panel appears. You never lose a request by looking at it.

Why it works this way

Without this, working inside a shard meant reading every event twice: once as terminal output, once as a card floating over that same output a moment later. Panels are for the sessions you aren’t watching: the parallel agents, the background gem, the shard behind the one you’re in. Narrowing them to that case is what makes a screenful of agents quiet enough to run.

Subagent identification

When Claude dispatches subagents (parallel child agents that work on independent tasks), crystl gives each one a stable, human-friendly name so you can tell them apart on both approval cards and notifications. Each subagent shows:

• A dwarf name drawn from Tolkien’s legendarium: thorin, balin, dwalin, glóin, gimli, durin, and dozens more (lowercase, matching the crystal shard names)
• A pickaxe glyph (⛏) marking it as a subagent rather than the main session
• A “subagent · <type>” line showing the subagent’s role

Names are deterministic: the same subagent keeps the same dwarf name across app launches. This makes parallel subagent activity easy to follow. When three agents request approvals at once, you can see that thorin is editing files while glóin runs tests, instead of an anonymous pile of identical panels.

Behavior

• Notifications float above other windows as translucent glass panels
• Approval cards stay visible until you respond
• Question cards stay visible until you submit or skip
• Denial panels stay visible until you retry or dismiss
• Activity notifications can be dismissed with a click or cleared all at once
• A shard’s status notifications replace each other. When a shard asks a new question, the notification for its old one goes away on the desktop, in the bell, and on your phone, because only the newest question can be answered. Messages written for you (cards, schedule results, worker reports) stay until you dismiss them
• Panels for the shard you’re currently watching are withheld, see Panels you’re already watching

Disabling notifications

Turn notifications off in settings, agents > defaults, under NOTIFICATIONS. No cards appear on your Mac and nothing is pushed to your phone. Approvals and questions go back to your agent’s own terminal prompt, so you answer them there. goose keeps its approval cards, since it has no prompt of its own. Off means off for everything else, your agents’ safety warnings included.