Zed: The Convergence

I’ve been running a split setup for months. iTerm2 for the terminal. Sublime Text for the editor. Claude Code bridging them together with AI. It worked. It shipped code. But there was always this friction — this invisible tax you pay when your workflow lives across three separate windows, three separate contexts, three separate mental models.

You alt-tab. You lose your place. You context-switch. And every switch costs you cycles. Not machine cycles — yours.

Zed brings the editor, terminal and AI workflow into one interface.

The Stack Collapse

Zed is what happens when someone builds an editor with zero nostalgia and zero bloat. Written in Rust. Loads instantly. Renders at GPU speed. It doesn’t try to be everything — it just happens to be everything I need.

Here’s what clicked:

Project Switcher — Open a local project and it appears in the top-left switcher. Click it, and you’re inside that project. Full UI, full context, full environment. No “Open Folder” dialogs. No workspace configuration files. Just your code, ready.

Integrated Terminal — Full-screen terminal, right inside the editor. I run Claude Code here the same way I ran it in iTerm2 — except now it’s one keystroke away from my file tree, my editor, my git status. No alt-tab. No lost context.

File Tree — Clean, fast, responsive. Exactly what a file tree should be and nothing more.

Git Integration — Built-in git support that stays out of your way until you need it. Diffs, status, branches — all right there.

Editor — Fast. Precise. Syntax highlighting, multiple cursors, the works. Sublime-level editing speed with none of the plugin archaeology.

Markdown Support — For someone who writes blog posts, documentation, and PRDs in markdown, native support without plugins is a quiet luxury.

Why It Matters

This isn’t about features. Every editor has features. This is about convergence — the moment when separate tools collapse into one and the friction disappears.

I used to think the ideal setup was modular: pick the best terminal, the best editor, the best AI tool, wire them together. But the overhead of orchestration was the thing I didn’t account for. The cognitive load of keeping three apps synchronized — that’s the hidden cost.

Zed eliminates it. Not by being the best terminal or the best editor in isolation. By being good enough at everything, fast enough at everything, and present in one single window.

For a principal engineer running Claude Code as the daily AI workflow, this is the setup. One editor. One terminal. One context. The stack collapses. The friction vanishes. You just write code.

The One Catch (And How to Fix It)

There’s one thing Zed does that nearly broke the magic. When you switch projects using that beautiful top-left project switcher, Zed kills everything in the terminal. Everything. Your Claude Code session. Your running processes. Your entire context. Gone.

Switching the workspace can close its integrated terminal. Treat terminal process lifetime separately from the project UI, and verify the behavior of the installed Zed version. A tmux server can preserve sessions when its terminal client disconnects.

For someone running Claude Code as the daily workflow, this is a dealbreaker. Or it would be — if tmux didn’t exist.

tmux is a terminal multiplexer. It runs a background server that holds your sessions. When Zed kills the terminal on project switch, only the tmux client dies. The server — and everything running inside it, including Claude Code — survives. When you switch back, a new client auto-reattaches. Everything is right where you left it.

Think of it like a TV and a DVR. Turning off the TV doesn’t stop the recording.

Setup

Two config files. That’s it.

In Zed’s settings (~/.config/zed/settings.json), tell the terminal to use tmux:

{
  "terminal": {
    "shell": {
      "with_arguments": {
        "program": "/bin/zsh",
        "args": [
          "-c",
          "project_path=$(pwd -P); session_name=\"zed-$(printf %s \"$project_path\" | shasum -a 256 | cut -d \" \" -f 1)\"; exec tmux -L zed-updated new-session -A -s \"$session_name\" -c \"$project_path\""
        ]
      }
    }
  }
}

The session name uses a SHA-256 digest of the full canonical project path, avoiding the ordinary collision between folders with the same basename. -L zed-updated selects a separate server; -c sets a new session’s directory, and -A attaches when that session already exists. Existing sessions on the default server remain there: this configuration does not move or duplicate their processes.

Then create ~/.tmux.conf:

# Ctrl+A as prefix (Ctrl+Space conflicts with Zed)
set -g prefix C-a
unbind C-b
bind C-a send-prefix

# Mouse support
set -g mouse on

# Better colors
set -g default-terminal "tmux-256color"

# Keep server alive when client detaches
set -g destroy-unattached off

Day-to-Day

You don’t have to do anything. Forget tmux is there.

Open a terminal → tmux session auto-created. Switch projects → tmux client dies silently, Claude Code keeps running. Switch back → auto-reattach. Sessions are lightweight and vanish on reboot.

One thing you’ll notice: when you select text in the terminal, it gets deselected the moment you release the mouse — but it’s already copied. That’s tmux. No Cmd+C needed. Select, release, paste. Once you get used to it, the old way feels slow.

You will lose a few iTerm2 conveniences, though. Drag-and-drop a file to get its path? Gone — that was an iTerm2 feature, not a terminal standard. In Zed, right-click a file in the tree and copy the path instead. Small trade-off for everything you gain.

The Second Catch: Claude Code Flickering

You set up Zed + tmux and everything feels perfect. Then you open Claude Code and the terminal starts flickering. Diffs flash green and red then vanish. The status bar blinks. The entire UI jitters like a broken monitor.

Flicker can depend on how the application, tmux and the terminal coordinate redraws. Diagnose the combination and installed versions before attributing it to one component.

Root Cause

Synchronized output (DECSET 2026) lets an application bracket a batch of screen updates so a supporting terminal or multiplexer can present them together. It can reduce visible intermediate frames during rapid redraws.

Check whether the installed tmux build includes application synchronized-output support, then reproduce the problem in that build. An older running server does not become a new server merely because its executable was upgraded on disk.

Check the Stable Build First

The maintainer recorded the synchronized-output change in tmux issue 4744 on December 17, 2025. It is included in the 3.7 release history; the official releases page lists 3.7c as of September 20, 2026. HEAD is no longer required for this feature. Inspect the package and install or upgrade the current stable build where appropriate:

brew update
brew info tmux

# If tmux is already installed on the stable track:
brew upgrade tmux
# If it is not installed, use: brew install tmux

tmux -V

tmux kill-server terminates every session and running program on the selected server. Save work and deliberately stop its jobs before using it. To preserve existing default-server sessions, leave that server running and use the separately named zed-updated server selected in the Zed configuration above. If that named server already exists, inspect it too; its name does not prove it is running the new binary.

# Inspect the named server, if it already exists:
tmux -L zed-updated list-sessions
tmux -L zed-updated display-message -p "#{version}"

# ONLY after saving work and stopping every job on this named server:
# tmux -L zed-updated kill-server

# Reopen the Zed terminal; its launcher above creates or attaches
# to the project session on the zed-updated server.
# Existing default-server sessions remain on their original server.

Reopen the terminal in Zed, confirm that it attaches to zed-updated, and verify redraw behavior in the new server. Existing default-server sessions remain available through their original clients. A synchronized-output update can help without guaranteeing that every source of flicker is gone.

If You Deliberately Track HEAD

A development build may be useful for a specific unreleased fix. Record the version or commit and test it; do not choose HEAD solely to get a feature already present in stable.

For a deliberate HEAD installation, Homebrew documents --fetch-HEAD to check the upstream repository during upgrade:

brew upgrade tmux --fetch-HEAD

To check what you're running:

tmux -V        # version of the executable on PATH
brew info tmux # installed formula/build information
tmux -L zed-updated display-message -p "#{version}" # running named server

To return from HEAD to stable, preserve the work in all running sessions, inspect the installed formula, and follow Homebrew’s current install guidance. Replacing package files does not migrate a running tmux server.

brew info tmux
# For an existing HEAD installation, after reviewing package changes:
# brew reinstall tmux

After selecting the intended stable build, repeat the server-version and rendering checks. See the Homebrew command reference for installation and HEAD options.