Interactive session

When stdout is a TTY, crystal opens an alternate screen: transcript, optional overlay, optional pinned todos, optional progress row, status bar, and a multiline composer. Redirected output stays sequential.

Images

For an OpenAI Chat Completions, DeepSeek, Responses, or Anthropic model with imageInput: true, run /attach <workspace-image-path> or press Ctrl+V. audioInput and videoInput do not attach audio or video.

Platform	Clipboard reader	Formats
Windows	PowerShell	Raw PNG, then bitmap
macOS	osascript	PNG, JPEG, GIF
Linux	wl-paste or xclip	Advertised PNG, JPEG, GIF, and WebP

A missing reader is reported separately from a clipboard with no image. Ctrl+V is handled before a following Enter in the same key batch. The composer and transcript show [Image #N]. Pasted markers have a distinct color and are one editing unit. Typing the same text does not attach an image. Raw bytes stay out of rendered text. Each image may be up to 20 MiB. PNG, JPEG, GIF, and WebP are accepted.

A multimodal plugin tool may return Crystal ImageContent. It is sent on the next model round. When imageModel is set, Plan and Work include describe_image, which asks that vision model to describe a file. The question comes from image.system.md and image.user.md. A model that accepts images also gets view_image, which returns the file itself. Screenshot capture, device control, and coordinate protocols belong to external plugins, not Crystal Code.

Status bar

The status bar shows approval, thinking when the model supports it, Tier <token> and Speed <token> when set, the selected budget (Context 272K), model, workspace, context percent (CTX), IN / OUT, a Title Case total when there is room, tool count, and elapsed time. Named labels are Title Case. Short abbreviations are uppercase. Plan or Work is on the composer prompt, not repeated on the bar.

While a turn runs, a progress row sits above the bar: Awaiting Approval · 5s, Running Command · 2m18s, Thinking · 1m16s · ~1.2k Tokens, Retrying In 8s (Attempt 1), Compacting. The prefix is a braille spinner, separate from the status-bar bullet. Output is UTF-8, so Windows does not replace those frames with ?. The ~N Tokens estimate appears only when estimatedTokens is on. A queued-follow-up count appears while items wait.

When the session has todos, a pinned Todos bar sits above the progress row. It shows the first four items. /todos prints the full list. Session start and /cd show Loading Tools on that row while operator tool sets load.

Assistant text is rendered as markdown while it streams and after it commits. User, thinking, tool, result, and compaction-summary blocks are rounded panels. Tool names in the chrome are Title Case. Approval cards for edit and write show a short + / - preview.

Result detail

Success panels use three switches. verboseResults is the parent. verboseTools and verboseCommands apply only while that parent is on. None of them hides a failure, an approval card, a thinking panel, an ask overlay, or the Tool card. The Tool card is the call itself (Read, Grep, Edit, Bash, Apply Patch), drawn before the result.

Command	Effect
/verbose calls	Shows or hides Tool cards. On unless verboseCalls is false. A hidden call can still leave an Edited … line. crystal run does not read this
/verbose results	Turns the parent on or off, or toggles it when on and off are omitted. On unless verboseResults is false
/verbose tools, Ctrl+O	Toggles tool detail on an empty composer
/verbose commands, Ctrl+G	Toggles command detail
/verbose	Prints all of these switches

While verboseResults is off, every success result is omitted: read, search, skill, edit, write, and the bash tools. The other switches stay stored and do not draw a result until /verbose results on. Ctrl+G does not expand output in that state, because the panel is omitted, not collapsed. Cards already in this session follow the switch.

While the parent is on:

verboseTools	verboseCommands	Success results
On	On	Full text
Off	On	Read, search, and skill results are omitted. Edit, write, and command output stay
On	Off	Command output collapses to a hidden-line hint and the last line. Other results stay
Off	Off	Both of the off rows above

crystal run does not read verboseResults. Its plain log still shortens long command output on its own.

Composer keys

Key	Action
Enter	Submit when idle. Queue a follow-up while a turn is running
Empty Enter, follow-up queued	Interrupt the turn, or compaction if that is still running, and send the queue now
Empty Enter, queue empty	Does nothing
Ctrl+J, or \ then Enter	Insert a newline
Backspace	Delete one character
Ctrl+W, Alt/Option+Backspace	Delete a word. On Windows, Ctrl+Backspace
Tab	Toggle Plan/Work, or complete a / command and its argument
Shift+Tab	Toggle Plan/Work
? on an empty composer	Show shortcuts and commands
Up / Down	Move in the composer. At the first or last row, browse prompt history. Moves the slash picker while it is open. A recalled prompt that starts with / stays in history until you edit it
Escape	Clear the composer
Wheel, PageUp / PageDown, Ctrl+Up/Down	Scroll the transcript
Ctrl+C before any model text, reasoning, tool call, or retry, composer and queue empty	Cancel the turn and put that message back
Ctrl+C later in the turn	Cancel. The message stays
Ctrl+C at idle	Clear the composer
Ctrl+C twice on an empty composer	Exit

crystal run does not put a message back. A trusted image marker the session no longer holds stays in the transcript, and that Ctrl+C only cancels. A queued follow-up also keeps the message.

The alternate screen enables bracketed paste and mouse reporting (1000, SGR 1006), turns alternate scroll off, and repeats those modes while the session is open. On Windows, quick edit is off for that time, so the wheel reaches the transcript. The previous console mode returns when the session closes. The wheel never becomes Up/Down. While mouse reporting is on, hold Shift to select text (Option or Fn in some macOS terminals). Rows that arrive while you are scrolled back do not move the view. Pasted text drops control, invisible, and bidirectional formatting characters. The frame repaints on resize. An escape sequence that is not a paste wrap is not paste. Approval and question overlays use the same input loop, so scroll and resize still work.

Questions

A question prompt can hold one or more tabbed questions, described choices, single or multiple selection, and a custom answer. Custom input is on by default. One single-select answer submits immediately. Several questions, or multiple selection, use a Confirm tab.

Key	Action
Up/Down, J/K	Move
Enter	Select. While editing a custom answer, save it
Space	Toggle a multiple-choice option
Left/Right, Tab	Move between questions
Escape	Dismiss. While editing a custom answer, return to the choices without changing the answer

While a custom answer is edited, its text and cursor are inside the panel. If the panel is taller than the screen, the wheel, PageUp, PageDown, and Ctrl+Up/Down scroll the rows. The title and border stay. Moving the highlight or cursor brings that row back. A manual scroll stays until the highlight or cursor moves. Scrolling past either end, or using those keys when the panel already fits, scrolls the transcript.

Follow-up queue

The composer stays open while a turn runs. Enter with text enqueues a follow-up (FIFO). Queued items stay in a Queued panel. The queue is sent when the current tool batch finishes, or when the turn ends. Empty Enter while a follow-up is queued interrupts the turn, or compaction if that is still running. Interrupt does not drop queued text.

/quit, /clear, /resume, and /fork stop a busy turn before they run. /clear, /resume, and /fork stay in the queue and run in the order typed. Each of those three drops follow-up text still waiting. During compaction they are refused, with the same kind of message as /cd during a turn. Other commands that change the session, workspace, or model are refused for the same reason. /status, /help, /todos, and other commands that only report state or adjust the display run immediately. /quit still exits.

One turn

1. Snapshot the transcript and the current tool definitions.
2. Stream one chat request. Render deltas as they arrive.
3. Stop before tools when the model did not finish normally. Truncated output and a content filter keep the text and end the turn. Any other unusual finish reason fails the turn. These stops do not run tools and do not compact.
4. If the candidate has tool calls, run the batch through the executor. Approval runs first.
5. Append the exact tool results.
6. Repeat until there are no tool calls, a limit stops the turn, or you cancel. The host may compact before a model round when the estimate or the last round is over budget. If compaction cannot reduce further, the turn stops.
7. After a completed turn, consider compaction again. /compact summarizes earlier context now and prints the summary.