Marks and Scrollback
Marks divide your terminal history into navigable sections. Combined with scrollback search, they let you jump directly to the commands or output you need.
Learning Focus
Use marks to navigate command history by structure rather than by line, and master scrollback search for quick access to past output.
What Are Marks
A mark is an annotation in kitty's scrollback buffer that identifies a specific position — usually a shell prompt or command boundary. Kitty highlights marks visually and lets you jump between them.
┌── Terminal Scrollback ──────────────────────────┐
│ │
│ ▶ $ git pull ← Prompt mark │
│ Already up to date. │
│ ───────────────────────────────────────────── │
│ │
│ ▶ $ npm run build ← Prompt mark │
│ > build@1.0.0 build │
│ > vite build │
│ ✓ built in 2.3s │
│ ───────────────────────────────────────────── │
│ │
│ ▶ $ docker ps ← Prompt mark │
│ CONTAINER ID IMAGE STATUS │
│ a1b2c3d4e5f6 nginx Up 2 hours │
│ │
└──────────────────────────────────────────────────┘
Navigating Marks
| Shortcut | Action |
|---|---|
Ctrl+Shift+up | Jump to previous mark |
Ctrl+Shift+down | Jump to next mark |
Ctrl+Shift+Left | Jump to first mark on screen |
Ctrl+Shift+Right | Jump to last mark on screen |
note
These shortcuts require shell integration to be enabled. See Shell Integration Basics.
Mark Types
| Type | Description | Created By |
|---|---|---|
| Prompt marks | Mark the start of a shell prompt | Shell integration auto-marks each prompt |
| Command marks | Mark the boundary around command output | Shell integration |
| Custom marks | User-defined marks for specific patterns | kitty @ create-marker |
| Text marks | Match a literal string | Manual configuration |
| Regex marks | Match a regular expression pattern | Manual configuration |
Creating Custom Marks with create-marker
Kitty supports dynamic marks via the create-marker remote control command:
# Mark lines containing "ERROR" with a red background
kitty @ create-marker 1 --regex 'ERROR' --foreground red
# Mark function definitions in log output
kitty @ create-marker 2 --regex '^def [a-z_]+' --foreground cyan
# Create a mark for a specific text string
kitty @ create-marker 3 --text 'Traceback' --foreground yellow
# Create a mark with a custom function
kitty @ create-marker 4 --function 'first_line'
# Remove a specific marker
kitty @ remove-marker 1
# List active markers
kitty @ ls --markers
Marker Options
| Option | Description |
|---|---|
--regex PATTERN | Match lines with regex |
--text TEXT | Match lines containing text |
--function NAME | Use a built-in match function |
--foreground COLOR | Highlight color |
--background COLOR | Background highlight |
--multiple | Highlight all matches, not just first |
Configuration in kitty.conf
~/.config/kitty/kitty.conf
# Custom markers: highlight errors and warnings
marker 1 --regex 'ERROR|FATAL|CRITICAL' --foreground red --background '#330000'
marker 2 --regex 'WARN|WARNING' --foreground yellow --background '#332200'
marker 3 --regex '\[FAIL\]' --foreground red --bold
Scrollback Buffer
Kitty's scrollback buffer stores terminal history for later review.
Key Scrollback Shortcuts
| Shortcut | Action |
|---|---|
Ctrl+Shift+h | Open scrollback search |
Ctrl+Shift+up | Scroll up one line |
Ctrl+Shift+down | Scroll down one line |
Ctrl+Shift+PageUp | Scroll up one page |
Ctrl+Shift+PageDown | Scroll down one page |
Ctrl+Shift+Home | Scroll to top of history |
Ctrl+Shift+End | Scroll to bottom (latest) |
Configuring Scrollback Size
~/.config/kitty/kitty.conf
# Number of lines to keep in scrollback buffer (per window)
scrollback_lines 10000
# Enable unlimited scrollback (use with caution)
# scrollback_lines -1
Scrollback Indicator
~/.config/kitty/kitty.conf
# Show a visual indicator when scrolled back
scrollback_indicator true
# Custom indicator style: "arrow" or "bar"
scrollback_indicator_style arrow
When scrollback_indicator is true, kitty shows a ▼ or similar marker in the top-right when you are scrolled back above the current viewport.
Scrollback Search
Press Ctrl+Shift+h to open the scrollback search prompt. Kitty highlights all matches and lets you navigate through them:
Search: █
─────────────────────────────────────────────
1: ERROR: Connection refused on port 8080
2: ERROR: Timeout exceeded after 30s
3: WARN: Retrying connection (attempt 2/3)
─────────────────────────────────────────────
3 matches found. Press Tab to cycle.
| Search Key | Action |
|---|---|
Ctrl+Shift+h | Open scrollback search |
Enter | Confirm search and close |
Tab | Jump to next match |
Shift+Tab | Jump to previous match |
Escape | Cancel search |
Ctrl+c | Cancel search |
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| Marks not appearing after sourcing | Ctrl+Shift+up does nothing | Verify $KITTY_SHELL_INTEGRATION is set |
| Scrollback search finds nothing | No results for expected text | Increase scrollback_lines in config |
| Custom marker regex wrong | No lines highlighted | Test regex with kitty @ create-marker and adjust |
| Scrollback indicator missing | No visual cue for scrolled state | Set scrollback_indicator true in config |
| Marks slow with huge scrollback | Lag when jumping between marks | Reduce scrollback_lines or use fewer markers |
Hands-On Practice
# Ensure shell integration is active (source it if needed)
if [ -z "$KITTY_SHELL_INTEGRATION" ]; then
echo "Shell integration not active — source the integration file first"
# Example for bash:
# source ~/.local/kitty/shell-integration/bash/kitty.bash
fi
# Run several commands to populate scrollback
for i in $(seq 1 5); do
echo "Command number $i"
sleep 0.5
done
# Practice mark navigation
echo "Now press: Ctrl+Shift+up and Ctrl+Shift+down to jump between prompts"
# Create a custom marker for "number"
kitty @ create-marker 10 --regex 'number' --foreground green
# Open scrollback search
echo "Press: Ctrl+Shift+h and type 'number' to search"
# Remove the custom marker
kitty @ remove-marker 10
# Check scrollback configuration
kitty @ get-config scrollback_lines