Zed on macOS

01 What is Zed?

Zed is a high-performance code editor built entirely in Rust, created by Nathan Sobo, Antonio Scandurra, and Max Brunsfeld — the team behind GitHub's Atom editor and Tree-sitter. Where Atom ran on Electron and struggled with performance, Zed was redesigned from scratch with one overriding principle: speed as a first-class feature.

Rather than using Electron or any web-rendering stack, Zed runs its own GPU-accelerated UI framework called GPUI, which communicates directly with the Metal graphics API on macOS. The result is a constant 120 fps rendering rate, a 0.12-second cold startup, and 2ms input-to-screen latency — figures that feel categorically different from Electron-based editors.

02 Installation

Option A — Direct Download (simplest)

Go to zed.dev/download. Download the macOS dmg, drag Zed to /Applications, and launch it from Spotlight or the Dock. Zed auto-updates.

Option B — Homebrew

$ brew install --cask zed

Setting up the CLI

Zed ships a zed CLI tool for opening files and projects from the terminal. Install it via the command palette:

⌘⇧P → zed: install CLI

After installation, use it from any terminal:

$ zed .                     # open current directory
$ zed myfile.rs             # open a file
$ zed -n ~/projects/app     # open in new window
$ zed --wait myfile.txt     # block until file is closed (for git editor)
$ zed --completions zsh     # generate shell completions

Set Zed as your git editor

$ git config --global core.editor "zed --wait"

Channels: Stable vs Preview

Zed ships two channels. Stable is updated weekly with polished features. Preview gets new features and fixes faster (roughly twice a week) but may have rougher edges. Both can be installed simultaneously. Switch in Zed Menu → Check for Updates.

03 The Interface

Key UI zones

The Welcome page

When Zed opens without a folder you see the welcome page. It offers quick actions: open a folder, clone a repository, or browse docs. Once you open a project, it disappears. Reopen it by closing all tabs in the center pane, or via the command palette → "Welcome".

Windows and Projects

Each Zed window contains one project. Multiple windows can be open simultaneously. By default, opening a new project replaces the current window's project. To always open in a new window, use zed -n ~/path or press ⌘↩ when selecting from Open Recent.

04 Projects & Files

Opening projects

$ zed .                    # open CWD as project
# Or from within Zed:
⌘O                        # open folder picker
⌘⇧P → open recent        # recent projects list

File Finder

The fastest way to open any file: press ⌘P and start typing. Zed fuzzy-matches across the entire project. Type a / to filter by directory. Press ⌘↩ to open in a new pane.

Project panel

Toggle with ⌘⇧E. Key actions in the Project Panel:

• a — create new file in selected directory
• A — create new directory
• r or F2 — rename selected item
• d or ⌫ — delete selected item
• x — cut, c — copy, v — paste file
• ⌘⌥R — reveal file in Finder
• ⌘C — copy path to clipboard

Project trust

When you open a new project, Zed asks whether to trust it. Trusted projects automatically sync language/MCP servers and project settings. When Zed prompts, you can trust any parent directory to avoid repeated prompts for subdirectory projects.

05 Essential Navigation Shortcuts

06 Editing Commands

07 Panels, Panes & Layout

Dock toggles

Pane splitting and navigation

Theme and appearance

08 Multi-cursor Editing

Zed's multi-cursor system is one of its most powerful editing features. All cursors edit simultaneously.

09 Code Navigation

Breadcrumbs and Outline

The breadcrumb bar above each editor shows the current file's path and symbol hierarchy. Click any breadcrumb segment to jump to that symbol. The Outline panel (⌘⇧B) shows the current file's symbols as a tree — click to jump.

Symbol search

LSP-powered navigation

Folding

10 Built-in Terminal

Zed's terminal is a full-featured terminal emulator embedded in the bottom dock. It opens in the project's root directory by default and inherits your shell's environment.

Terminal settings

{
  "terminal": {
    "shell":            "/bin/zsh",        // or "system" for default
    "font_family":     "JetBrains Mono",
    "font_size":       14,
    "cursor_shape":    "bar",             // bar | block | underline | hollow
    "copy_on_select":  true,
    "working_directory": "current_project_directory",
    "env": {
      "EDITOR": "zed --wait"
    }
  }
}

11 Agent Panel

The Agent Panel is Zed's built-in AI chat interface. It supports multi-turn conversation, multi-file editing, parallel agent threads, and any LLM provider you configure. Open it with ⌘⇧A.

Agent Panel shortcuts

Supported model providers

Zed's agent works with all major providers. Configure via Agent Panel → Agent Settings → LLM Providers:

• Anthropic — Claude Opus, Sonnet, Haiku (BYOK or hosted)
• OpenAI — GPT-4o, GPT-5.4, o1, o3, o4 (BYOK)
• Google — Gemini 3 Flash, Gemini Pro (BYOK)
• Ollama — any local model at http://localhost:11434
• LM Studio — local OpenAI-compatible endpoint
• llama.cpp — direct llama.cpp server (Preview, July 2026)
• OpenRouter — any model via OpenRouter
• GitHub Copilot — via the Copilot provider
• Zed hosted — credits-based access, no API key needed

Agent modes

Cycle through modes with ⇧Tab in the Agent Panel message editor:

• Write — Agent edits files directly
• Ask — Agent only answers questions, no file edits
• Minimal — Lightweight chat without file-editing tools

Context: @ mentions

In the Agent Panel message editor, type @ to add context:

• @file — attach a specific file
• @selection — add the current editor selection
• @directory — include an entire directory tree
• @symbol — add a function or class by name
• @diagnostics — include current error/warning list
• @terminal — include the last terminal output
• @fetch — fetch a URL and add its content

Parallel agents

Zed supports running multiple agent threads simultaneously. Create additional threads with ⌘N in the Agent Panel. Each thread has independent context and can edit different files concurrently. Monitor all threads in the Agent Panel thread list.

Feature-specific model settings

{
  "agent": {
    // Main agent model
    "default_model": {
      "provider": "anthropic",
      "model": "claude-sonnet-4-5"
    },
    // Git commit messages get a cheaper model
    "commit_message_model": {
      "provider": "anthropic",
      "model": "claude-haiku-4-5"
    },
    // Conventional commit format instruction
    "commit_message_instructions":
      "Use Conventional Commits: <type>(<scope>): <description>",
    // Temperature per provider+model pair
    "model_parameters": [
      {
        "provider": "anthropic",
        "model": "claude-sonnet-4-5",
        "temperature": 0.2
      }
    ]
  }
}

12 Edit Predictions — Zeta2

Edit Predictions is Zed's inline autocomplete feature, similar to GitHub Copilot's suggestions. As you type, the model predicts your next edit and shows it as a grey overlay. Press Tab to accept.

The default model is Zeta2 — an open-weight model developed by the Zed team, specifically trained on code-editing tasks (predicting the next change given cursor context). It's trained with LSP-derived type information and symbol definitions. Zeta2 is also available on Hugging Face for self-hosting or fine-tuning.

Alternative prediction providers

You can swap Zeta2 for another provider in settings:

{
  "edit_predictions": {
    "mode": "eager",            // eager | on_request
    "provider": "zeta"           // zeta | copilot | none
  }
}

13 Inline Assistant

The Inline Assistant brings AI editing directly into the code buffer. Select code, invoke the assistant, type a transformation instruction, and the agent rewrites the selection in place — without opening the Agent Panel.

Common inline assistant patterns

# Select a function, then ⌘↩ and type:
"Add proper error handling with Result<T,E>"
"Write unit tests for this function"
"Add JSDoc comments"
"Refactor to use async/await"
"Translate this to TypeScript"
"Optimize for performance"
"Explain what this does"

14 ACP — Agent Client Protocol

The Agent Client Protocol (ACP) is an open, Apache-licensed standard co-developed by Zed and JetBrains in January 2026. It lets any ACP-compatible AI agent integrate with any ACP-supporting editor through a single interface — eliminating the custom-integration sprawl that previously made every agent–editor combination unique.

Via ACP, external CLI agents (Claude Code, Codex, OpenCode, Cursor) run in a panel inside Zed's UI with full access to multi-file editing, codebase context, and review tools. Privacy-first: external agents communicate directly with the local editor process — Zed's servers are never involved.

Configuring external ACP agents

{
  "agent": {
    "agent_servers": [
      {
        "id":      "claude-code",
        "label":  "Claude Code",
        "command": "claude",
        "args":  ["--acp"]
      },
      {
        "id":      "codex",
        "label":  "Codex",
        "command": "codex",
        "args":  ["--acp"]
      }
    ]
  }
}

After configuring, open the Agent Panel, click the + button, and select your ACP agent from the list. The agent runs in a thread with Zed-native edit review UI.

15 MCP Servers

Zed integrates with the Model Context Protocol (MCP) to give the AI agent access to external data sources and tools — databases, APIs, file systems, documentation, GitHub, etc. MCP provides context to models; ACP provides agent capabilities to editors. They work together.

Configuring MCP servers

Go to Agent Panel → Agent Settings → MCP Servers, or configure in settings.json:

{
  "context_servers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem",
               "/Users/stephen/projects"]
    },
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": { "DATABASE_URL": "postgresql://..." }
    }
  }
}

Once MCP servers are running, the agent can use their tools in any thread. In the message editor, @ mentions will include MCP-provided context sources.

16 Git Integration

Zed has comprehensive native git support — no extension required. Open the Git Panel with ⌃⇧G.

Git Panel operations

AI commit message generation

With staged changes, click the ✨ sparkle button in the commit message editor or invoke via the command palette. The model analyses your diff and generates a commit message. Customize the format with:

{
  "agent": {
    "commit_message_instructions":
      "Use Conventional Commits format. Scope optional. Body if needed.",
    "commit_message_model": {
      "provider": "anthropic",
      "model": "claude-haiku-4-5"
    }
  }
}

17 Debugger

Zed includes a full graphical debugger based on the Debug Adapter Protocol (DAP) — the same protocol used by VS Code. Supports Node.js, Python, Rust (via CodeLLDB), Go (via Delve), and any language with a DAP adapter. Open the Debug Panel with ⌘⇧D.

Launch configuration

Create a .zed/debug.json in your project to define debug configurations:

[
  {
    "label":    "Debug Node server",
    "adapter":  "js-debug",
    "request":  "launch",
    "program":  "${workspaceFolder}/src/index.js"
  },
  {
    "label":    "Debug Python tests",
    "adapter":  "debugpy",
    "request":  "launch",
    "module":   "pytest",
    "args":    ["tests/"]
  }
]

18 Real-time Collaboration

Real-time collaboration is a first-class feature in Zed — not an extension. It uses CRDTs (Conflict-free Replicated Data Types) for conflict-free simultaneous editing, the same technology used by collaborative document editors.

Starting a collaboration session

1. Sign in to your Zed account (free) via the title bar or ⌘⇧P → "Sign in".

2. Click the collaboration icon in the title bar, or use ⌘⇧P → "Collaboration: Share Project".

3. Copy the share URL and send it to your collaborator. They open the URL and join your session in their Zed instance — no setup required.

Collaboration features

• Shared cursors: See all collaborators' cursors and selections in real-time
• Follow mode: Click a collaborator's avatar to follow their viewport
• Voice chat: Built-in audio call — no external app
• Screen sharing: Share your screen within the session
• Text chat: Persistent chat attached to the session
• Shared terminal: Collaborators can see and interact with the terminal
• Conflict-free editing: CRDTs ensure edits from multiple users merge gracefully
• Scrollbar indicators: Small marks show where remote cursors are in long files

Channels

Zed Channels (free) provide persistent project collaboration rooms. Team members can open channels, join active sessions, and access shared notes. Enable via the Channels panel in the right dock.

19 Remote Development

Zed's remote development feature runs the UI locally while the codebase, language servers, terminal, and agent run on a remote SSH host. This means full local GPU-speed UI responsiveness even for remote projects — the network only carries GPUI rendering commands, not full Electron re-renders.

Connecting to a remote host

# From the command palette:
⌘⇧P → remote: open SSH project

# Or via CLI:
$ zed ssh://user@hostname/path/to/project

SSH configuration

{
  "ssh_connections": [
    {
      "host":     "dev.example.com",
      "username": "stephen",
      "port":     22,
      "projects": [
        { "path": "/home/stephen/myproject" }
      ]
    }
  ]
}

Remote development capabilities

• Language server runs on the remote host — no local language install needed
• Terminal opens on the remote machine
• AI Agent features work in the remote session
• Dev Containers (Docker) supported for containerised development
• UI remains locally rendered — stays fast regardless of network latency

20 settings.json — Complete Reference

Open settings with ⌘⌥, (JSON) or ⌘, (GUI editor). On macOS, the file lives at:

~/.config/zed/settings.json

A well-annotated macOS settings.json

{
  // ── UI & APPEARANCE ─────────────────────────────────
  "theme": "One Dark",
  "icon_theme": "Zed (Default)",

  // ── FONTS ────────────────────────────────────────────
  "buffer_font_family": "JetBrains Mono",
  "buffer_font_size": 14,
  "buffer_font_weight": 400,
  "buffer_line_height": "comfortable",  // standard | comfortable | custom
  "ui_font_family": "System UI",
  "ui_font_size": 14,

  // ── EDITOR BEHAVIOUR ─────────────────────────────────
  "tab_size": 2,
  "hard_tabs": false,
  "soft_wrap": "none",              // none | editor_width | preferred_line_length
  "preferred_line_length": 80,
  "show_whitespaces": "selection",    // all | selection | none
  "relative_line_numbers": false,
  "cursor_blink": false,
  "cursor_shape": "bar",             // bar | block | underline | hollow
  "format_on_save": "off",           // on | off | language_default
  "ensure_final_newline_on_save": true,
  "remove_trailing_whitespace_on_save": true,
  "inlay_hints": { "enabled": true },
  "show_copilot_suggestions": true,

  // ── SCROLLBAR ─────────────────────────────────────────
  "scrollbar": {
    "show": "auto",                 // always | never | auto
    "git_diff": true,
    "search_results": true,
    "diagnostics": true
  },

  // ── GUTTER ────────────────────────────────────────────
  "gutter": {
    "line_numbers": true,
    "code_actions": true,
    "runnables": true,
    "folds": true
  },

  // ── GIT ───────────────────────────────────────────────
  "git": {
    "git_gutter": "tracked_files",
    "inline_blame": {
      "enabled": true,
      "delay_ms": 600,
      "location": "inline"           // inline | status_bar
    }
  },

  // ── MODAL KEYMAPS ─────────────────────────────────────
  "vim_mode": false,                // set true to enable Vim
  "helix_mode": false,              // set true to enable Helix

  // ── EDIT PREDICTIONS ──────────────────────────────────
  "edit_predictions": {
    "mode": "eager",               // eager | on_request
    "provider": "zeta"             // zeta | copilot | none
  },

  // ── TERMINAL ──────────────────────────────────────────
  "terminal": {
    "font_family": "JetBrains Mono",
    "font_size": 13,
    "line_height": "comfortable",
    "shell": "system",
    "working_directory": "current_project_directory",
    "copy_on_select": false,
    "env": { "EDITOR": "zed --wait" }
  },

  // ── macOS WINDOW ──────────────────────────────────────
  "window_decorations": "client",   // server | client | transparent
  "macos_window_blur": false,
  "window_tabbing": "manual",      // macOS native window tabs
  "when_closing_with_no_tabs": "close_window",

  // ── LANGUAGE-SPECIFIC OVERRIDES ───────────────────────
  "languages": {
    "Python": {
      "tab_size": 4,
      "format_on_save": "on"
    },
    "Go": {
      "hard_tabs": true,
      "format_on_save": "on"
    },
    "Markdown": {
      "soft_wrap": "preferred_line_length",
      "preferred_line_length": 100
    }
  },

  // ── LSP ───────────────────────────────────────────────
  "lsp": {
    "rust-analyzer": {
      "initialization_options": {
        "checkOnSave": { "command": "clippy" },
        "inlayHints": { "bindingModeHints": { "enable": true } }
      }
    }
  }
}

Per-project settings

Create a .zed/settings.json in any project root to override settings for that project. Zed merges it with your global settings — project settings take precedence. Examples of what to put here: language server settings, formatter choice, per-language tab size, and agent/MCP configuration.

21 keymap.json — Custom Keybindings

Open with ⌘K ⌘S or ⌘⌥,. Located at ~/.config/zed/keymap.json on macOS. The file is a JSON array of objects with bindings and optional context expressions.

[
  // Global binding (no context = always active)
  {
    "bindings": {
      "cmd-;": "editor::ToggleComments"
    }
  },

  // Context-specific: only in editor, not Vim insert mode
  {
    "context": "Editor && !VimWaiting && !(vim_mode == insert)",
    "bindings": {
      "cmd-d":    "editor::SelectNextOccurrence",
      "cmd-k d":  "editor::DeleteLine"
    }
  },

  // Key sequences (like Emacs C-x C-f)
  {
    "bindings": {
      "cmd-k cmd-s": "zed::OpenKeymap"    // ⌘K then ⌘S
    }
  },

  // Vim insert mode: jk as Escape
  {
    "context": "Editor && vim_mode == insert",
    "bindings": {
      "j k": ["workspace::SendKeystrokes", "escape"]
    }
  },

  // Actions with arguments
  {
    "bindings": {
      "cmd-1": ["workspace::ActivatePane", 0],
      "cmd-2": ["workspace::ActivatePane", 1],
      "cmd-3": ["workspace::ActivatePane", 2]
    }
  }
]

Keybinding contexts

22 Vim Mode & Helix Mode

Enabling Vim mode

// In settings.json:
{ "vim_mode": true }
// Or via command palette: "vim: toggle vim mode"

Zed's Vim mode provides full modal editing including motions, text objects, operators, visual modes, and macros. It integrates with Zed's multi-cursor and selection systems.

Vim motions and operators

Zed-specific Vim extensions

• g l — select next occurrence (like Ctrl+D in VS Code)
• g a — select all occurrences
• g s — split selection into lines
• g h — hover documentation
• g r — find references
• g d — go to definition
• ] d / [ d — next/previous diagnostic
• ] g / [ g — next/previous git hunk

Helix mode

// In settings.json:
{ "helix_mode": true }

Helix mode is built on top of Vim mode and follows the Helix editor's "selection-first" approach: you select before you act. Key differences from Vim:

• Motions extend selections rather than moving the cursor
• Operators work on the current selection
• m matches surrounding brackets/quotes rather than setting marks
• Alt-b / Alt-e — move to start/end of larger syntax node
• * — set current selection for search

23 Themes & Fonts

Switching themes

Press ⌘K ⌘T to open the theme selector — live preview as you scroll. You can also set it directly in settings.json:

{
  "theme": {
    "mode": "system",         // system | light | dark
    "light": "One Light",
    "dark": "One Dark"
  }
}

Built-in themes (selection)

• One Dark / One Light
• Ayu Dark / Ayu Light / Ayu Mirage
• Gruvbox Dark / Gruvbox Light
• Rosé Pine / Rosé Pine Moon / Rosé Pine Dawn
• Catppuccin Mocha / Latte / Frappé / Macchiato
• Tokyo Night / Tokyo Night Storm / Tokyo Night Light
• Solarized Dark / Light
• Nord

Font configuration

{
  "buffer_font_family": "JetBrains Mono",
  "buffer_font_size": 14,
  "buffer_font_features": {
    // Control OpenType features: calt = contextual alternates (ligatures)
    "calt": false           // set true to enable font ligatures
  },
  "buffer_font_fallbacks": ["Apple Color Emoji"],
  "buffer_line_height": { "custom": 1.7 }
}

Writing a custom theme extension

Create a folder in ~/.config/zed/extensions/my-theme/:

// extension.toml
id = "my-theme"
name = "My Theme"
version = "0.1.0"
themes = ["themes/my-theme.json"]

// themes/my-theme.json
{
  "name": "My Theme",
  "author": "Stephen",
  "themes": [{
    "name": "My Theme Dark",
    "appearance": "dark",
    "style": {
      "background": "#1a1825",
      "editor.foreground": "#e2d9f3",
      "syntax": {
        "keyword": { "color": "#ff7b72", "font_style": "italic" },
        "string":  { "color": "#a5d6ff" },
        "comment": { "color": "#6e7681", "font_style": "italic" },
        "function":{ "color": "#79c0ff" }
      }
    }
  }]
}

24 Extensions

Open the Extensions panel with ⌘⇧X. Zed extensions can add languages, themes, icon themes, snippets, and MCP server bundles. They're installed via the Extensions panel or by adding to settings.json.

Auto-installing extensions

{
  "auto_install_extensions": {
    "html":            true,
    "dockerfile":      true,
    "docker-compose":  false,   // never install this one
    "toml":            true,
    "graphql":         true
  }
}

Popular extensions (June 2026)

Developing extensions

Zed extensions are written in WASM (compiled from Rust). A language extension provides grammar, language server configuration, syntax highlighting queries, and formatting configuration. Use the zed: rebuild dev extension command during development to hot-reload changes.

25 Pricing & AI Plans