Claude Code for Kitty Terminal (2026)

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 use 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.

Common Questions

How do I get started with claude code for kitty terminal?

Begin with the setup instructions in this guide. Install the required dependencies, configure your environment, and test with a small project before scaling to your full codebase.

What are the prerequisites?

You need a working development environment with Node.js or Python installed. Familiarity with the command line and basic Git operations is helpful. No advanced AI knowledge is required.

Can I use this with my existing development workflow?

Yes. These techniques integrate with standard development tools and CI/CD pipelines. Start by adding them to a single project and expand once you have verified the benefits.

Where can I find more advanced techniques?

Explore the related resources below for deeper coverage. The Claude Code documentation and community forums also provide advanced patterns and real-world case studies.