# View Modes: Terminal, Split, Chat

> Show any shard as a terminal, as a conversation beside the terminal, or as a conversation filling the window. One pill in the shard bar, Cmd + Y, and the terminal keeps running underneath.

A shard is a shell with a process in it and a conversation with an agent. crystl can show you either, or both. The window's **view mode** picks which, and it has three states, drawn as a three-segment pill in the right band of the [shard bar](/docs/gems-and-shards/):

- **terminal**: the terminal fills the shard area. The default.
- **split**: the conversation sits in a dock beside the terminal.
- **chat**: the conversation fills the shard area and the terminal's view steps aside.

All three labels stay visible and the active one is lit, so the pill reports the state you are in rather than the one click away.

The mode belongs to the **window**, not to a shard. Change it once and every shard you click shows itself that way, so switching shards never raises the question of which mode this one is in. The mode comes back after a restart.

## Switching

- Click a segment of the pill in the shard bar.
- Press `Cmd + Y`. From the terminal it opens whichever chat mode you were last in, and from either chat mode it goes back to the terminal. It never cycles all three; the three-way choice is the pill's job. The first time you ever press it, with nothing stored, you get split.
- Choose **toggle chat** in the **View** menu, which is the same `Cmd + Y`.
- The dock's **✕** means "back to the terminal", and sets the mode to terminal.

Because `Cmd + Y` returns to your *last* chat mode, the shortcut settles into whichever one you live in: fullscreen if you work in fullscreen, the dock if you work in the dock.

## The terminal never stops running

Chat mode unmounts the terminal's **view**. It does not stop the terminal.

The pty keeps running, the terminal engine keeps processing output, and the cell store keeps filling, for the whole time the conversation is on screen. So while you are in chat mode:

- [`crystl screen`](/docs/cli/#screen) returns the live grid, at the geometry of the window as it is now. Resizing the window during chat mode reaches the hidden terminal, so an agent reading your screen is never writing against a stale width.
- [`crystl watch`](/docs/cli/#watch) still fires on new output.
- Dialog detection and the shard's status still answer from the real grid.

Flipping back mounts a view onto state that never paused: scrollback intact, no replay, no reflow beyond an ordinary resize.

## Reading and replying

Both chat modes show the same surface, read from the same structured transcript that powers [`crystl history`](/docs/cli/#history) and the [history navigator](/docs/conversation-history/). New agent output appears as the turn runs, and the composer sends your reply into that shard.

Plain `Return` sends. `Shift + Return` adds a new line. See [keyboard shortcuts](/docs/keyboard-shortcuts/#typing-a-new-line) for the same behavior in crystl's other text boxes. With an empty composer, `Escape` interrupts the agent, exactly as it would in the terminal.

An open approval or agent question appears inline above the composer. Answering it there uses the same request as the [floating card](/docs/notifications/), so resolving it in either place clears the other.

The header's **simple / detailed** control decides how much you see: simple keeps the conversation and folds tool calls into markers, detailed puts every tool call inline.

In fullscreen chat the conversation takes the whole shard area and uses your **terminal's font size**, because it is standing where the terminal stood. The dock stays at its own fixed size, since terminal-sized text in a 420pt column would wrap into uselessness. An empty facet strip gives its space back to the conversation.

## Tool calls

Tool calls get their own rows. Click one to expand its full input and output, with a copy button for the complete result, then click again to collapse it.

On Prism you can also click a collapsed `… +N lines (click to expand)` row in the terminal and crystl opens the conversation with that exact tool call expanded. See [tool calls](/docs/tool-calls/) for the matching rules.

## The peek: one shard's terminal, without leaving chat mode

In chat mode, `Cmd + Shift + Y` shows this shard's terminal. The window stays in chat mode, the pill's highlight does not move, and the peek ends when you switch shards. Use it to check a dialog or compare some output without giving up the mode you were working in.

It is the lighter sibling of `Cmd + Y`: that one changes the window's mode and stays changed, while a peek borrows the terminal for a look and leaves the mode alone.

A peek is per-shard and temporary on purpose. There is no per-shard mode to keep track of.

## When the grid is the only honest answer

Some things cannot be drawn as a conversation, and crystl says so rather than showing you an empty one.

- **A shard with no agent yet**: chat opens, and says so — there is no agent, the composer is how you start one, and anything you send meanwhile runs in the shell, whose output is in the terminal. Summon an agent and the conversation fills in from there.
- **A TUI dialog**: the conversation shows a quiet banner reading *the terminal is showing a dialog*. In chat mode that banner's action is **show it**, which starts a peek. crystl offers the terminal; it never changes your surface on its own.
- **A shard in chat mode with a dialog on the grid** still gets its floating card. The grid that would have shown you the dialog is hidden, so the card is the only way you would hear about it.
- **An agent whose conversation crystl can't read** (aider, goose, anything with no transcript crystl can follow) will not pretend. Ask for chat and that shard shows you split instead, with a line naming the agent and, where crystl knows it, where its conversation is kept. The mode is your intent; a shard answers for itself.

## Chat mode over a split window

[Split view](/docs/split-view/) (`Cmd + D`) is a different thing from the pill's **split** segment. Split view divides a gem into side-by-side terminal panes. The pill's split puts the conversation beside the terminal.

Both can be on at once. In chat mode a split window shows **one** conversation, the selected shard's, and hides the pane borders and the empty pane's picker along with the terminals. The split is not undone: leave chat mode and the same panes come back, in the same places, with the same shards in them. Two conversations side by side is not available yet.

## What's unavailable in chat mode

The grid is hidden, so the things that act on it stand down: `Cmd + K`, scrollback search, and copying a detected table. The conversation has its own copy paths. Flip back to the terminal, or take a peek, and they return.

## Renderer independence

The conversation reads the transcript, not terminal pixels, so it works on both [Prism and xterm](/docs/terminal-renderers/) even though click-to-expand rows inside the terminal need Prism. That makes `Cmd + Y` the reliable way to the conversation whatever the terminal surface can recognize.

## See also

- [split view](/docs/split-view/): side-by-side terminal panes, the other meaning of split
- [tool calls](/docs/tool-calls/): what expands, and the click-to-expand matching rules
- [history navigator](/docs/conversation-history/): search every past turn and tool call
- [keyboard shortcuts](/docs/keyboard-shortcuts/): `Cmd + Y`, `Cmd + D`, and the rest

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