Claude Code for Kitty Terminal — Workflow Guide

Written by Michael Lip · Solo founder of Zovo · $400K+ on Upwork · 100% JSS Join 50+ builders · More at zovo.one

The Setup

You are running Claude Code inside Kitty, the GPU-accelerated terminal emulator with image rendering, ligature support, and a powerful scripting system (kittens). Kitty’s unique features like inline image display and remote control enhance the Claude Code workflow. Claude Code can leverage these features, but it treats Kitty as a generic terminal.

What Claude Code Gets Wrong By Default

  1. Ignores Kitty’s image protocol. Claude generates text descriptions of images and diagrams. Kitty supports inline image rendering via its graphics protocol — Claude Code output could include image previews directly in the terminal.

  2. Uses tmux-style commands for panes. Claude writes tmux split-window for multiplexing. Kitty has built-in window management: kitty @ launch --type=window and layout switching without tmux.

  3. Opens files in a new terminal application. Claude uses open file.png which launches Preview.app. Kitty can display images inline with kitty +kitten icat image.png and open files with its configured handlers.

  4. Does not use Kitty remote control. Claude restarts Kitty for config changes. Kitty supports kitty @ remote control for font changes, layout switches, and window management without restart.

The CLAUDE.md Configuration

# Kitty Terminal Configuration

## Terminal
- Emulator: Kitty (GPU-accelerated, scriptable)
- Config: ~/.config/kitty/kitty.conf
- Remote control: kitty @ commands
- Kittens: built-in utility scripts

## Kitty Rules
- Image display: kitty +kitten icat image.png
- Diff viewer: kitty +kitten diff file1 file2
- Remote control: kitty @ set-font-size 14
- Windows: kitty @ launch --type=window
- Layouts: kitty @ goto-layout splits (tall, grid, splits, stack)
- SSH: kitty +kitten ssh user@host (preserves features)
- Clipboard: kitty +kitten clipboard (paste from clipboard)

## Conventions
- Use Kitty layouts instead of tmux for simple pane management
- Display images inline during development (icat)
- Remote control for scripted terminal configuration
- Use kitty +kitten ssh for remote Claude Code sessions
- Font ligatures enabled for code readability
- Custom key mappings in kitty.conf for Claude Code workflow
- Color scheme: matches editor theme

Workflow Example

You want to set up a development layout in Kitty for Claude Code. Prompt Claude Code:

“Configure Kitty with a splits layout for development: main editor pane on top, Claude Code pane bottom-left, and a file watcher pane bottom-right. Add key mappings for switching between panes.”

Claude Code should use kitty @ commands to create the layout, launch panes with kitty @ launch, set the layout to splits, and add key mappings in kitty.conf for ctrl+shift+1/2/3 to focus each pane.

Common Pitfalls

  1. Missing allow_remote_control in config. Claude uses kitty @ commands but they fail silently. Remote control must be enabled with allow_remote_control yes in kitty.conf, or launched with kitty -o allow_remote_control=yes.

  2. SSH sessions losing Kitty features. Claude connects with plain ssh user@host. Kitty features (image display, clipboard integration) do not work over regular SSH. Use kitty +kitten ssh user@host which auto-installs the terminfo and enables features.

  3. Font rendering differences from VS Code. Claude’s code output looks different in Kitty than VS Code. Configure font_family, bold_font, italic_font explicitly in kitty.conf for consistent code rendering, and enable disable_ligatures cursor for ligature control.