Icat and Diff Kittens
The icat and diff kittens are two of the most immediately useful built-in extensions. Icat brings images into your terminal; diff turns kitty into a visual diff tool.
Learning Focus
Master the icat and diff kittens to view images inline and compare files visually — two capabilities that set kitty apart from other terminals.
Icat Kitten — Inline Images
The icat kitten renders images directly in the terminal using kitty's graphics protocol.
Basic Usage
# Display an image at its natural size
kitty +kitten icat screenshot.png
# Display with specific placement
kitty +kitten icat --place 80x40@0x0 image.png
# Scale up a small image
kitty +kitten icat --scale-up diagram.png
# Display in a specific terminal window
kitty +kitten icat --place 40x20@10x5 photo.jpg
Options Reference
| Option | Description | Default |
|---|---|---|
--place WxH@XxY | Position and size in cell units | Auto-detect |
--scale-up | Enlarge images smaller than cell | Off |
--transfer-mode | How to send image data (file, stream, background) | auto |
--clear | Clear all displayed images | — |
--silent | Suppress status messages | Off |
--hold | Keep image open after kitten exits | Off |
Transfer Modes
| Mode | Description | Best For |
|---|---|---|
file | Send file path to kitty | Local images, fastest |
stream | Stream pixel data over stdin | Piped image data |
background | Send in background thread | Large images |
Use Cases
Viewing images on remote servers:
# SSH into server and view an image
ssh user@server "kitty +kitten icat --transfer-mode file /var/www/screenshot.png"
Image in a pipeline:
# Generate a plot and display it
python3 -c "
import matplotlib.pyplot as plt
plt.plot([1,2,3],[4,5,6])
plt.savefig('/tmp/plot.png')
" && kitty +kitten icat /tmp/plot.png
Clearing images:
# Clear all icat images from the terminal
kitty +kitten icat --clear
warning
On remote servers, kitty must be installed on the remote machine for icat to work over SSH.
Diff Kitten — Visual File Comparison
The diff kitten shows a side-by-side visual diff with syntax highlighting.
Basic Usage
# Compare two files
kitty +kitten diff file1.txt file2.txt
# Compare two directories
kitty +kitten diff /path/to/dir1 /path/to/dir2
# Compare git revisions
kitty +kitten diff <(git show HEAD:file.txt) file.txt
Features
- Syntax highlighting for 200+ languages
- Side-by-side or unified view
- Scroll sync — both panes scroll together
- Word-level diff highlighting
- Keyboard navigation for quick review
- File tree for directory comparisons
Key Bindings
| Key | Action |
|---|---|
Up/Down | Scroll line by line |
PgUp/PgDn | Scroll page by page |
Home/End | Jump to start/end |
q | Quit diff viewer |
Tab | Toggle side-by-side / unified view |
g | Go to next change |
G | Go to previous change |
1-9 | Adjust split ratio |
r | Refresh view |
? | Show help overlay |
Integrating with Git Diff
~/.gitconfig
[diff]
external = kitty +kitten diff
Or use as a one-off:
git difftool --tool=kitty
For a custom git alias:
git config --global alias.kdiff '!kitty +kitten diff'
Then use:
git kdiff HEAD~1:config/settings.yaml config/settings.yaml
Comparing with Patch Files
# Apply diff output to compare
kitty +kitten diff original.txt <(git diff HEAD~1 -- myfile.txt)
Common Pitfalls
| Pitfall | Symptom | Fix |
|---|---|---|
| Icat image too large | Overflows terminal | Use --place to constrain dimensions |
| Diff kitten not found | kitty +kitten diff fails | Verify kitty is in PATH and up to date |
| Git diff external breaks pager | Git commands hang | Use git difftool instead of git diff |
| Icat on remote without kitty | "No kitty terminal detected" | Install kitty on remote, or use scp first |
| Diff no syntax highlighting | Plain text view | Ensure file extension is recognized |
Hands-On Practice
# Create two test files and diff them
echo -e "line one\nline two\nline three" > /tmp/file_a.txt
echo -e "line one\nline changed\nline three\nline four" > /tmp/file_b.txt
# View the diff
kitty +kitten diff /tmp/file_a.txt /tmp/file_b.txt
# Download an image and view it
curl -s https://upload.wikimedia.org/wikipedia/en/7/7d/Lenna_%28test_image%29.png -o /tmp/lenna.png
kitty +kitten icat /tmp/lenna.png
# Test image placement
kitty +kitten icat --place 40x15@0x0 /tmp/lenna.png
# Clean up
rm /tmp/file_a.txt /tmp/file_b.txt /tmp/lenna.png