## Shortcut Scheme

The shortcut scheme follows a simple model: `Cmd` works at the gem (project tab) level, `Cmd + Ctrl` works at the shard (session) level, and `Cmd + D` / `Cmd + Opt` handle split panes.

### Gems (project tabs)

| Shortcut      | Action                                       |
|---------------|----------------------------------------------|
| `Cmd + T`    | New gem                                     |
| `Cmd + W`    | Close gem (or the focused pane when split)  |
| `Cmd + 1-9`  | Jump to gem by position                      |
| `Cmd + Shift + ]` | Next gem                                 |
| `Cmd + Shift + [` | Previous gem                             |

### Shards (sessions within a gem)

| Shortcut              | Action                                         |
|-----------------------|------------------------------------------------|
| `Cmd + Ctrl + T`     | New shard                                     |
| `Cmd + Ctrl + W`     | Close shard                                   |
| `Cmd + Shift + T`    | Resurrect the most recently closed shard (undo-close) |
| `Cmd + Ctrl + 1-9`   | Jump to shard by position                     |
| `Cmd + Ctrl + ]`     | Next shard                                    |
| `Cmd + Ctrl + [`     | Previous shard                                |

### Split panes

| Shortcut                   | Action                     |
|----------------------------|----------------------------|
| `Cmd + D`                  | Split / unsplit toggle    |
| `Cmd + Opt + Left`        | Move focus to the left pane|
| `Cmd + Opt + Right`       | Move focus to the right pane|

`Cmd + D` changed in v2.75.0. In older versions it made a new shard, now it toggles a split pane. To make a new shard, use `Cmd + Ctrl + T`.

### Right sidebar

| Shortcut     | Action                                         |
|--------------|------------------------------------------------|
| `Cmd + ]`    | Next sidebar view (workbench, files, markdown, sequences when enabled) |
| `Cmd + [`    | Previous sidebar view                        |

A first press opens the sidebar if it’s closed. The arrow buttons beside the sidebar’s title do the same thing with the mouse, and their tooltips show these keys. The same unsaved-edit guard applies as the arrows, so an unsaved markdown edit is never discarded by a key press.

### Terminal

| Shortcut                 | Action                                         |
|--------------------------|------------------------------------------------|
| `Cmd + K`                | Clear screen and scrollback (keeps the shell prompt) |
| `Cmd + F`                | Find in scrollback                            |
| `Cmd + +`                | Increase font size                            |
| `Cmd + -`                | Decrease font size                            |
| `Cmd + 0`                | Reset font size                              |
| `Cmd + Ctrl + F`        | Toggle full screen                            |
| `Cmd + Y`                | Toggle the conversation (split or composer) for the focused shard |
| `Cmd + Shift + Y`       | [Peek](/content/docs/view-modes/index.html) this shard’s terminal without leaving composer mode, and again to go back |
| `Cmd + C`                | Copy selection                                |
| `Cmd + V`                | Paste                                         |
| Click                     | Open a file path or URL under the pointer     |
| `Cmd + click`            | Open it while a full-screen app has the mouse |

`Cmd + Y` flips the window between the terminal and the conversation, read from the transcript rather than the terminal renderer. You can read and drive the conversation without the TUI in the way. It returns to whichever [view mode](/content/docs/view-modes/index.html) you were last in, split or composer, and the pill in the shard bar picks between all three. Tool calls appear as their own rows there: click one to expand its full output, with a copy button. You can also click a collapsed `… +N lines (click to expand)` row straight in the terminal.

A single click opens the file path or URL under the pointer. When a full-screen app has the mouse, a click goes to that app, so use `Cmd + click` instead. The terminal underlines a link only when a click on it opens something, so a path to a file that is not there stays plain. A bare domain like `crystl.dev` shows as a link too, and a click asks first: visit `https://crystl.dev`, copy it with `https://`, or copy it as written. On a remote shard you can also open it as a file.

`Cmd + F` opens a find bar over the terminal. Type to search, `Enter` / `Shift + Enter` jump to the next / previous match, a count shows how many matches were found, and `Esc` closes the bar.

`Cmd + Shift + F` opens **global history search**: a floating palette that searches everything your agents ever said and every command that ran, across all gems and shards, open or closed. Arrow keys move through results, `Enter` jumps to an open shard or shows the surrounding conversation for closed history, and `Esc` (or the close button) dismisses it.

Scope and kind filters narrow to the current gem, conversations, or commands.

`Cmd + K` and `Cmd + F` are claimed by crystl at the app level (the same way iTerm and Warp claim them), so they won’t reach the program running in the terminal.

### Typing a new line

**`Shift + Return` inserts a new line.** Plain `Return` sends. Use it whenever you want a multi-line message and don’t want to fire it off halfway through writing.

It works where you’ll want it most: typing a prompt to Claude Code in the terminal. No `/terminal-setup` step, no config. crystl passes the key through and Claude Code picks it up. Other agents handle multi-line input their own way, so check their docs if `Shift + Return` doesn’t behave there.

The same key works in crystl’s own text boxes, though plain `Return` varies by field:

| Where                                       | `Return`               | `Shift + Return`        |
|---------------------------------------------|------------------------|--------------------------|
| Terminal prompt (Claude Code)              | Sends the message      | New line                 |
| Message box (split, composer, quest chat, side quests) | Sends the message      | New line                 |
| Workbench task **description**              | New line               | New line                 |
| Workbench task **title**                    | Commits the rename     | Commits the rename     |

The Workbench description is the odd one out: it’s a multi-line note, so plain `Return` already gives you a new line. Each line round-trips as its own detail line in `WORKBENCH.md`. `Esc` hands focus back to the terminal.

### Facet inserts

| Shortcut               | Action                                         |
|------------------------|------------------------------------------------|
| `Cmd + Opt + 1`       | Fire the facet insert bound to bar slot 1 into the active shard |
| `Cmd + Opt + 2`       | Fire the facet insert bound to bar slot 2  |
| `Cmd + Opt + 3`       | Fire the facet insert bound to bar slot 3  |

### Approval management

| Shortcut               | Action                                         |
|------------------------|------------------------------------------------|
| `Cmd + Return`         | Allow the focused project’s pending approvals  |
| `Cmd + Esc`            | Deny the focused project’s pending approvals    |

The approval chords act on the **focused project**: one press answers every approval queued for the gem in front of you. A queued approval in a sibling project is left alone. When two or more requests are pending, an **allow all** bar also floats above the cards; clicking it approves the whole queue.

**Plain `Return` in the terminal does not approve anything.** It used to, and that is gone. `Return` sends your message, nothing more. To answer an approval, use `Cmd + Return` / `Cmd + Esc`, click **Allow** or **Deny** on the panel, or answer the agent’s own menu in the terminal.

### App

| Shortcut     | Action                                         |
|--------------|------------------------------------------------|
| `Cmd + ,`    | Open settings                                 |
| `Cmd + Q`    | Quit crystl                                  |
| Hold `Option` at launch | Fresh start: open with no restored gems |

`esc`

`↑`  `↓` navigate
`↵` open
`esc` close