Echoes

A pure-Ruby AppKit-based macOS terminal emulator. Echoes aims to be a well-integrated host for Ruby tooling — embedding rubish (a Ruby shell) and rvim (a Ruby vim) as first-class panes, with native prompt rendering, structured completions, and a private OSC namespace that lets in-pane Ruby tools drive UI features (gradient backgrounds, proportional fonts) other terminals can't.

• macOS (uses AppKit via Fiddle; no Linux/Windows support)
• Ruby >= 3.2

gem install echoes
echoes install

echoes install drops thin Echoes.app and EchoesEmbed.app shortcuts into ~/Applications/ so the app shows up in Spotlight, Dock, and Cmd-Space. Each shortcut is a one-line wrapper that execs into the gem-bundled launcher; re-run echoes install after each gem update echoes to refresh the path. echoes uninstall removes them.

To run from a clone instead:

git clone https://github.com/amatsuda/echoes
cd echoes
bin/setup
open Echoes.app          # GUI (PTY-spawned shell per pane)
open EchoesEmbed.app     # GUI with rubish embedded per pane
bundle exec exe/echoes -t  # TTY mode

• Echoes.app — terminal mode. Spawns the user's $SHELL per pane via PTY, like any other terminal emulator.
• EchoesEmbed.app — same window/UI, but each pane runs rubish in-process via a per-pane helper subprocess. Line editing, prompt rendering, and tab completion happen natively in Echoes (no ANSI roundtrip); only command output flows over the pty.
• Edit File… (Cmd+Shift+E) — opens an rvim-backed editor pane. Insert mode, :w, :q, search, visual mode, undo — the full vim surface. The dialog opens at the active pane's pwd.

• Images — Kitty graphics protocol (PNG via f=100, raw RGB / RGBA via f=24 / f=32, zlib-compressed payloads with o=z, file-path transmission via t=f / t=t, sub-cell pixel offsets, placements with q= / a=p / a=d, z= for layering — negative z blits the image beneath cell text, the default z=0 and any positive value blit on top) and iTerm2 inline images (OSC 1337 File= with PNG / JPEG / TIFF / GIF). SVG is also rendered by both protocols — detected by content-sniffing the payload, rasterized at the cell footprint requested (c=/r= for Kitty, width=/height= for iTerm2). Path-only SVGs (paths, basic shapes, <g>, transforms) go through a native CoreGraphics fast path — synchronous, no XPC. SVGs containing <text>, <filter>, gradients, <use>, etc. fall through transparently to a WKWebView backend (slower first paint, but full CSS / SVG surface). JavaScript is disabled and external resources blocked on both paths. Animated GIFs play — frame iteration via the retained NSBitmapImageRep, with per-image timing driven off the existing 60 Hz timer and only the image's row range marked dirty per frame.
• Desktop notifications — OSC 9 (\e]9;message\a, iTerm2 style) and OSC 777 (\e]777;notify;title;message\a, VTE style) deliver to the macOS Notification Center.
• Programming-font ligatures — =>, !=, <=, ->, etc. shape through Core Text when the active font (Fira Code, JetBrains Mono, …) ships them.
• Synchronized output (DEC 2026) — full-frame updates from tmux, Neovim, and IDEs land atomically instead of tearing.
• Find — Cmd+F opens the search bar; while it's focused, Cmd+R toggles regex mode and Cmd+I toggles case-insensitive matching.
• Pane capture — a running program can snapshot its own pane to disk as raster PNG or vector PDF via \e]7772;capture (see below).

Echoes reads ~/.config/echoes/echoes.conf at startup. The file is plain Ruby instance_eval'd against Echoes.config; every setter below has the same name as its config attribute.

font_family    "JetBrains Mono"
font_size      14.0
rows           24
cols           80
shell          "/bin/zsh"
scrollback_limit  10_000
tab_position   :top                # or :bottom
window_title   "Echoes"
foreground     "#e0e0e0"
background     "#1a1a2e"
cursor_color   "#b58900"
selection_color "#586e75"

Two profiles ship built-in (Solarized Dark, Solarized Light), so the View → Profile submenu has alternatives without any config. Declare your own — or re-declare a built-in by the same name to override it. Switching at runtime through the menu repaints the palette, fg/bg, selection, and cursor without a restart.

profile "Tokyo Night" do
  foreground   "#c0caf5"
  background   "#1a1b26"
  cursor_color "#c0caf5"
  selection_color "#283457"
  color_palette %w[
    #15161e #f7768e #9ece6a #e0af68 #7aa2f7 #bb9af7 #7dcfff #a9b1d6
    #414868 #f7768e #9ece6a #e0af68 #7aa2f7 #bb9af7 #7dcfff #c0caf5
  ]
end

default_profile "Tokyo Night"

Override any menu shortcut by action symbol. Pass an empty string to disable a default shortcut entirely.

keybind "Cmd+Shift+T", :new_tab
keybind "Cmd+K",       :toggle_find
keybind "",            :toggle_pointer    # disable the default

Available actions (one per menu item): :new_window, :new_tab, :close_tab, :close_pane, :edit_file, :split_right, :split_down, :select_next_pane, :select_previous_pane, :show_next_tab, :show_previous_tab, :select_tab_1 … :select_tab_9 (jump-to-tab; :select_tab_9 is "last tab"), :increase_font_size, :decrease_font_size, :reset_font_size, :toggle_find, :find_next, :find_previous, :toggle_pointer, :toggle_copy_mode.

Modifier names are case-insensitive and accept the obvious aliases: Cmd/Command/Super, Ctrl/Control, Opt/Option/Alt, Shift.

All Echoes-specific escape sequences live under OSC code 7772. Other terminals ignore unknown OSC codes, so emitters degrade gracefully.

Background painting (pane-scoped):

\e]7772;bg-color;#rrggbb\a
\e]7772;bg-gradient;type=linear:angle=N:colors=#rrggbb,#rrggbb[,...]\a
\e]7772;bg-fill;color=#rrggbb:rect=row1,col1,row2,col2\a
\e]7772;bg-clear\a

bg-fill calls accumulate, so a presentation tool can build up a slide layout (header bar, sidebar, accent stripe) on top of a base bg-color or bg-gradient. bg-clear wipes both the base layer and all fills.

Multicell glyphs (OSC-66-shaped, with Echoes-only knobs):

\e]7772;multicell;<key=value:...>;<text>\a

Accepts the standard kitty s/w/n/d/v/h keys plus:

• f=Family Name — render the glyph(s) in a specific font. Proportional fonts (Helvetica, Noto Serif, …) are measured per-glyph at layout time so the cells reserved match the actual rendered width — Hello in Noto Serif at 2× lays out cleanly without overflow or gaps.
• flip=h|v|hv — mirror the rendered glyph(s) horizontally, vertically, or both. Handy for direction-having emojis (e.g. flipping 🐇 to face the other way).

h= (halign) is honored for non-fractional / proportional text: the whole string lands in an s × source_chars cell block with the renderer's center / right-align math applied.

These knobs are routed through OSC 7772 rather than OSC 66 so a future kitty-spec extension claiming the same param names can't collide with ours.

Pane snapshots, multi-display, child windows:

\e]7772;capture;<absolute-path.png|.pdf>\a
\e]7772;display-info\a
\e]7772;open-window;display=N:program=<base64-argv>:fullscreen=yes|no\a

• capture writes a snapshot of the active pane to disk. .png rasterizes via NSBitmapImageRep; anything else (default .pdf) saves vector — usually smaller and crisper because text and background gradients stay resolution-independent.
• display-info is a sync query: the host replies on the same pty with \e]7772;display-info;<json>\a, where <json> is an array of {index, w, h, primary, current} per NSScreen. A presentation tool uses current to pick "anywhere but here" for a second-screen slide window.
• open-window spawns a child program in a new Echoes window on the chosen display. program is the argv JSON-encoded then base64-wrapped (e.g. Base64.strict_encode64(JSON.dump(argv))). fullscreen=yes uses a borderless, above-menu-bar window covering the full screen frame; otherwise the visible frame with default chrome.

A small Ruby helper (Echoes::Client) lets in-pane Ruby tools emit these without hand-rolling escape sequences:

require 'echoes/client'

Echoes::Client.bg_gradient(from: '#1a1a2e', to: '#16213e', angle: 90)
Echoes::Client.bg_fill('#ff6b35', row1: 0, col1: 0, row2: 2, col2: 79)
Echoes::Client.styled_text("Title", scale: 3, family: "Helvetica Neue")
Echoes::Client.capture("/tmp/slide.pdf")
Echoes::Client.bg_clear

Echoes::Client.styled_text auto-routes: OSC 66 when only standard knobs are used (portable), OSC 7772 ;multicell when an Echoes-only knob like family: is set.

OSC 9 / OSC 777 notifications go through terminal-notifier when it's on $PATH, otherwise fall back to osascript's display notification primitive. Echoes-only knobs that would otherwise extend OSC 66 (font family, mirror flips) live on OSC 7772 ;multicell instead, so portable emitters can keep OSC 66 strictly kitty-spec compatible.

bin/setup
bundle exec rake test       # run all tests
bundle exec exe/echoes      # launch from the working tree
bin/console                 # irb with the gem loaded

rake app syncs CFBundleVersion in both bundles' Info.plist files with Echoes::VERSION (run after a version bump).

Bug reports and pull requests welcome at https://github.com/amatsuda/echoes.

MIT.