Configure your terminal for Claude Code

Claude Code works in any terminal without configuration. This page is for when something specific is not behaving the way you expect. Find your symptom below. If everything already feels right, you do not need this page.

Shift+Enter submits instead of inserting a newline
Option-key shortcuts do nothing on macOS
No sound or alert when Claude finishes
You run Claude Code inside tmux
Display flickers or scrollback jumps
You want Vim keys in the prompt

This page is about getting your terminal to send the right signals to Claude Code. To change which keys Claude Code itself responds to, see keybindings instead.

Enter multiline prompts

Pressing Enter submits your message. To add a line break without submitting, press Ctrl+J, or type \ and then press Enter. Both work in every terminal with no setup. In most terminals you can also press Shift+Enter, but support varies by terminal emulator:

Terminal	Shift+Enter for newline
Ghostty, Kitty, iTerm2, WezTerm, Warp, Apple Terminal, Windows Terminal	Works without setup
VS Code, Cursor, Devin Desktop, Alacritty, Zed	Run `/terminal-setup` once
gnome-terminal, JetBrains IDEs such as PyCharm and Android Studio	Not available; use Ctrl+J or `\` then Enter

For VS Code, Cursor, Devin Desktop, Alacritty, and Zed, /terminal-setup writes Shift+Enter and other keybindings into the terminal’s configuration file. On the first run you see a confirmation such as Installed VSCode terminal Shift+Enter key binding. Existing bindings are left in place; if you see a message such as VSCode terminal Shift+Enter key binding already configured, no change was made. Run /terminal-setup directly in the host terminal rather than inside tmux or screen, since it needs to write to the host terminal’s configuration. In VS Code, Cursor, and Devin Desktop, /terminal-setup also updates two editor settings: it sets terminal.integrated.gpuAcceleration to "off" to prevent garbled text in the integrated terminal, and it sets terminal.integrated.mouseWheelScrollSensitivity for smoother scrolling in fullscreen mode. To undo the GPU acceleration change, set it back to "auto" and reload the editor window. If you are running inside tmux, Shift+Enter also requires the tmux configuration below even when the outer terminal supports it. To bind newline to a different key, or to swap behavior so Enter inserts a newline and Shift+Enter submits, map the chat:newline and chat:submit actions in your keybindings file.

Enable Option key shortcuts on macOS

Some Claude Code shortcuts use the Option key, such as Option+Enter for a newline or Option+P to switch models. On macOS, most terminals do not send Option as a modifier by default, so these shortcuts do nothing until you enable it. The terminal setting for this is usually labeled “Use Option as Meta Key”; Meta is the historical Unix name for the key now labeled Option or Alt.

Apple Terminal
iTerm2
VS Code

Open Settings → Profiles → Keyboard and check “Use Option as Meta Key”.If you accepted Claude Code’s first-run terminal setup prompt, this is already done. That prompt runs /terminal-setup for you, which enables Option as Meta and turns off the audible bell in your Apple Terminal profile.In screen reader mode, /terminal-setup leaves the bell setting unchanged so the terminal bell stays audible. Before v2.1.211, /terminal-setup turned the bell off even in screen reader mode. If an earlier run turned the bell off, turn it back on under Settings → Profiles → Advanced → “Audible bell”.

Open Settings → Profiles → Keys → General and set Left Option key and Right Option key to “Esc+”.Running /terminal-setup in iTerm2 enables “Applications in terminal may access clipboard” under Settings → General → Selection so the /copy command can write to your system clipboard. The command detects iTerm2 even when run from inside tmux. Restart iTerm2 for the change to take effect.

Add "terminal.integrated.macOptionIsMeta": true to your VS Code settings.

For Ghostty, Kitty, and other terminals, look for an Option-as-Alt or Option-as-Meta setting in the terminal’s configuration file.

Get a terminal bell or notification

When Claude finishes a task or pauses for a permission prompt, and you appear to be away from the terminal, it fires a notification event. See when each notification type fires for the exact timing. Surfacing this as a terminal bell or desktop notification lets you switch to other work while a long task runs. By default Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2. In other terminals, set preferredNotifChannel to "terminal_bell" to ring the terminal bell instead, or configure a Notification hook for a custom sound or command. The following settings entry turns on the terminal bell:

~/.claude/settings.json

{
  "preferredNotifChannel": "terminal_bell"
}

The desktop notification reaches your local machine over SSH, so a remote session can still alert you. Ghostty and Kitty forward it to your OS notification center without further setup. iTerm2 requires you to enable forwarding:

Open iTerm2 notification settings

Go to Settings → Profiles → Terminal.

Enable alerts

Check “Notification Center Alerts”, then click “Filter Alerts” and enable “Send escape sequence-generated alerts”.

If notifications still do not appear, confirm that your terminal application has notification permission in your OS settings, and if you are running inside tmux, enable passthrough.

Play a sound with a Notification hook

In any terminal you can configure a Notification hook to play a sound or run a custom command when Claude needs your attention. Hooks run alongside the built-in notification rather than replacing it, so terminals that do not receive a desktop notification, such as Warp or the VS Code integrated terminal, can use a hook or set preferredNotifChannel to "terminal_bell" instead. The example below plays a system sound on macOS. The linked guide has desktop notification commands for macOS, Linux, and Windows.

~/.claude/settings.json

{
  "hooks": {
    "Notification": [
      {
        "hooks": [{ "type": "command", "command": "afplay /System/Library/Sounds/Glass.aiff" }]
      }
    ]
  }
}

Configure tmux

When Claude Code runs inside tmux, two things break by default: Shift+Enter submits instead of inserting a newline, and desktop notifications and the progress bar never reach the outer terminal. Add these lines to ~/.tmux.conf, then run tmux source-file ~/.tmux.conf to apply them to the running server:

~/.tmux.conf

set -g allow-passthrough on
set -s extended-keys on
set -as terminal-features 'xterm*:extkeys'

The allow-passthrough line lets notifications and progress updates reach the outer terminal instead of being swallowed by tmux. The extended-keys lines let tmux distinguish Shift+Enter from plain Enter so the newline shortcut works.

Match the color theme

Use the /theme command, or the theme picker in /config, to choose a Claude Code theme that matches your terminal. Selecting the auto option detects your terminal’s light or dark background, so the theme follows OS appearance changes whenever your terminal does. Claude Code does not control the terminal’s own color scheme, which is set by the terminal application. To customize what appears at the bottom of the interface, configure a custom status line that shows the current model, working directory, git branch, or other context.

Create a custom theme

In addition to the built-in presets, /theme lists any custom themes you have defined and any themes contributed by installed plugins. Select New custom theme… at the end of the list to create one interactively: you name the theme, then pick individual color tokens to override. Press Ctrl+E while a custom theme is highlighted to edit it. Each custom theme is a JSON file in ~/.claude/themes/. The filename without the .json extension is the theme’s slug, and selecting the theme stores custom:<slug> as your theme preference. The file has three optional fields:

Field	Type	Description
`name`	string	Display label shown in `/theme`. Defaults to the filename slug
`base`	string	Built-in preset the theme starts from: `dark`, `light`, `dark-daltonized`, `light-daltonized`, `dark-ansi`, or `light-ansi`. Defaults to `dark`
`overrides`	object	Map of color token names to color values. Tokens not listed here fall through to the base preset

Color values accept #rrggbb, #rgb, rgb(r,g,b), ansi256(n), or ansi:<name> where <name> is one of the 16 standard ANSI color names such as red or cyanBright. Unknown tokens and invalid color values are ignored, so a typo cannot break rendering. The following example defines a theme that keeps the dark preset but recolors the prompt accent, error text, and success text:

~/.claude/themes/dracula.json

{
  "name": "Dracula",
  "base": "dark",
  "overrides": {
    "claude": "#bd93f9",
    "error": "#ff5555",
    "success": "#50fa7b"
  }
}

Claude Code watches ~/.claude/themes/ and reloads when a file is added or changed, so edits made in your editor apply to a running session without a restart. If the ~/.claude/themes/ folder itself didn’t exist when Claude Code started, restart once after creating your first theme file. After that, changes apply without a restart. The reference below covers the tokens you can set in overrides. The interactive editor in /theme shows the same tokens with a live preview, plus a few single-purpose accents such as onboarding screen colors that are omitted here.

Color token reference

The following example combines tokens from several of the groups below: the brand accent, the plan mode border, the diff backgrounds, and the fullscreen message background.

~/.claude/themes/midnight.json

{
  "name": "Midnight",
  "base"

Settings and permissions

Environments

Model and responses

Interface

Configure your terminal for Claude Code

Enter multiline prompts

Enable Option key shortcuts on macOS

Get a terminal bell or notification

Play a sound with a Notification hook

Configure tmux

Match the color theme

Create a custom theme

​Enter multiline prompts

​Enable Option key shortcuts on macOS

​Get a terminal bell or notification

​Play a sound with a Notification hook

​Configure tmux

​Match the color theme

​Create a custom theme

Enter multiline prompts

Enable Option key shortcuts on macOS

Get a terminal bell or notification

Play a sound with a Notification hook

Configure tmux

Match the color theme

Create a custom theme