IDEs & terminals
Guides

IDEs & terminals

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:

  1. Open the editor's integrated terminal (Ctrl+`).
  2. Run rayu.
  3. 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:

SituationWhat the command does
Terminal already reports modified EnterTells you nothing needs changing
Inside tmuxAppends a managed block to ~/.tmux.conf: extended-keys on, extended-keys-format csi-u, and a terminal-features line
WezTermSets config.enable_kitty_keyboard = true in your WezTerm config
Anywhere elseFalls 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:

tmux
# 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:

TerminalNotes
kitty, Ghostty, WezTerm, Alacritty, footNative kitty protocol: Shift+Enter works immediately
iTerm2 3.5+Native; enable nothing
WarpNative Shift+Enter
VS Code, Windows Terminal (recent)Works; older builds need /terminal-setup
Terminal.appNo kitty protocol; use the key map above
tmux, screenWorks, but the multiplexer must forward extended keys
Windows PowerShell 5.1 / conhostWorks; 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+V on 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+Space or /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:

bash
# 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/app

The 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-keys on the tmux side. /terminal-setup writes it.
  • Nested sessions are fine, but a rayu inside a rayu gets no hooks of its own: RAYU_HOOKS_DISABLED=1 is 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:

ThingStatus in v3
/ide command, IDE lockfile discoveryRemoved. No editor handshake
JetBrains pluginNot part of v3
--ide flagRemoved
Attaching the editor panel to a terminal sessionThe 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 →