跪拜 Guibai
← All articles
Artificial Intelligence · Command Line

Ghostty Fixes the Terminal Rendering Bugs That Break Claude Code on iTerm2

By 深度学习机器 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

CLI-based AI coding tools like Claude Code, Codex, and OpenCode push terminal emulators harder than traditional dev workflows. Ghostty's GPU rendering and Kitty protocol support fix real, documented rendering bugs that iTerm2 cannot resolve without introducing new breakage, making it a practical upgrade for anyone whose terminal is now an AI pair-programming interface.

Summary

Switching from iTerm2 to Ghostty eliminates a class of rendering bugs that Claude Code users have been reporting for months—flickering text, broken Shift+Enter, duplicate output lines, and scroll position resets. The root cause is architectural: iTerm2 renders text frame-by-frame on the CPU, while Ghostty uses Metal GPU batch rendering and supports the Kitty terminal protocol's synchronous update feature. When an AI tool streams large volumes of text, Ghostty composites the entire screen update on the GPU before pushing it to the display, removing the intermediate frames that cause stutter.

For routine terminal work—git, npm, shell scripts—the difference is negligible on modern hardware. The gap becomes obvious during fast log scrolling, long-running Neovim sessions with LSP, and any TUI tool that refreshes frequently. Ghostty also handles Claude Code's heavy shortcut usage more reliably because it implements the Kitty keyboard protocol natively, avoiding the key-combination conflicts that iTerm2's custom keyboard extensions introduce.

A full configuration walkthrough covers installing Ghostty via Homebrew, pairing it with zoxide for smart directory jumping and Yazi for terminal file management, and wiring up shell integrations that set terminal titles per directory and auto-cd when exiting Yazi. The setup targets AI-assisted development specifically, with a 25-million-line scrollback buffer and a Quake-style dropdown terminal accessible from a global hotkey.

Takeaways
— Ghostty renders text on the GPU via Metal, while iTerm2 uses CPU-based Core Graphics—this eliminates intermediate frames that cause flicker during rapid text streaming.
— Claude Code's `CLAUDE_CODE_NO_FLICKER=1` workaround reduces flicker on iTerm2 but breaks Shift+Enter, freezes the editor, and causes scroll-reset bugs.
— Ghostty supports the Kitty protocol's synchronous rendering, which waits for GPU-side compositing to finish before refreshing the screen.
— Native Kitty keyboard protocol support means Ghostty correctly interprets the rich shortcut combinations (Shift+Tab, Ctrl+O, Ctrl+B) that AI tools rely on.
— For everyday commands like git, npm, and ls, the performance difference between iTerm2 and Ghostty is imperceptible on modern hardware.
— Fast log scrolling, Neovim with LSP, and full-screen TUI tools like htop and lazygit show the most noticeable improvement on Ghostty.
— A 25-million-line scrollback buffer prevents AI tool output from being truncated during long sessions.
— Zoxide replaces cd with frequency-based smart jumping; Yazi provides a Vim-style terminal file manager that auto-cds on exit.
Conclusions

Claude Code's rendering issues on iTerm2 are not bugs in Claude Code—they are protocol incompatibilities between a modern TUI rendering engine and a terminal emulator built on xterm extensions from a different era.

The `CLAUDE_CODE_NO_FLICKER` flag is a telling artifact: it patches one symptom (flicker) by enabling the alternate screen buffer, but that buffer interacts poorly with iTerm2's implementation, creating a cascade of new bugs. Ghostty needs no such flag because the underlying protocol handles the problem correctly.

Terminal emulator choice is becoming a functional dependency for AI-assisted development, not just a preference. The same way a GPU driver matters for gaming, the terminal's protocol support and rendering pipeline now directly affect whether an AI coding tool works reliably.

Ghostty's architectural bet—Zig for low resource usage, native platform controls, and Kitty protocol first—sidesteps the accumulated complexity that makes iTerm2 fragile under new workloads. It's a clean-slate design for a terminal that is now a primary development interface rather than a background utility.

Concepts & terms
Kitty Terminal Protocol
A modern terminal protocol that extends xterm with features like synchronous rendering, native image display, and a richer keyboard protocol. It allows the terminal and applications to coordinate screen updates to eliminate flicker.
Synchronous Rendering
A GPU rendering technique where the terminal waits for all screen updates to be composited in GPU memory before pushing a complete frame to the display, avoiding partial draws that appear as flicker or tearing.
Alternate Screen Buffer
A separate terminal screen buffer that applications can switch to for full-screen TUI interfaces. It preserves the main buffer's content and is commonly used by text editors and AI tools to prevent scrollback pollution.
Zig
A systems programming language designed as a simpler alternative to C, with manual memory management, no hidden control flow, and compile-time code execution. Ghostty uses it for performance and low resource overhead.
Source: juejin.cn ↗ Google Translate ↗ Backup ↗