tty7/docs/terminal/prompt.mdx

---
title: "The prompt"
description: "Ghost suggestions, tab completion that explains itself, syntax highlighting, and real multi-line editing."
---

tty7 puts an editor at the shell prompt. Nothing to install, no plugin to source
— the moment a supported shell starts in a pane, the prompt behaves like this.

<Frame caption="Ghost suggestions from history, then the completion menu">
  <video autoPlay muted loop playsInline src="/images/prompt-editor.mp4" aria-label="The tty7 prompt" />
</Frame>

## Ghost suggestions

As you type, the rest of the line is filled in from your history, greyed out
ahead of the cursor.

| | |
|---|---|
| <kbd>→</kbd> | Accept the whole suggestion |
| Keep typing | The suggestion narrows |
| Anything that does not match | It disappears |

Your existing shell history is what feeds it — there is no separate database to
build up first, and it carries across sessions and reboots.

## Tab completion, with descriptions

<kbd>⇥</kbd> opens a completion menu that knows what it is offering:

- **Commands** from your PATH and your shell's builtins
- **Files and directories**, with `cd`, `pushd`, `popd`, and `rmdir` offering
  directories only
- **Flags and subcommands** with their descriptions, for about 100 common
  commands — `git`, `cargo`, `docker`, `kubectl`, `npm`, `brew` and the rest
- **Values** where a flag only takes certain ones

<Frame caption="Completion on `git ch`, each subcommand with its description">
  <img src="/images/prompt-completion.webp" alt="Explained tab completion" />
</Frame>

When tty7 has nothing useful to offer, the <kbd>⇥</kbd> falls through to your
shell's own completion, so a carefully configured zsh setup is not lost.

To hand <kbd>⇥</kbd> back to the shell entirely, turn off **Settings → Terminal →
Prompt & command history → Tab completion** (`tab_completion` in `config.json`).

## Syntax highlighting

The line you are typing is coloured as you type it: the command, its flags, its
arguments, paths, quoted strings, operators, comments. It is a fast tokenizer,
not a shell parser — it never changes what gets run.

## Line editing

The prompt behaves like a text field, because it is one:

- **Click to place the caret** anywhere in the line
- **Select with the mouse**, drag to extend
- **Word motion** and word delete
- **Undo**

Everything readline does still works — this sits on top, it does not replace it.

<Tip>
  On macOS, turn on **Settings → Keyboard & Mouse → Keyboard → Option (⌥) acts as Meta** if
  you want <kbd>⌥ B</kbd> / <kbd>⌥ F</kbd> to move by word instead of typing
  `∫` and `ƒ`.
</Tip>

## Typing with an IME

Pinyin, Kana, Hangul and the rest work in a pane the way they do in a text
field: the composition is drawn in place at the cursor and only the committed
text reaches the program.

Two rules decide who gets a keystroke:

- **A plain printable key goes to the IME.** A key held with <kbd>⌃</kbd>,
  <kbd>⌘</kbd>, <kbd>fn</kbd>, or <kbd>⌥</kbd> does not — those are chords, not
  characters.
- **A program that asks for every key gets every key.** When something turns on
  the kitty keyboard protocol's report-all-keys mode, the IME steps aside so the
  program sees raw input.

<Note>
  On macOS with **Option (⌥) acts as Meta** turned on, <kbd>⌥</kbd> chords
  bypass the IME entirely, so <kbd>⌥ B</kbd> reaches your shell as meta-b
  instead of being eaten as a dead key.
</Note>

Rendering CJK well is a separate question — see
[fonts and the two-column grid](/customization/fonts#cjk-and-the-two-column-grid).

## Multi-line commands

A command that wraps, or one you deliberately break across lines, edits in
place. The grid shifts to keep the caret visible instead of scrolling the whole
screen away.

When the prompt itself takes up most of the row — a deep working directory, a
busy theme — the line you type starts on the row below it instead, with the
full width of the pane. That happens once the prompt leaves fewer than a third
of the columns (never fewer than 20); an ordinary prompt keeps the input beside
it. To keep the prompt short instead, trim it in the shell: `%2~` in a zsh
`PROMPT`, fish's `prompt_pwd`, or starship's `truncation_length`.

| | |
|---|---|
| <kbd>⇧ ⏎</kbd> · <kbd>⌥ ⏎</kbd> | Insert a newline instead of submitting |
| <kbd>⏎</kbd> | Submit the whole buffer, however many lines it is |

The newline key is rebindable as `InsertNewline` under **Settings →
Keybindings**.

## Which shells

The prompt features arrive through tty7's shell integration, which is injected
automatically — nothing to add to your rc file — for **zsh**, **bash**,
**fish**, **PowerShell**, and **WSL**. Other shells (nushell, elvish, xonsh, and
the rest) run perfectly well in a pane; they simply do not get the prompt layer.

The integration is also what reports the working directory, the exit code of
each command, and where prompts begin — which is what the sidebar's branch
readout, the "command finished" notification, and `tty7 procs` are built on.

[How shell integration works →](/reference/shell-integration)

## Turning it off

Each prompt feature is a switch, and turning one off hands its key straight back
to the shell:

| Setting | Key it releases |
|---|---|
| **Settings → Terminal → Prompt & command history → Tab completion** | <kbd>⇥</kbd> → your shell's completion |
| **Settings → Terminal → Prompt & command history → Command history search** | <kbd>⌃ R</kbd> → your shell's reverse-i-search, or your fzf binding |

### Giving the whole prompt back to the shell

Turning off **Settings → Terminal → Prompt & command history → tty7 prompt editor**
(`prompt_editor: false`) hands over not one key but the line itself. Every
keystroke at the prompt — printable characters, arrows, IME commits, paste — goes
straight to the PTY, and your shell's own line editor does the editing: zsh's
ZLE, bash's readline, fish's reader. A widget you bound yourself runs exactly as
it does outside tty7:

```zsh
# ~/.zshrc — works at a tty7 prompt with the editor off
bindkey '^[[A' history-beginning-search-backward-end
```

What you give up is the layer this page describes: ghost suggestions, the
completion menu, the fuzzy <kbd>⌃ R</kbd>, the multi-line editor, mouse caret
placement and undo on the prompt. Tab completion and history search grey out in
Settings while it is off — both are menus tty7 opens inside that editor, so
there is nothing left for them to switch.

What you keep is everything shell integration reports: prompt boundaries, the
working directory, exit codes, "command finished" notifications, the sidebar's
branch readout, `tty7 procs`. The setting moves the line editor, not the
integration.

It applies to open panes immediately, so there is nothing to restart, and a line
you had half-typed is handed to the shell rather than dropped.

<Tip>
  Reach for this if the shell's own history traversal matters to you — shared
  history between panes, `HIST_FIND_NO_DUPS`, a prefix search bound to
  <kbd>↑</kbd> — or if a plugin you rely on (zsh-autosuggestions,
  zsh-syntax-highlighting, atuin) should own the line instead.
</Tip>