Skip to main content

Shell Integration Basics

Shell integration connects kitty with your shell to provide prompt-aware scrolling, mark-based navigation, and scrollback annotations.

Learning Focus

Enable shell integration in your shell configuration to unlock prompt jumping, command output marks, and structured scrollback navigation.

What Shell Integration Provides​

When enabled, kitty understands the structure of your terminal session — it knows where prompts begin, where command output ends, and can navigate based on that structure.

FeatureBenefit
Prompt marksJump between shell prompts with keyboard shortcuts
Command marksMark each command's output for navigation
Scrollback annotationsKitty annotates the scrollback buffer for structured access
Cursor syncScroll the viewport without losing your prompt position
Output streamingSee command output in real time with synchronized scrolling

How It Works​

┌──────────────────────────────────────────────────────┐
│                 Terminal Window                       │
│                                                       │
│  $ git status                    ← Prompt (marked)    │
│  On branch main                                       │
│  Your branch is up to date...    ← Command output     │
│                                                       │
│  ──── mark ────                                       │
│                                                       │
│  $ docker compose up -b         ← Next prompt (marked)│
│  [+] Building 0.5s                                     │
│  [+] Running 2/2                                       │
│  ✔ Container app  Started                              │
│  ✔ Container db   Started       ← Output              │
│                                                       │
└──────────────────────────────────────────────────────┘
         ▲                              ▲
         │                              │
  Ctrl+Shift+up/down              Ctrl+Shift+h
  (jump by mark)                  (search scrollback)

Kitty uses OSC escape codes (Operating System Command sequences) to communicate with the shell. When your shell outputs a prompt, kitty detects the OSC code and records the position as a mark.

Enabling Shell Integration​

For Bash​

Add to ~/.bashrc:

~/.bashrc
# Enable kitty shell integration
if [ -n "$KITTY_SHELL_INTEGRATION" ]; then
  source "$HOME/.local/kitty/shell-integration/bash/kitty.bash"
fi

For Zsh​

Add to ~/.zshrc:

~/.zshrc
# Enable kitty shell integration
if [ -n "$KITTY_SHELL_INTEGRATION" ]; then
  source "$HOME/.local/kitty/shell-integration/zsh/kitty.zsh"
fi

For Fish​

Add to ~/.config/fish/config.fish:

~/.config/fish/config.fish
# Enable kitty shell integration
if set -q KITTY_SHELL_INTEGRATION
  source "$HOME/.local/kitty/shell-integration/fish/kitty.fish"
end
note

The $KITTY_SHELL_INTEGRATION environment variable is set automatically by kitty when it launches a shell. The check ensures the integration only loads when running inside kitty.

Verify It Is Working​

After sourcing the integration file, run:

echo $KITTY_SHELL_INTEGRATION
# Should output: enabled

Quick Test​

# Source the integration (adjust path for your shell)
source "$HOME/.local/kitty/shell-integration/bash/kitty.bash" 2>/dev/null || \
  echo "Integration file not found. Is kitty installed?"

# Now run a few commands
ls -la
echo "hello"
pwd

# Try jumping between prompts
# Press: Ctrl+Shift+up / Ctrl+Shift+down

OSC Escape Codes Used​

CodePurposeSent By
OSC 133 ; A STPrompt start (before prompt)Shell integration
OSC 133 ; B STPrompt end (after prompt)Shell integration
OSC 133 ; C STCommand startShell integration
OSC 133 ; D STCommand endShell integration
OSC 133 ; L STTitle/description for a markKitty or manual

Shell Integration Options​

Control which features are enabled:

~/.bashrc
# Enable all features
export KITTY_SHELL_INTEGRATION="enabled"

# Enable only specific features
export KITTY_SHELL_INTEGRATION="enabled no-cursor no-prompt-mark"

Available feature flags:

FlagWhat It Disables
no-cursorDisable cursor synchronization
no-prompt-markDisable prompt mark annotations
no-output-streamDisable output streaming

Supported Shells​

ShellStatusIntegration File Location
Bash✅ Full support~/.local/kitty/shell-integration/bash/kitty.bash
Zsh✅ Full support~/.local/kitty/shell-integration/zsh/kitty.zsh
Fish✅ Full support~/.local/kitty/shell-integration/fish/kitty.fish

Common Pitfalls​

PitfallSymptomFix
Integration not sourced before promptPrompt marks not appearingSource before setting PS1 in .bashrc
Double-sourcing the integrationDuplicate marks, slowdownGuard with [[ -z $KITTY_SHELL_INTEGRATION ]] check
Using $PROMPT_COMMAND that clears marksMarks lost after each commandChain $PROMPT_COMMAND instead of overwriting
Remote SSH sessions without integrationNo marks on remoteInstall kitty or copy shell-integration files to remote
Fish integration not loadingShell integration file not foundVerify fish version >= 3.0

Hands-On Practice​

# Locate the shell integration file for your shell
ls -la "$HOME/.local/kitty/shell-integration/" 2>/dev/null || \
  echo "Kitty not found at default path"

# If kitty is installed, test sourcing
if [ -f "$HOME/.local/kitty/shell-integration/bash/kitty.bash" ]; then
  source "$HOME/.local/kitty/shell-integration/bash/kitty.bash"
  echo "Shell integration activated for this session"
fi

# Verify
echo "KITTY_SHELL_INTEGRATION=$KITTY_SHELL_INTEGRATION"

What's Next​