See what your agent made, and who needs you

1. Enable scripting

   Settings → Window → Scripting (or launch with --listen-on unix:/tmp/rb.sock). rbterm then exports the control-channel environment into every pane it opens.

2. Teach Claude the command

   Add a short instruction to your global CLAUDE.md (or package it as a skill). That's it — any Claude Code session you start inside rbterm inherits the environment and knows where to show its work.

   Paste this into ~/.claude/CLAUDE.md:

   ## rbterm: show images in the terminal
   When you produce an image the user should see — a screenshot, a chart,
   a Playwright capture — and $RBTERM_LISTEN_ON is set, display it with:
   
       "${RBTERM_EXE:-rbterm}" @ display-image --path /absolute/path/to.png
   
   Use --clear to remove it. If $RBTERM_LISTEN_ON is unset you are not
   running inside rbterm — skip silently.

Environment inside an rbterm pane

RBTERM_LISTEN_ON

Address of the control socket. Its presence means “you are inside rbterm and scripting is on.”

RBTERM_EXE

Absolute path to the running rbterm binary — the app bundle is never on PATH, so use "$RBTERM_EXE" @ ….

RBTERM_PANE_ID

The pane's stable id. Stamped into every rbterm @ request automatically, so commands self-target. Also usable explicitly: -m id:$RBTERM_PANE_ID.

1. Zero-config: the bell

   In Claude Code, run /config and set preferredNotifChannel to terminal_bell. Claude rings when it needs you; the tab lights up with the yellow ! and you get a desktop notification if you're in another app. Bells cross SSH natively, so this also works for claude running on a remote host in an SSH tab.

2. Precise: hooks

   For exact state transitions, drive the status user-var from Claude Code hooks. Paste this into ~/.claude/settings.json — every Claude session started inside rbterm then badges its own pane:

   {
     "hooks": {
       "UserPromptSubmit": [{"hooks": [{"type": "command",
         "command": "\"${RBTERM_EXE:-rbterm}\" @ set-user-vars -m \"id:${RBTERM_PANE_ID:-0}\" status=working >/dev/null 2>&1 || true"}]}],
       "Notification": [{"hooks": [{"type": "command",
         "command": "\"${RBTERM_EXE:-rbterm}\" @ set-user-vars -m \"id:${RBTERM_PANE_ID:-0}\" status=waiting >/dev/null 2>&1 || true"}]}],
       "Stop": [{"hooks": [{"type": "command",
         "command": "\"${RBTERM_EXE:-rbterm}\" @ set-user-vars -m \"id:${RBTERM_PANE_ID:-0}\" status=done >/dev/null 2>&1 || true"}]}]
     }
   }

Status words

waiting · blocked · attention

Yellow ! — attention. Clears when you view the tab.

working · running · busy

Spinner — running. Persists until changed.

done · ok · success

Green dot — done. Clears when you view the tab.

failed · error · fail

Red dot — failed. Clears when you view the tab.

status= (empty)

Clears the override and returns the pane to its derived status.

Claude Code ! cmd

When Claude tells you to run something, it writes ! cmd. Double-click the !, the command or any argument and you get all of it.

Inline code

Code in the middle of a sentence, like git status --short in a Claude Code or Codex reply, selects as one piece (v0.3.94 and later).

Wrapped commands

Agents break a long command across lines themselves. rbterm selects every line and copies it back as one line, so pasting never sends a newline that runs half of it.

Everything else keeps rbterm’s usual smart word selection: plain text, separate lines of a code block, a log line that is all one colour, and file names in ls output. Triple-click still selects the whole row.

Then run it in a new tab

Right-click the selection and rbterm asks Run in a new tab?, showing exactly what will run. Run in new tab (or Enter) opens a tab in the same folder and runs it there; Copy copies it; Cancel (or Esc) does nothing. Nothing runs without that confirmation, and Claude’s ! prefix is dropped for you (v0.3.94 and later).

Spinner in the title

Spinner badge — Codex is working. Follows Codex live, so it stops the moment Codex does.

[ ! ] Action Required

Yellow ! — Codex is waiting on an approval or a question. Stays lit until you answer it.

Spinner stops, tab unseen

Green dot — Codex finished in a tab you weren’t looking at. Clears when you view the tab.

The title travels with the output, so this works for codex on a remote host in an SSH tab, and inside tmux with set-titles on. Scripts see the same states: rbterm @ ls reports them, and -m state:attention finds every Codex waiting on you.

Settings → Codex

1. Alternate screen

   Makes Codex draw inline instead of taking over the screen, so scrollback and Cmd+F search keep working through a whole session.

2. Notifications

   Codex doesn’t recognise rbterm yet, so out of the box its alerts are a bare bell. This switch makes them carry their text, which rbterm shows as a desktop notification.

3. Image skill

   Installs a skill that teaches Codex the display-image command from SEC 01, so Codex can pop its screenshots into its own pane. Codex’s sandbox blocks the rbterm socket by default, so it will ask your permission the first time.