Approval Modes

Updated June 6, 2026

When Claude Code needs to run a tool (editing a file, running a command, searching your codebase), it asks for permission. crystl intercepts these requests and presents them as floating glass panels on your screen.

The four modes

Manual

Every tool call requires your explicit approval. A floating approval panel appears with Allow and Deny buttons. This is the safest mode and gives you full control over what Claude does.

Best for: reviewing unfamiliar code changes, sensitive operations, learning what Claude does step by step.

Smart

crystl auto-approves safe, read-only operations (file reads, glob searches, grep) and prompts you for anything that modifies your system (file edits, bash commands, writes). This strikes a balance between speed and control.

Best for: day-to-day development where you trust Claude to read but want to review writes.

Auto

All tool calls are approved automatically. Claude works at full speed without interruption. Use this when you’re confident in the task and want maximum throughput.

Best for: well-defined tasks, trusted workflows, when you’re watching the output.

Pause

All approval requests are queued without being shown. Nothing is approved or denied until you switch to another mode. Useful when you want Claude to plan its work while you step away.

Best for: queuing work, stepping away from your desk, batching reviews.

Approval panels

Each approval panel is a floating glass panel that shows:

  • The tool name (Edit, Bash, Read, etc.)
  • The target (file path or command)
  • A preview of what will change
  • Allow and Deny buttons

Panels are non-activating. They appear on screen without stealing focus from your current window. You can click Allow or Deny and keep working.

Stop the whole session

Deny rejects just the one tool call — your agent keeps going and can try something else. To stop the entire session instead, hold Option while clicking Deny. A confirmation appears first (“stop the whole session?”) so an accidental Option press can’t kill a run. There’s no separate button for this — it’s a deliberate power-user shortcut.

Allow all

When two or more approval requests are queued, an Allow All bar appears so you can batch-approve them in one click.

Denial panels

When Smart or Auto mode denies a tool, an orange denial panel appears showing what was blocked. A Retry button lets you override the auto-deny without switching modes.

Per-project approval

You can override the global approval mode on a per-gem basis. Open the gem menu (click the ⋮ on the gem’s tab, or double-click its tile in the Crystal Rail) and choose approval to set the mode directly, or settings for the full panel where the Approval (Claude) dropdown sits at the top. Either way you get four options:

  • Default (Global): Use the global approval mode
  • Manual: Always prompt for this gem
  • Smart: Auto-approve reads, prompt for writes
  • Auto Approve: Approve everything automatically

The per-project setting is saved in .crystl/project.json and persists across sessions.

Priority chain

crystl resolves the active approval mode in this order:

  1. Session override: If you’ve changed the mode for an individual shard, that takes priority
  2. Per-project config: The Gem Settings dropdown
  3. Global mode: The default approval mode from the Crystal Rail flyout

When you set a per-project mode, the terminal prints a confirmation: Approval mode changed from X to Y.

Global default

The Crystal Rail’s approval flyout header now reads Default Approval (Claude) to clarify that it sets the fallback mode. The Pause All option remains at the bottom, separated by a divider.

From the CLI

Approvals are also reachable via the crystl CLI. This helps when you’re triaging from another terminal, scripting a workflow, or running an agent that needs to coordinate with whoever holds the approval seat.

crystl pending                       # list every pending request
crystl approve 3                     # approve request id 3
crystl deny 4                        # deny request id 4
crystl wait pending --timeout 60     # block until the next one appears, then exit
crystl events --type pending_changed # stream approval lifecycle as JSON lines

crystl wait pending is built on the bridge’s SSE stream: no polling, exits cleanly on Ctrl-C, returns exit 1 on timeout.

Switching modes

You can change the approval mode at any time from the shard’s settings or the Gem Settings panel. The change takes effect immediately for all pending and future requests in that gem.