dopairb

An interactive Ruby shell that answers every keystroke, evaluation, result and exception with loud terminal effects. It is built as an IRB extension. The design spec is spec.md (in Japanese).

A 72-second promo with sound and English/Japanese subtitles: plain irb, then dopa on, the setup, and "Happy dopa Ruby!". The scripts that record dopairb sessions like this one are in docs/recording.

dopairb(main):001> (1..100).sum                     COMBO 00  SCORE 33  [⣿⣿⣀⣀⣀⣀⣀⣀] x1.5
                    ⠂⠌⠟⠃        <- sparks, afterglow and HUD on every keystroke

        █████ ███ ████   ████ █████    █   █ ███ █████ █
        █      █  █   █ █       █      █   █  █    █   █     <- big moments: drop, impact, shockwave, fireworks
        ████   █  ████   ███    █      █████  █    █   █
✦ FIRST HIT! ✦  +252                                          <- optional one-line badge left behind
=> 5050                                                        <- IRB's normal result output, untouched

dopairb is not on rubygems.org yet. Install it from the repository:

$ git clone https://github.com/ko1/dopairb
$ cd dopairb
$ gem build dopairb.gemspec && gem install ./dopairb-*.gem

To try it without installing, run ruby exe/dopairb in the checkout.

$ dopairb                 # start it, at full blast with sound (IRB options are passed through)
$ dopairb --calm          # quieter: low intensity, no flash, shorter effects
$ dopairb --party         # max + full-screen flash + sound effects
$ dopairb --intensity=normal --no-sound   # the tamer pre-0.4.0 defaults
$ dopairb --no-flash      # suppress flashing, available from the very first start
$ DOPAIRB="intensity=low,flash=off" dopairb

To turn your regular irb into dopairb, add this to ~/.irbrc:

begin
  require "dopairb"   # adds the `dopa` command; `dopa on` starts the show
  Dopairb.enable      # ...or start with the show on (e.g. Dopairb.enable(sound: :off))
rescue LoadError
  # a Ruby without dopairb keeps plain irb
end

With only the require, irb stays plain until you type dopa on. The title (and the loading screen on a cold start) plays right before the first prompt, as with the dopairb command. Sessions opened by binding.irb get the effects too; Dopairb.enable(binding_irb: false) keeps them plain. Settings for a single run (dopairb options and $DOPAIRB) win over the ones given to Dopairb.enable in .irbrc.

Inside a session, the dopa command changes settings:

dopa                  show settings and session stats
dopa on / dopa off    switch the show on (back to the last level) or off
dopa off|low|normal|max
dopa calm / dopa party
dopa demo             play every effect once (does not change your score)
dopa loading          show the loading screen
dopa gallery          the bonus art you have collected (`dopa gallery starry_night` shows one)
dopa gallery tour     a full-screen slideshow of all 100; uncollected ones appear as silhouettes
dopa flash=off duration=0.5 ...

Effects come in four strengths: small (every key), medium (syntactic moments), large (evaluation finished) and huge (records and comebacks). When several fire at once, only the biggest plays. The smaller ones are folded into its subtitle rather than queued.

Error effects name the kind of error. They never make fun of the failure.

Between sessions dopairb keeps a small profile: lifetime XP (the sum of your scores), level, best score, best combo, a day streak and the bonus art you have collected. Levels need powers of two: LV 2 at 512 XP, LV 3 at 1,024, LV 4 at 2,048, and so on. Each level-up and each jackpot unveils a masterpiece full screen, and now and then (about 1 success in 50) one simply drops: ART DROP!. There are 100 public-domain works to collect, from the Lascaux horses and Hokusai's Great Wave through Vermeer, Turner and van Gogh to Klimt, Kandinsky and Mondrian, all painted procedurally in half blocks (no image files ship with the gem). New ones come first; dopa gallery lists yours.

The startup title shows your level and day streak, and the finale shows NEW BEST! and an XP bar.

The profile is ~/.local/state/dopairb/profile.json ($XDG_STATE_HOME is honored). Set DOPAIRB_PROFILE=path to use another file, or DOPAIRB_PROFILE=off to keep nothing; levels are then not shown. Non-interactive runs never touch it.

DOPAIRB_SEED=n makes the luck (critical hits, jackpots, particles) repeatable, which helps when recording a demo.

With sound=sfx, every effect has a sound: key clicks, NICE! chimes, a comet ping, a stamp thump, a count-up that ends in a boom, fanfares and explosions for the big moments, a buzz or crack for errors. All sounds are synthesized in Ruby at runtime and cached as WAV files in the temp directory. No audio files ship with the gem.

They are played by the first player found:

• paplay (PulseAudio, including WSLg on WSL2)
• afplay (macOS)
• aplay (ALSA)
• powershell.exe on WSL without WSLg

The finale's sound is one track synthesized on the same timeline as the animation (a tick and a rising note per stat row, a drum roll, a boom, a fanfare, fireworks) and stretched with duration. Sounds are rendered once and reused by later sessions. At startup, a Ractor renders the missing ones in parallel with the REPL, so typing is not slowed down (a thread is used where Ractor is unavailable). The startup sound is rendered first. On a start without cached sounds (the first run, or after an upgrade), a loading screen (a cat running along a pastel progress bar) is shown until it is ready. dopa loading shows it any time. Players run as separate processes, so the REPL never waits for them. PowerShell takes a few hundred milliseconds to start, so with it only the result effects make sound, not every keystroke. When no player is found, sfx falls back to the terminal bell on big moments. Sound plays on the machine that runs dopairb, so over ssh you will not hear it.

The gem also ships dopacc, which puts the show on top of Claude Code:

gem install dopairb
dopacc install        # adds hooks + a status line to ~/.claude/settings.json

Then restart Claude Code. From then on:

• Every successful tool call adds to the COMBO with a chime. At 10 and above it is FEVER (x2 score).
• At COMBO 8, 16, 32, ... a full-screen COMBO 16! banner with fireworks takes over the screen for two seconds.
• A tool call has a 1/64 chance of a JACKPOT!! (x16).
• A failed tool call breaks the combo with a crack.
• When Claude finishes a turn that used tools, a full-screen MISSION COMPLETE! shows the turn's tools, score, combo and best.
• The status line shows COMBO / SCORE / BEST (an existing statusLine is left alone).

dopacc off / calm / on   # nothing / sounds only / everything (inside Claude Code: ! dopacc off)
dopacc status
dopacc demo              # ! dopacc demo inside Claude Code shows a banner right away
dopacc uninstall

dopacc install --project writes to ./.claude/settings.local.json instead. DOPACC=off in the environment silences it too.

How it works: Claude Code owns the terminal and its hooks run without one. So a hook walks up the process tree to Claude Code's tty, draws the banner on it, and then has Claude Code repaint. With the fullscreen TUI ("tui": "fullscreen"), it draws over Claude Code's screen and makes it lay itself out again by narrowing the window by one column for a moment. With the classic TUI, it draws on the alternate screen and switches back. Progress is kept in ~/.local/state/dopairb/dopacc.json. Hooks never fail: whatever happens, they exit 0 silently (DOPACC_DEBUG=1 prints errors).

• IRB evaluates and prints as usual. => value, exception messages and backtraces come from IRB itself. Effects are drawn in a temporary area and cleared. Only your input, the program's output and the result (plus an optional one-line badge) stay in the scrollback.
• dopairb never calls your #inspect / #to_s for its effects. It classifies values only with Module#=== and bind_call on built-in methods.
• When your program writes to stdout or stderr during an evaluation, the waiting display and any effect get out of the way immediately. While a system / spawn / IO.popen child might write straight to the terminal, nothing is decorated.
• Pressing a key during an effect ends it at once, and the key goes to Reline as usual. Per-keystroke effects pause while you paste.
• Non-interactive runs (pipes, redirects), TERM=dumb and intensity=off emit no control sequences at all. NO_COLOR emits no color codes.
• On narrow terminals, big-font banners fall back to spaced-out one-line text, then to badges only. On terminals where East Asian Ambiguous characters are two columns wide, box-drawing and block characters are replaced with ASCII or braille.
• An exception inside an effect never reaches the REPL. Set DOPAIRB_DEBUG=path to log it.

dopairb extends IRB and has no evaluation engine of its own. All dependencies on IRB and Reline internals live in two files.

• lib/dopairb/reline_adapter.rb (Reline 0.5–0.7, tested with 0.6.3)
  • Public API: Reline.add_dialog_proc (three dialogs: HUD, spark trail, effect strip) and output_modifier_proc (glow on the input).
  • Internals:
    • LineEditor#input_key: before/after comparison of each key.
    • #handle_signal: Reline calls it every 10 ms while waiting for input, so it serves as the animation tick.
    • #render.
    • #render_finished: records how the submitted input looks on screen.
    • Core#readmultiline.
• lib/dopairb/irb_adapter.rb (IRB 1.14–1.x, tested with 1.18.0)
  • Public API: IRB::Command.register(:dopa) and IRB.conf[:AT_EXIT].
  • Internals: IRB::Context#evaluate (around each statement) and IRB::WorkSpace#filter_backtrace (hides dopairb's own frames).

The rest is terminal-independent logic:

• Game: COMBO / CHARGE / SCORE.
• Probe: safe classification of values and exceptions.
• InputFx: per-keystroke effects.
• Director and the scenes in scenes/.
• Canvas: a cell grid with a braille sub-pixel layer.
• Stage: borrows a few rows at the cursor, draws, and restores the input line exactly.

• The HUD is not pinned to the top of the screen. It sits at the right end of the prompt line while typing and disappears when the input is submitted.
• Output printed during evaluation (puts etc.) is not decorated. Its lines are only counted, to trigger OUTPUT RAIN.
• Scores live for the session only and are not saved.
• Effects use Unicode. Any glyph that is not one column wide is swapped for ASCII or braille at runtime.
• Start it with the dopairb command, or call Dopairb.enable in .irbrc.
• IRB sessions entered via binding.irb get the same Context hook (unless binding_irb=off; detected with IRB::Context#from_binding?). The result screen appears only when the outermost session ends.

These are rough numbers from a local machine, not a formal benchmark. Processing one key (LineEditor#update + render) takes about 3 ms in plain IRB and about 5.6 ms in dopairb. With keys typed 30 ms apart, both follow the input within 1 ms. While an effect is running, the screen is redrawn at up to 30 fps, about 1 ms per frame.

$ bundle exec rake test     # unit tests + every scene x width x color depth + PTY integration tests

The integration tests (test/test_integration.rb) start dopairb on a pseudo terminal. They rebuild the screen with a small VT100 model (test/support/vt.rb) and check the acceptance criteria of spec §10:

• results and error messages remain as plain text
• fast typing and pastes do not change the input
• Ctrl-C works
• narrow terminals work
• NO_COLOR emits no color codes
• non-interactive runs contain no control sequences
• intensity=off behaves as plain IRB

They require setsid.

• Output that does not come from a child process (a C extension writing to fd 1 directly, $stdout.reopen, …) cannot be detected and may mix with the waiting display during an evaluation.
• When a multi-line input grows at the bottom of the screen, the effect strip below the input disappears (the HUD and spark trail remain). The strip is also hidden while completion candidates are shown.
• When IRB shows a long result in a pager (less), the effect finishes before the pager starts.
• If the terminal is resized in the middle of an effect, the rest of that effect may be garbled. The next effect uses the new width.

MIT