Approval Modes

Updated April 3, 2026

When Claude Code needs to run a tool — editing a file, executing 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.

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. Click a selected gem tile in the Crystal Rail to open the Gem Settings panel. At the top is the Approval (Claude) dropdown with 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.

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.