31. IDEs & terminals#
RayuCode v3 is a terminal program. It does not connect to a running editor, and
there is no /ide command in v3. What it does have is careful terminal support:
it negotiates the best keyboard protocol your terminal offers, and it can write
the config that fixes the one chord terminals cannot report on their own.
Editor-side work happens through the VS Code extension
or by running rayu inside the editor's integrated terminal, which is an ordinary
terminal as far as Rayu is concerned.
Running inside an editor's terminal#
This is the recommended editor setup, and it needs no integration:
- Open the editor's integrated terminal (
Ctrl+`). - Run
rayu. - Work with the panel open beside it.
Everything works, including image paste and the full key map, because the integrated terminal is a real terminal. Two caveats:
- Shift+Enter depends on the terminal, not on VS Code. Recent VS Code
terminals support the kitty keyboard protocol, so it works. If it submits
instead of inserting a newline, run
/terminal-setup(below). - Over Remote-SSH, the terminal runs on the remote host. Rayu sees a normal terminal there and behaves identically, but the fix for Shift+Enter has to be applied on the machine whose terminal you are typing into.
Shift+Enter and /terminal-setup#
A terminal only sends one byte for Enter, so Shift+Enter and Enter are indistinguishable unless the terminal implements the kitty keyboard protocol. Rayu requests it at startup, so on kitty, Ghostty, WezTerm, Alacritty, foot, iTerm2 3.5+, Warp, and recent VS Code and Windows Terminal, Shift+Enter works out of the box.
/terminal-setup handles the cases where it does not:
| Situation | What the command does |
|---|---|
| Terminal already reports modified Enter | Tells you nothing needs changing |
| Inside tmux | Appends a managed block to ~/.tmux.conf: extended-keys on, extended-keys-format csi-u, and a terminal-features line |
| WezTerm | Sets config. in your WezTerm config |
| Anywhere else | Falls back to Terminal.app guidance (the key map below) |
The tmux block is written with a marker and re-running is idempotent, so you cannot end up with three copies:
# rayu: let Shift+Enter reach the application instead of collapsing to Enter.
set -s extended-keys on
set -s extended-keys-format csi-u
set -as terminal-features 'xterm*:extkeys'Afterwards the command tells you how to activate the change: tmux source ~/.tmux.conf then restart Rayu, or restart WezTerm.
For Terminal.app on macOS, which has no CSI u support at all, the fix is a key
map: bind Shift+Return to the bytes 1b 5b 31 33 3b 32 75 (that is
ESC[13;2u). Terminal.app stores it in its own settings; the command prints the
exact codes.
Until then, \ followed by Enter inserts a newline everywhere.
Terminals tested for rendering#
Rayu draws with the alternate screen and true color, so any reasonably modern terminal works. These handle it best:
| Terminal | Notes |
|---|---|
| kitty, Ghostty, WezTerm, Alacritty, foot | Native kitty protocol: Shift+Enter works immediately |
| iTerm2 3.5+ | Native; enable nothing |
| Warp | Native Shift+Enter |
| VS Code, Windows Terminal (recent) | Works; older builds need /terminal-setup |
| Terminal.app | No kitty protocol; use the key map above |
| tmux, screen | Works, but the multiplexer must forward extended keys |
| Windows PowerShell 5.1 / conhost | Works; use Windows Terminal for better Unicode |
If the interface renders as escape codes, see Troubleshooting.
Images and clipboard#
- Paste an image with the usual
Ctrl+V(Cmd+Von macOS). Rayu takes the image from the clipboard and attaches it to the prompt, if the model can see images. - Drag a file into the terminal and most terminals paste its path. Rayu accepts image paths too, so that is a second route.
- Voice input is
Ctrl+Spaceor/voice, and needs a working microphone.
Fonts and Unicode#
The UI uses box drawing, block elements, and Nerd Font glyphs for icons. A font with good coverage avoids most visual glitches: JetBrains Mono, Fira Code, or Cascadia Code, with a Nerd Font variant if you want the icon glyphs.
If box characters appear as ? or misaligned, the font is missing the glyphs
rather than Rayu misdrawing them. On Windows, use Windows Terminal, not conhost.
Running Rayu over SSH#
Two options, and they differ in where the UI runs:
# UI remote, over plain SSH
ssh dev@host -t 'cd /srv/app && rayu'
# UI local, attached to the server on the SSH host
rayu --ssh dev@host -C /srv/appThe second form runs the TUI on your machine and talks to RayuCode on the remote host, so latency is local and the remote side does not have to render anything. Use it when the connection is slow or the remote terminal is minimal.
--ssh-binary names a specific remote executable, and --ssh-server-socket
targets an isolated daemon socket over there.
Multiplexers#
tmux and screen work. Two things to know:
- Shift+Enter needs
extended-keyson the tmux side./terminal-setupwrites it. - Nested sessions are fine, but a
rayuinside arayugets no hooks of its own:RAYU_HOOKS_DISABLED=1is set for nested invocations, which is the recursion guard.
rayu restart save snapshots the open Rayu windows and rayu restart restore
reopens them after a reboot, which is a nicer arrangement than rebuilding your
tmux layout by hand.
Not in v3#
Worth stating plainly, because older docs and habits assume them:
| Thing | Status in v3 |
|---|---|
/ide command, IDE lockfile discovery | Removed. No editor handshake |
| JetBrains plugin | Not part of v3 |
--ide flag | Removed |
| Attaching the editor panel to a terminal session | The extension runs its own engine; use the CLI, the extension, or Telegram |
To get editor-grade review of agent changes, use the
VS Code extension, which has its own diff viewer, or
run git diff in the terminal.
Next#
Next: Troubleshooting →