Skip to main content

Set up your terminal for agents

Agent CLIs work in Saggar without configuration. This page is for when a key or a cue isn't behaving the way an agent's own documentation says it should. Find your symptom below; if everything already feels right, you don't need this page.

Each agent also documents its own terminal expectations. The per-provider links at the end point at those pages; use them for keybindings, Vim mode, and anything else that lives inside the agent rather than in the terminal.

Insert a newline without submitting​

Shift+Enter inserts a newline in every provider Saggar knows, with no setup. Saggar sends Shift+Return as the CSI 13;2u sequence the kitty keyboard protocol defines, which is what Claude Code, Codex, Pi, OpenCode, GitHub Copilot CLI, and Antigravity CLI all read as "newline, not submit".

Don't run Claude Code's /terminal-setup for this. It writes a Shift+Enter binding into other terminal apps' configuration, and Saggar is not one of them: its terminals identify themselves as TERM_PROGRAM=saggar. Ctrl+J, and \ followed by Enter, also insert a newline in every provider.

Option+Enter needs the Meta setting below.

Enable Option key shortcuts​

Some agent shortcuts use Option, such as Option+Enter for a newline in Copilot CLI or Option+P to switch models in Claude Code. Saggar leaves Option to your keyboard layout by default, so ⌥3 still types # and dead keys still compose accents, and those agent shortcuts do nothing until you turn Meta on.

Open Settings ▸ Sessions and turn on Use Option as the Meta key, or use this link:

Use Option as Meta

With Meta on, Saggar sends every Option chord to the terminal program as an Escape-prefixed sequence, the same as "Use Option as Meta Key" in Terminal.app or "Esc+" in iTerm2. With it off, the four editing chords still reach the shell: Option+Backspace and Option+Delete erase a word, and Option+← and Option+→ jump one.

Hear when an agent needs you​

With a provider's hooks installed, the agent tells Saggar directly when it needs you and when it finishes, so the session's status changes and the attention cue fires without any terminal setting. This section is for unhooked sessions and for other programs.

Saggar reads three things a program can print:

  • The terminal bell. Saggar never beeps. A bell turns the session Needs you and raises the attention cue instead.
  • Raised notifications over OSC 9, kitty's OSC 99, or OSC 777, with a title, a body, and an urgency. Settings ▸ Notifications ▸ Notifications from programs controls whether they show, and urgent ones make the session need you.
  • Progress over ConEmu's OSC 9;4, shown on the session's row.

So point each agent at the bell or a raised notification rather than at a desktop notification it won't be able to send:

  • Claude Code sends a desktop notification only in Ghostty, Kitty, and iTerm2. In Saggar, set preferredNotifChannel to "terminal_bell" in ~/.claude/settings.json, or leave it to the hooks.
  • Codex rings its notification through OSC 9 or the bell depending on tui.notification_method; the default auto works, and both routes reach Saggar.
  • Antigravity CLI rings the bell when its notifications setting is on.
  • OpenCode and Pi raise their notifications from their own attention settings, linked below.

Any program can raise its own notice without an agent involved:

printf '\e]777;notify;Build finished;3 warnings\a'

Configure tmux​

Saggar's own terminals don't run tmux, but its saved SSH targets attach to a named tmux session on the remote host, and a tmux you start by hand sits in the same position. By default tmux turns Shift+Enter back into plain Enter and swallows the notifications and progress the section above relies on. Add these lines to ~/.tmux.conf on the machine running tmux, then run tmux source-file ~/.tmux.conf to apply them to the running server:

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

allow-passthrough lets raised notifications and progress reach Saggar. extended-keys lets tmux tell Shift+Enter from Enter, and the terminal-features line enables it for the xterm-256color terminal Saggar advertises. extended-keys-format csi-u needs tmux 3.5 or later and makes tmux forward the same CSI u sequence Saggar sends; on tmux 3.2 to 3.4, leave that line out.

Keep the transcript in scrollback​

Find in this terminal, the prompt walk, the palette's search inside sessions, and the scrollback a restored session replays all read the terminal's scrollback buffer. A program running on the terminal's alternate screen keeps its transcript out of that buffer while it runs, so those features see the shell that launched it and nothing more.

The default rendering in every provider stays in the main screen and keeps scrollback working. If you change it, you trade those features:

  • Codex: tui.alternate_screen = "never" keeps the transcript in scrollback.
  • Antigravity CLI: choose inline rendering rather than alt-screen.
  • Claude Code: its fullscreen renderer uses the alternate screen. Saggar honors synchronized output frames, so the flicker that mode exists to fix shouldn't appear here.

Scrollback depth is a setting: Settings ▸ Sessions ▸ Scrollback applies to open sessions straight away, except one currently showing a full-screen program.

Paste prompts and files​

Saggar asks before pasting more than one line, because a pasted script runs each line as it arrives in a plain shell. Agents receive a paste bracketed, so a multi-line prompt lands as text rather than as several submissions. If the confirmation gets in the way, Don't ask again on the prompt, or Settings ▸ Sessions ▸ Confirm before pasting more than one line, turns it off.

Agents collapse a long paste to a placeholder and send the full text on submit, so a pasted log doesn't flood the screen. For anything the size of a file, write it to disk and ask the agent to read it by path instead. A pasted or dropped image reaches Claude Code and Codex as an attachment; see Tips.

Match colors and fonts​

Settings ▸ Appearance chooses the terminal font, its own point size, and whether the terminal canvas follows Saggar's light and dark appearance or stays dark for tools whose dim colors assume a dark background. Saggar doesn't set an agent's palette; each agent has a theme picker of its own, linked below. Pick one that matches the canvas, or the agent's automatic or terminal-following option where it has one, so the two don't fight when the appearance flips.

Provider terminal guides​

Each agent's own documentation covers its keys, notifications, and themes, including its Vim editing mode where it has one.

ProviderKeys and newlinesNotificationsThemes and rendering
Claude CodeTerminal configuration and keybindingsTerminal bell or notificationMatch the color theme, fullscreen rendering
CodexCommands and shortcutsNotificationsCLI customization, TUI options
Antigravity CLIKeybindingsConfiguration optionsRendering modes
PiTerminal setup, tmux, and keybindingsSettingsThemes
OpenCodeKeybindsAttentionThemes
GitHub Copilot CLICommand reference