Lumen

Shell integration

How your terminal learns where each prompt, command and output begins, and what it can do once it knows.

Updated

Shell integration is a small script that runs in your shell and tells the terminal where each prompt starts, where the command you typed starts, where its output starts and how it exited. A terminal on its own only sees a stream of characters. With those marks it can let you jump from command to command, copy one command's output, flag failures and notify you when a long job finishes.

Most modern terminals support it, and most of them load it for you. This page explains how the marks work (OSC 133), what each terminal does with them, and the details of Lumen's version.

How terminal shell integration works

A terminal emulator draws whatever bytes a program writes. It has no idea that $ ls is a prompt and a command, and that the next forty lines are output. Shell integration fills the gap with escape sequences: invisible control codes the shell prints around its prompt.

The script hooks into the shell's prompt machinery (PROMPT_COMMAND and PS1 in bash, precmd and preexec in zsh, events in fish). Before drawing the prompt, after you press Enter, and when a command exits, it prints a mark. The terminal records each mark against a line in the scrollback.

A second common sequence, OSC 7, reports the shell's current folder, so new tabs and splits can open in the same place.

OSC 133 prompt marks

OSC 133 comes from FinalTerm, an experimental terminal, and has become the shared format. "OSC" is Operating System Command, an escape sequence that starts with ESC ]. The four marks are:

SequenceMeaning
OSC 133 ; APrompt starts
OSC 133 ; BPrompt ends; the command you type starts
OSC 133 ; CCommand submitted; output starts
OSC 133 ; D ; 1Command finished, with its exit status (here 1)

In a shell you could print one by hand with printf '\e]133;A\a'. That's the whole trick, and also the weakness: any program can print the same bytes. cat a file containing them, or curl a hostile page, and the terminal will believe a prompt started there. Terminals that take marks at face value can show fake prompts, fake exit codes, or misplace "copy last output". VS Code adds a nonce to its command-line sequence for this reason, and Lumen goes further (below).

What terminals do with shell integration

TerminalLoaded automaticallyMain features
iTerm2No; install from the iTerm2 menuMarks, jump between prompts, select output, alert when a command finishes, recent folders, command history
kittyYes: bash, zsh, fishJump to prompts, last output in a pager, click to move the cursor, new windows in the same folder
WezTermSome packages install it; otherwise source wezterm.shScroll to prompt, select a command's output as a semantic zone, current folder
GhosttyYes: bash, zsh, fish, elvish, nushellJump to prompts, triple-click output, no close confirmation at a prompt, new splits in the same folder, SSH helpers
VS CodeYes: bash, zsh, fish, pwshSuccess/failure decorations, command navigation, sticky scroll; uses its own OSC 633 plus OSC 133
LumenYes: bash, zsh, fishSee below

A few notes. iTerm2 pioneered most of these features on macOS and its integration also reports user and host, which drives automatic profile switching. kitty's defaults are Ctrl+Shift+Z and Ctrl+Shift+X to move between prompts and Ctrl+Shift+G to open the last output in a pager. Ghostty doesn't inject into the old /bin/bash that macOS ships, so source the script by hand or install a newer bash. Fish 4.0 and later prints prompt marks itself.

Shell integration in Lumen

Lumen loads its scripts automatically for bash, zsh and fish. There's nothing to install and nothing to add to your dotfiles. Once a pane has run a command, you get:

  • Jump between commands: Ctrl+Shift+Up and Ctrl+Shift+Down (Cmd+Shift+Up/Down on macOS) move the view prompt by prompt.
  • Copy the last command's output: Ctrl+Shift+O (Cmd+Shift+O). Useful for pasting an error into an issue or a chat with an AI tool.
  • Marks beside each prompt: grey for success, red for failure, and failed prompts are tinted red so you spot them while scrolling.
  • Scrollbar marks: every command has a mark on the scrollbar, red for failures. Click one to jump there.
  • Finished-command notifications: if a command ran for at least notify-after seconds (10 by default) and you're looking at another tab or app, Lumen sends a desktop notification and puts a green or red dot on the tab.
  • New panes in the same folder: tabs and splits open where the shell is, not in your home folder.
# ~/.config/lumen/config.toml
notify-after = 30   # only notify for commands over 30 seconds

The anti-spoofing key

Each pane gets its own random key, and Lumen's shell scripts include it in every mark. Marks without the right key are ignored. Output from cat, a build log or a remote server can contain OSC 133 sequences, but it can't know the key, so it can't fake a prompt, a success mark or a notification. Lumen uses OSC 133-style marks, so the format is familiar, but it doesn't trust the bare sequence.

Shell integration over SSH

When you SSH to another machine, the remote shell is the one drawing prompts, and Lumen can't inject anything into it. To get marks, jumps and notifications on the remote host, source Lumen's integration script there from your shell's startup file. The shell integration docs show the exact lines. Without it, SSH sessions still work; you just lose the per-command features until you exit back to your local shell.

Using the marks from scripts

The same command boundaries drive Lumen's scripting. lumen msg watch command-finished streams one JSON line per finished command, for example {"event":"command-finished","command":"npm test","exit":0}, which you can use to trigger anything else. See terminal plugins and scripting for examples.

When another terminal is the better fit

If you use PowerShell, elvish or nushell, Lumen's integration doesn't cover them; Ghostty and VS Code support more shells. iTerm2's integration has extra macOS conveniences such as automatic profile switching per host and file transfer helpers. kitty's ssh kitten can carry its integration to remote hosts for you. For splits and tabs that use the shell's folder, see splitting a terminal and terminal tabs; if you run coding agents in a terminal, the guide to the best terminal for Claude Code covers why finished-command notifications matter there.

Questions

What is OSC 133?

An escape sequence format, from the FinalTerm project, that a shell prints to mark where a prompt, a command and its output start, and how the command exited. Terminals use it for shell integration.

What is terminal shell integration?

A small script in your shell that prints invisible marks around prompts and commands, so the terminal can jump between commands, copy output, flag failures and open new tabs in the same folder.

Does shell integration work over SSH?

Only if the remote shell prints the marks. In Lumen you source the integration script on the remote host. kitty and Ghostty have SSH helpers that set things up on the remote side for you.

Can a program fake shell integration marks?

In many terminals, yes: any output can contain OSC 133 sequences. Lumen gives each pane a random key and ignores marks without it, so command output can't fake prompts or results.

Try Lumen

Free and open source, for Linux and macOS. Copy the command for your system and paste it into a terminal.

curl -fsSL https://lumenshell.dev/install | sh
brew install --cask lumenshell/tap/lumen