# Approval Modes

> Control how Crystl handles Claude Code permission requests.

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.

---
Source: https://crystl.dev/docs/approval-modes/