# Zed — Administrator & Developer Guide

> Operational reference for building, packaging, configuring, operating, and extending Zed — the GPU-accelerated, multiplayer code editor written in Rust.

This guide is for administrators, packagers, platform engineers, extension authors, and contributors. For end-user workflows, key bindings, and daily usage, see the **User Guide**.

Zed is a Cargo workspace with ~200 crates. It ships as a single `zed` binary plus an auxiliary `cli` launcher and a separate `collab` collaboration server. The codebase targets macOS (Metal), Linux (Vulkan/OpenGL via Wayland or X11), and Windows (DirectX/WGPU), all rendered through a custom GPU UI framework called GPUI.

---

## 1. Architecture Overview

### 1.1 System Topology

```
+------------------- Zed Desktop Process -----------------------+
|                                                               |
|   crates/zed (main entry — crates/zed/src/main.rs)            |
|     |                                                         |
|     v                                                         |
|   crates/workspace     <--- Window/pane/panel management      |
|     |           \                                             |
|     |            +--> crates/editor                           |
|     |            |       |                                    |
|     |            |       v                                    |
|     |            |    crates/language, language_core, lsp     |
|     |            |       |                                    |
|     |            |       v                                    |
|     |            |    crates/project (LSP/DAP/Git store,      |
|     |            |       worktree, task runner)               |
|     |            |                                             |
|     |            +--> crates/terminal + terminal_view         |
|     |            +--> crates/agent_ui  --> crates/agent       |
|     |            +--> crates/debugger_ui --> crates/dap*      |
|     |            +--> crates/git_ui     --> crates/git        |
|     |            +--> crates/collab_ui  --> crates/rpc,       |
|     |                                       channel, call     |
|     |                                                         |
|     v                                                         |
|   crates/gpui (UI framework)                                  |
|     |    \----- crates/gpui_{macos,windows,linux,web,wgpu}    |
|     v                                                         |
|   GPU (Metal / DirectX / WGPU / OpenGL / WASM)                |
+---------------------------------------------------------------+
          |                           |
          | SSH remote protocol       | RPC (protobuf over TLS)
          v                           v
   remote_server (on dev box)    collab.zed.dev (crates/collab)
                                      |   \---> LiveKit (SFU)
                                      v
                                  Postgres
```

### 1.2 Binaries in the Workspace

| Binary | Crate | Purpose |
|--------|-------|---------|
| `zed` | `crates/zed` | Main editor application |
| `cli` | `crates/cli` | Launcher that forwards to the app; supports CLI surface |
| `collab` | `crates/collab` | Multiplayer collaboration server |
| `remote_server` | `crates/remote_server` | Headless backend for SSH remote projects |
| `auto_update_helper` | `crates/auto_update_helper` | Helper process that applies updates |
| `crash_handler` | `crates/crashes` | Spawned by Zed to capture minidumps |
| `edit_prediction_cli` | `crates/edit_prediction_cli` | Offline evaluation and dataset tooling for the zeta model |
| `extension_cli` | `crates/extension_cli` | Package, publish, and test Zed extensions |
| `eval_cli` | `crates/eval_cli` | Evaluate agents against datasets |
| `schema_generator` | `crates/schema_generator` | Emit JSON Schemas for `settings.json`, `tasks.json`, etc. |
| `theme_importer` | `crates/theme_importer` | Import VSCode themes into Zed format |
| `docs_preprocessor` | `crates/docs_preprocessor` | mdBook preprocessor for the zed.dev docs |
| `xtask` | `tooling/xtask` | Repo automation (CI helpers, workflow generation, diagnostics) |

> [!NOTE]
> The `cli` binary is a separate process from the main `zed` binary. It communicates via `ipc-channel` to launch or connect to a running Zed instance. On macOS, the CLI is installed as a symlink; on Linux and Windows, it ships alongside the main binary.

### 1.3 Core Crate Inventory

The ~200 workspace crates break down into several functional layers:

#### UI Framework Layer

| Crate | Purpose |
|-------|---------|
| `gpui` | Custom GPU-accelerated UI framework: window management, element tree, layout, input, fonts, drawing primitives |
| `gpui_macos` | macOS platform backend (Metal renderer) |
| `gpui_linux` | Linux platform backend (Wayland + X11) |
| `gpui_windows` | Windows platform backend (DirectX) |
| `gpui_web` | Experimental web/WASM platform target |
| `gpui_wgpu` | GPU rendering layer via wgpu |
| `gpui_macros` | Procedural macros for GPUI |
| `gpui_tokio` | Tokio integration shim for GPUI's async runtime |
| `gpui_platform` | Platform abstraction traits |
| `gpui_util` | GPUI utility functions |
| `gpui_shared_string` | Shared string type for GPUI |
| `ui` | Reusable UI components (buttons, lists, pickers, labels, icons) |
| `ui_input` | Input field components |
| `ui_prompt` | Prompt/dialog components |
| `ui_macros` | Macros for UI components |

#### Text Engine Layer

| Crate | Purpose |
|-------|---------|
| `rope` | Rope data structure for efficient text storage |
| `sum_tree` | B-tree implementation for ordered collections |
| `text` | Text buffer core (CRDT-based) |
| `multi_buffer` | Multi-buffer editing (excerpts from multiple files) |
| `buffer_diff` | Diff computation between buffer states |
| `streaming_diff` | Streaming diff for AI-generated content |

#### Editor Layer

| Crate | Purpose |
|-------|---------|
| `editor` | The `Editor` type — backs every text surface (code editor, terminal input, message composers). Handles display map, scroll, diagnostics, inlay hints, completions. (~1.4M chars source) |
| `workspace` | Top-level window state: panes, tabs, docks, status bar, session persistence |
| `sidebar` | Sidebar panel system (~590K chars) |
| `project` | Project-level state: worktrees, LSP store, DAP store, Git store, search, tasks |
| `project_panel` | File tree panel |
| `outline_panel` | Code outline panel |
| `vim` | Vim modal editing layer |
| `search` | Buffer and project search |
| `diagnostics` | Diagnostics panel |

#### Language & Intelligence Layer

| Crate | Purpose |
|-------|---------|
| `language` | Language/grammar support (~689K chars) |
| `language_core` | Core language primitives |
| `lsp` | Language Server Protocol client (JSON-RPC transport, capability negotiation) |
| `grammars` | Tree-sitter grammar management |
| `languages` | Built-in language configurations |
| `language_extension` | Language support via extensions |
| `language_model` | AI model abstraction trait |
| `language_model_core` | Core model types |
| `language_models` | Provider registry and implementations |
| `language_models_cloud` | Cloud-hosted model integration |

#### AI & Agent Layer

| Crate | Purpose |
|-------|---------|
| `agent` | Agent runtime: turns, tool-call loop, MCP integration |
| `agent_ui` | Agent panel UI (~1.9M chars) |
| `agent_settings` | Agent configuration schema |
| `agent_servers` | Agent server management |
| `edit_prediction` | Inline AI edit predictions |
| `edit_prediction_context` | Context gathering for predictions |
| `edit_prediction_metrics` | Prediction quality metrics |
| `edit_prediction_ui` | Prediction UI overlay |
| `zeta_prompt` | Edit prediction prompt templates |

#### AI Provider Crates

| Crate | Provider |
|-------|----------|
| `anthropic` | Anthropic (Claude) |
| `open_ai` | OpenAI |
| `ollama` | Ollama (local models) |
| `lmstudio` | LM Studio (local models) |
| `mistral` | Mistral AI |
| `deepseek` | DeepSeek |
| `google_ai` | Google AI (Gemini) |
| `open_router` | OpenRouter (aggregator) |
| `bedrock` | AWS Bedrock |
| `copilot` | GitHub Copilot (completions) |
| `copilot_chat` | GitHub Copilot Chat |
| `x_ai` | xAI (Grok) |
| `codestral` | Codestral |
| `vercel` | Vercel AI |
| `cloud_llm_client` | Zed's cloud LLM proxy |

#### Collaboration Layer

| Crate | Purpose |
|-------|---------|
| `collab` | Collaboration server binary |
| `collab_ui` | Collaboration UI panels |
| `rpc` | Protobuf wire format for collab and remote traffic |
| `proto` | Protobuf definitions (generated via `prost`) |
| `client` | Cloud client: authentication, presence, keychain, telemetry |
| `channel` | Channel management (text + voice) |
| `call` | Audio/video call management |
| `livekit_client` | LiveKit WebRTC client |
| `livekit_api` | LiveKit API bindings |

#### Debug & Dev Tools Layer

| Crate | Purpose |
|-------|---------|
| `dap` | Debug Adapter Protocol transport |
| `dap_adapters` | Per-adapter configurations (CodeLLDB, debugpy, etc.) |
| `debugger_ui` | Debugger UI panels |
| `debugger_tools` | Debugger utilities |
| `debug_adapter_extension` | DAP support via extensions |
| `repl` | Jupyter REPL integration |
| `terminal` | Terminal emulator (~241K chars) |
| `terminal_view` | Terminal UI panel |

#### Extension System Layer

| Crate | Purpose |
|-------|---------|
| `extension` | Extension manifests and metadata |
| `extension_host` | WASM extension runtime host |
| `extension_api` | Extension API (WIT-based interface) |
| `extension_cli` | Extension packaging and publishing CLI |
| `extensions_ui` | Extension management UI |

#### Infrastructure Layer

| Crate | Purpose |
|-------|---------|
| `db` | SQLite database (via custom `sqlez` crate) |
| `sqlez` | Custom SQLite wrapper (WAL mode) |
| `sqlez_macros` | Procedural macros for sqlez |
| `migrator` | Database schema migrations |
| `fs` | Filesystem abstraction |
| `worktree` | File watching and tree management |
| `settings` | Settings framework (cascading resolution) |
| `settings_macros` | Settings derive macros |
| `theme` | Theming system |
| `theme_settings` | Theme-related settings |
| `paths` | Platform-specific path resolution |
| `git` | Git integration (libgit2 + CLI fallback) |
| `git_ui` | Git panel UI (~847K chars) |
| `git_graph` | Git graph visualization |
| `git_hosting_providers` | GitHub, GitLab, Bitbucket, etc. |
| `auto_update` | Automatic update system |
| `release_channel` | Release channel management (Stable, Preview, Nightly, Dev) |
| `telemetry` | Telemetry collection |
| `telemetry_events` | Telemetry event definitions |
| `crashes` | Crash reporting and minidump capture |

### 1.4 Technology Stack

| Component | Technology |
|-----------|------------|
| Language | Rust (edition 2024) |
| UI Framework | GPUI (custom, GPU-accelerated via wgpu) |
| Rendering | wgpu (cross-platform GPU abstraction) |
| Database | SQLite (WAL mode, via custom `sqlez` crate) |
| Networking | reqwest, tokio |
| IPC | ipc-channel (CLI to GUI communication) |
| Text Storage | Custom rope + sum_tree data structures |
| Parsing | tree-sitter |
| Protocol Buffers | prost (protobuf code generation) |
| Audio | Custom pipeline with denoise models |
| Collaboration | LiveKit (WebRTC SFU) |
| Extensions | WASM (WIT-based API via wasmtime) |
| Allocator | mimalloc (release builds) |
| Build System | Cargo workspace + cargo-xtask |
| Async Runtime | Custom smol-based runtime with Tokio shims |
| Thread Pool | rayon (half available parallelism, 10MB stack) |

### 1.5 Event and Data Flow

1. The user triggers an **action** via keybinding, menu, command palette, or IPC from the CLI.
2. GPUI dispatches the action through the focused **element tree** and its chain of contexts.
3. Workspace dispatches to the relevant handler: Pane, Editor, or a panel (terminal, agent, git, debugger).
4. For semantic operations, `project` forwards requests to the relevant subsystem:
   - **LSP**: JSON-RPC to language server process
   - **DAP**: JSON over stdio to debug adapter process
   - **Git**: `libgit2` bindings with CLI fallback
   - **Remote**: Multiplexed SSH connection to `remote_server`
5. Results update `Buffer` / `MultiBuffer` / `Project` models, which emit events.
6. GPUI re-renders only the subtree affected by the change.

### 1.6 Concurrency Model

- **`BackgroundExecutor`** — thread pool for CPU-bound work (parsing, LSP requests, git scans). Uses rayon with half available parallelism and 10MB thread stacks.
- **`ForegroundExecutor`** — single-threaded, tied to the UI thread. Drives GPUI's `Futures`/`Tasks`.
- **`Entity<T>`** — GPUI's actor-lite primitive (`cx.new(|cx| ...)`). Entities mutate on the foreground executor only; cross-thread communication goes through channels or `spawn`-with-`cx.update`.

Everything is `async` under the hood. Zed uses its own `smol`-based runtime with Tokio shims (`gpui_tokio`) where needed for libraries that require Tokio.

---

## 2. System Requirements

### 2.1 Runtime Requirements (Using Zed)

| Platform | Minimum Version | Notes |
|----------|----------------|-------|
| macOS | 10.15 (Catalina)+ | Metal renderer. Apple Silicon and Intel supported |
| Linux | glibc >= 2.29, kernel >= 5.10 | Wayland preferred; X11 supported. Requires Vulkan or OpenGL 3.3 |
| Windows | 10 1809+ | DirectX 11 + DXGI. ARM64 and x64 |
| FreeBSD | 13+ | Community-maintained; same graphics requirements as Linux |

| Resource | Recommendation |
|----------|---------------|
| RAM | 4 GB minimum, 8 GB recommended, 16 GB for large projects with LSP |
| Disk | ~300 MB for the app and bundled fonts; language servers add more |
| GPU | Any GPU supporting Metal (macOS), Vulkan/OpenGL 3.3 (Linux), or DirectX 11 (Windows) |

### 2.2 Build Requirements (Compiling Zed)

| Item | Version / Detail |
|------|-----------------|
| Rust | Pinned toolchain in `rust-toolchain.toml` (recent stable, edition 2024) |
| Cargo | Ships with Rust |
| cmake | Required for native dependency builds |
| pkg-config | Linux/macOS dependency resolution |
| protoc | Protocol Buffers compiler |

**Platform-specific build dependencies:**

| Platform | Packages |
|----------|----------|
| Linux | `libasound2-dev` or `libpipewire-0.3-dev`, `libssl-dev`, `libxkbcommon-dev`, `libfontconfig1-dev`, `libwayland-dev`, `libvulkan-dev` (see `script/linux` for the full list) |
| macOS | Xcode Command Line Tools, Homebrew (`cmake`) |
| Windows | Visual Studio 2022 Build Tools with C++ desktop workload and Windows SDK |

### 2.3 Collab Server Requirements

| Component | Version |
|-----------|---------|
| Rust | Same as client (workspace pinned) |
| PostgreSQL | 14+ |
| LiveKit | 1.6+ (SFU mode) |
| OS | Linux recommended; Kubernetes-friendly (Helm-style manifests in `crates/collab/k8s/environments`) |

> [!IMPORTANT]
> The collab server is a separate binary (`crates/collab/src/main.rs`) with its own database and LiveKit dependencies. It is NOT required for local-only Zed usage. Self-hosting collab requires PostgreSQL and a LiveKit instance; see `compose.yml` and `livekit.yaml` in the repository root.

---

## 3. Configuration Reference

### 3.1 Configuration System Architecture

Zed uses a cascading settings system with three levels of precedence:

```
Lowest priority                              Highest priority
     |                                            |
     v                                            v
  Default settings  →  User settings  →  Project settings
  (assets/settings/     (~/.config/zed/     (.zed/settings.json)
   default.json)         settings.json)
```

All settings files use **JSONC** (JSON with comments). The schema is generated by `crates/schema_generator` and the full defaults live in `assets/settings/default.json`.

Keymaps follow a similar cascade:

```
Default keymaps  →  Base keymap selection  →  User keymap
(assets/keymaps/)    (vim, helix, etc.)       (keymap.json)
```

### 3.2 Settings File Locations

| Platform | User Settings | User Keymap |
|----------|--------------|-------------|
| macOS | `~/Library/Application Support/Zed/settings.json` | `~/Library/Application Support/Zed/keymap.json` |
| Linux | `$XDG_CONFIG_HOME/zed/settings.json` (typically `~/.config/zed/settings.json`) | `$XDG_CONFIG_HOME/zed/keymap.json` |
| Windows | `%APPDATA%\Zed\settings.json` | `%APPDATA%\Zed\keymap.json` |

Project-local settings: `.zed/settings.json` in the project root.

### 3.3 Data Directory Locations

| Platform | Data Directory |
|----------|---------------|
| macOS | `~/Library/Application Support/Zed/` |
| Linux | `$XDG_DATA_HOME/zed/` (typically `~/.local/share/zed/`) |
| Windows | `%LOCALAPPDATA%\Zed\` |

Contents: logs, extensions, languages, themes, database, crash reports.

> [!IMPORTANT]
> Settings use JSONC format (JSON with comments and trailing commas). Standard JSON parsers will reject these files. Use the `schema_generator` binary to produce JSON Schema files for editor validation.

### 3.4 Editor Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `buffer_font_family` | string | `"Zed Plex Mono"` | Primary editor font |
| `buffer_font_size` | number | `16` | Editor font size in pixels |
| `buffer_font_weight` | number | `400` | Editor font weight |
| `buffer_line_height` | string/object | `"comfortable"` | Line height: `"comfortable"`, `"standard"`, or `{"custom": N}` |
| `cursor_blink` | boolean | `true` | Whether the cursor blinks |
| `cursor_shape` | string | `"bar"` | Cursor shape: `"bar"`, `"block"`, `"underline"`, `"hollow"` |
| `hover_popover_enabled` | boolean | `true` | Show hover information popover |
| `show_completions_on_input` | boolean | `true` | Auto-show completions while typing |
| `show_completion_documentation` | boolean | `true` | Show documentation in completion popup |
| `use_autoclose` | boolean | `true` | Auto-close brackets and quotes |
| `use_auto_surround` | boolean | `true` | Auto-surround selected text with brackets |
| `always_treat_brackets_as_autoclosed` | boolean | `false` | Skip over closing brackets even when not auto-inserted |
| `show_inline_completions` | boolean | `true` | Show inline/ghost text completions |
| `tab_bar.show` | boolean | `true` | Show the tab bar |
| `tab_bar.show_nav_history_buttons` | boolean | `true` | Show back/forward buttons |
| `tabs.close_position` | string | `"right"` | Position of the close button on tabs |
| `tabs.file_icons` | boolean | `false` | Show file type icons in tabs |
| `tabs.git_status` | boolean | `false` | Show git status in tabs |
| `gutter.line_numbers` | boolean | `true` | Show line numbers |
| `gutter.code_actions` | boolean | `true` | Show code action indicators |
| `gutter.runnables` | boolean | `true` | Show runnable indicators |
| `gutter.folds` | boolean | `true` | Show fold indicators |
| `indent_guides.enabled` | boolean | `true` | Show indent guides |
| `indent_guides.coloring` | string | `"fixed"` | Indent guide coloring mode |
| `scrollbar.show` | string | `"auto"` | Scrollbar visibility: `"auto"`, `"system"`, `"always"`, `"never"` |
| `scrollbar.cursors` | boolean | `true` | Show cursor positions in scrollbar |
| `scrollbar.git_diff` | boolean | `true` | Show git diff markers in scrollbar |
| `scrollbar.search_results` | boolean | `true` | Show search results in scrollbar |
| `scrollbar.diagnostics` | boolean | `true` | Show diagnostic markers in scrollbar |
| `scroll_beyond_last_line` | string | `"one_page"` | How far past the last line you can scroll |
| `scroll_sensitivity` | number | `1.0` | Scroll speed multiplier |
| `relative_line_numbers` | boolean | `false` | Use relative line numbers |
| `seed_search_query_from_cursor` | string | `"always"` | Seed search with word under cursor: `"always"`, `"selection"`, `"never"` |
| `multi_cursor_modifier` | string | `"alt"` | Modifier for adding cursors: `"alt"` or `"cmd_or_ctrl"` |
| `redact_private_values` | boolean | `false` | Redact values in .env files |
| `expand_excerpt_lines` | number | `3` | Lines of context when expanding excerpts |
| `middle_click_paste` | boolean | `true` | Paste primary selection on middle click (Linux) |

### 3.5 Formatting & Language Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `formatter` | string/object | `"auto"` | Formatter: `"auto"`, `"language_server"`, `"prettier"`, `"external"` |
| `format_on_save` | string | `"on"` | Format on save: `"on"`, `"off"` |
| `tab_size` | number | `4` | Tab width in spaces |
| `hard_tabs` | boolean | `false` | Use hard tabs instead of spaces |
| `soft_wrap` | string | `"none"` | Soft wrap: `"none"`, `"editor_width"`, `"preferred_line_length"` |
| `preferred_line_length` | number | `80` | Target line length for wrapping and rulers |
| `remove_trailing_whitespace_on_save` | boolean | `true` | Strip trailing whitespace on save |
| `ensure_final_newline_on_save` | boolean | `true` | Ensure trailing newline on save |
| `enable_language_server` | boolean | `true` | Enable LSP support |

Language-specific overrides use the `"languages"` key:

```jsonc
{
  "languages": {
    "Python": {
      "tab_size": 4,
      "formatter": "language_server",
      "format_on_save": "on"
    },
    "JavaScript": {
      "tab_size": 2,
      "formatter": "prettier"
    }
  }
}
```

### 3.6 UI & Appearance Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `theme` | string | `"One Dark"` | Active color theme (light or dark) |
| `ui_font_family` | string | `"Zed Plex Sans"` | UI element font |
| `ui_font_size` | number | `14` | UI font size |
| `ui_font_weight` | number | `400` | UI font weight |
| `buffer_font_fallbacks` | array | `[]` | Fallback fonts for the editor |
| `active_pane_magnification` | number | `1.0` | Magnification factor for focused pane |
| `pane_split_direction_horizontal` | string | `"up"` | Direction for horizontal splits |
| `pane_split_direction_vertical` | string | `"left"` | Direction for vertical splits |
| `centered_layout.left_padding` | number | `0.2` | Left padding ratio in centered layout |
| `centered_layout.right_padding` | number | `0.2` | Right padding ratio in centered layout |
| `show_whitespaces` | string | `"selection"` | Show whitespace: `"all"`, `"selection"`, `"none"`, `"boundary"` |
| `wrap_guides` | array | `[]` | Column positions for wrap guide lines |

### 3.7 Terminal Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `terminal.shell` | string/object | `"system"` | Shell to use: `"system"` or `{"program": "...", "args": [...]}` |
| `terminal.dock` | string | `"bottom"` | Terminal panel dock position |
| `terminal.working_directory` | string | `"current_project_directory"` | Default working directory |
| `terminal.blinking` | string | `"terminal_controlled"` | Cursor blink mode |
| `terminal.alternate_scroll` | string | `"on"` | Alternate scroll mode |
| `terminal.font_family` | string | null | Terminal font (defaults to `buffer_font_family`) |
| `terminal.font_size` | number | null | Terminal font size (defaults to `buffer_font_size`) |
| `terminal.line_height` | string | `"comfortable"` | Terminal line height |
| `terminal.detect_venv` | object | `{"on": {...}}` | Virtual environment detection |
| `terminal.toolbar.breadcrumbs` | boolean | `true` | Show breadcrumbs in terminal toolbar |

### 3.8 Project Panel Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `project_panel.button` | boolean | `true` | Show project panel toggle button |
| `project_panel.dock` | string | `"left"` | Panel dock position |
| `project_panel.default_width` | number | `240` | Default panel width in pixels |
| `project_panel.git_status` | boolean | `true` | Show git status in file tree |
| `project_panel.file_icons` | boolean | `true` | Show file type icons |
| `project_panel.folder_icons` | boolean | `true` | Show folder icons |
| `project_panel.indent_size` | number | `20` | Tree indentation in pixels |
| `project_panel.auto_reveal_entries` | boolean | `true` | Auto-reveal active file in tree |
| `project_panel.auto_fold_dirs` | boolean | `true` | Auto-fold single-child directories |
| `project_panel.scrollbar.show` | string | `"auto"` | Scrollbar visibility |

### 3.9 Git & Version Control Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `git.inline_blame` | object | `{"enabled": true}` | Show inline git blame |
| `git.inline_blame.delay_ms` | number | `600` | Delay before showing blame |
| `git.gutter_debounce` | number | `50` | Debounce for gutter git diff updates (ms) |

### 3.10 Collaboration Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `collaboration_panel.button` | boolean | `true` | Show collaboration panel button |
| `collaboration_panel.dock` | string | `"left"` | Panel dock position |
| `collaboration_panel.default_width` | number | `240` | Default panel width |
| `chat_panel.button` | boolean | `true` | Show chat panel button |
| `chat_panel.dock` | string | `"right"` | Chat panel dock position |
| `notification_panel.button` | boolean | `true` | Show notification panel button |
| `notification_panel.dock` | string | `"right"` | Notification panel dock position |

### 3.11 Auto-Update & Telemetry Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `auto_update` | boolean | `true` | Enable automatic updates |
| `telemetry.diagnostics` | boolean | `true` | Send diagnostic/crash data |
| `telemetry.metrics` | boolean | `true` | Send usage metrics |

> [!TIP]
> On Linux, if Zed was installed via a package manager (apt, pacman, etc.), the `auto_update` setting may be ignored in favor of the package manager's update mechanism.

### 3.12 AI & Agent Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `agent.enabled` | boolean | `true` | Enable the agent panel |
| `agent.default_model` | object | varies | Default model for agent conversations |
| `agent.default_profile` | string | varies | Default agent profile |
| `agent.always_allow_tool_actions` | boolean | `false` | Skip confirmation for tool actions |
| `inline_completions.disabled_globs` | array | `[]` | Glob patterns to disable inline completions |

Agent profiles configure which tools are available and their permission levels:

```jsonc
{
  "agent": {
    "profiles": {
      "write": {
        "tools": {
          "read_file": "allow",
          "edit_file": "confirm",
          "terminal": "confirm",
          "create_directory": "confirm",
          "delete_path": "deny"
        }
      }
    }
  }
}
```

Tool permission levels: `"allow"` (no confirmation), `"confirm"` (ask first), `"deny"` (blocked). Tools also support regex patterns for path-based allow/deny rules.

### 3.13 Extension Capabilities

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `granted_extension_capabilities` | object | `{}` | Per-extension capability grants |

Extensions operate under a capability-based security model. Capabilities must be explicitly granted:

```jsonc
{
  "granted_extension_capabilities": {
    "extension-name": {
      "read_clipboard": true,
      "network_access": true
    }
  }
}
```

### 3.14 Vim Mode Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `vim_mode` | boolean | `false` | Enable Vim emulation |
| `vim.use_system_clipboard` | string | `"always"` | System clipboard integration: `"always"`, `"never"`, `"on_yank"` |
| `vim.use_multiline_find` | boolean | `false` | Multi-line find in Vim mode |
| `vim.use_smartcase_find` | boolean | `false` | Smartcase for Vim find |
| `vim.custom_digraphs` | object | `{}` | Custom digraph mappings |

### 3.15 File Handling Settings

| Setting | Type | Default | Description |
|---------|------|---------|-------------|
| `file_scan_exclusions` | array | (see below) | Glob patterns excluded from file scanning |
| `file_types` | object | `{}` | Custom file type associations |
| `autosave` | string | `"off"` | Autosave mode: `"off"`, `"on_focus_change"`, `"on_window_change"`, `{"after_delay": {"milliseconds": N}}` |
| `confirm_quit` | boolean | `false` | Confirm before quitting |
| `restore_on_startup` | string | `"last_workspace"` | Restore behavior: `"last_workspace"`, `"last_session"`, `"none"` |

Default file scan exclusions:

```jsonc
[
  "**/.git",
  "**/.svn",
  "**/.hg",
  "**/CVS",
  "**/.DS_Store",
  "**/Thumbs.db",
  "**/.classpath",
  "**/.settings",
  "**/.direnv",
  "**/node_modules",
  "**/target"
]
```

### 3.16 Task Configuration

Tasks are defined in `.zed/tasks.json` (project-level) or global tasks configuration:

```jsonc
[
  {
    "label": "cargo test",
    "command": "cargo",
    "args": ["test"],
    "cwd": "$ZED_WORKTREE_ROOT",
    "env": {},
    "use_new_terminal": false,
    "allow_concurrent_runs": false
  }
]
```

### 3.17 Project-Local Settings (.zed/settings.json)

Any setting can be overridden at the project level by placing a `settings.json` file in the `.zed/` directory at the project root. Project settings take highest precedence.

```jsonc
// .zed/settings.json
{
  "tab_size": 2,
  "formatter": "prettier",
  "languages": {
    "TypeScript": {
      "tab_size": 2,
      "format_on_save": "on"
    }
  },
  "lsp": {
    "rust-analyzer": {
      "initialization_options": {
        "check": {
          "command": "clippy"
        }
      }
    }
  }
}
```

---

## 4. Deployment & Building

### 4.1 Cloning the Repository

```sh
git clone https://github.com/zed-industries/zed.git
cd zed
```

The repository is large (~200 crates, 3,800+ files, ~31M chars of source). Initial clone may take several minutes.

### 4.2 Building on macOS

**Debug build (fastest rebuild):**

```sh
cargo run
```

**Release build:**

```sh
cargo run --release
```

**Create a Zed.app bundle:**

```sh
./script/bundle-mac
```

This produces `target/release/Zed.app`. Signing and notarization are handled in CI via `ci/` workflows; local bundles are adhoc-signed and will not auto-update.

### 4.3 Building on Linux

```sh
# Install system dependencies
./script/linux

# Debug build
cargo run

# Release build + install to ~/.local/bin/zed
./script/install-linux
```

> [!WARNING]
> On GCC >= 14, `aws-lc-rs` can fail to link the `remote_server`. Set `REMOTE_SERVER_TARGET=x86_64-unknown-linux-gnu` before running `script/install-linux` to work around it.

### 4.4 Building on Windows

Use the developer command prompt (`x64 Native Tools Command Prompt for VS 2022`):

```powershell
cargo run
cargo run --release
.\script\bundle-windows.ps1
```

The MSIX / EXE installer build is orchestrated by `script/bundle-windows.ps1`.

### 4.5 Cross-Compilation

The repository includes Docker-based cross-compilation support:

- `Dockerfile-cross.dockerignore` — Docker ignore file for cross builds
- `Dockerfile-distros` — Multi-distro testing

### 4.6 Nix Build

Zed has full Nix support with a flake:

```sh
# Enter dev shell
nix develop

# Build
nix build

# Run
nix run
```

Key Nix files:
- `flake.nix` — Flake definition
- `default.nix` — Legacy Nix expression
- `nix/` — Nix-specific modules, including `nix/livekit-libwebrtc/` for LiveKit native dependency
- `nix/dev/` — Development shell configuration
- `nix/modules/` — NixOS module definitions

### 4.7 Flatpak Build

```sh
# Build Flatpak
./script/flatpak/build.sh
```

Flatpak configuration lives in `script/flatpak/`.

### 4.8 Building the Collab Server

```sh
cargo build --package collab --release
```

The collab server is also available as a Docker image:

```sh
docker build -f Dockerfile-collab -t zed-collab .
```

Docker Compose configuration for local development:

```sh
docker compose up
```

The `compose.yml` at the repository root includes PostgreSQL and LiveKit alongside the collab server. `Procfile`, `Procfile.all`, and `Procfile.web` provide process manager configurations for different deployment scenarios.

> [!TIP]
> For local development, use `Procfile.all` with a process manager like `foreman` or `overmind` to run all services (collab, LiveKit, database) simultaneously.

### 4.9 cargo-xtask

The `tooling/xtask/` crate provides custom build tasks:

```sh
cargo xtask --help
```

Xtask handles CI helpers, workflow generation, and diagnostic utilities.

### 4.10 Release Channels

Zed has four release channels, defined in `crates/release_channel/src`:

| Channel | Purpose |
|---------|---------|
| **Stable** | Production releases for general users |
| **Preview** | Pre-release builds with upcoming features |
| **Nightly** | Daily builds from main branch |
| **Dev** | Local development builds |

The active channel affects feature flags, update behavior, telemetry, and server endpoints.

---

## 5. Operations

### 5.1 Auto-Update System

The auto-update system (`crates/auto_update`) checks for and applies updates automatically. The `auto_update_helper` binary handles the actual update application (file replacement, restart coordination).

Configuration:

```jsonc
{
  "auto_update": true  // or false to disable
}
```

> [!NOTE]
> On Linux, auto-update may be managed by your system package manager rather than Zed's built-in mechanism. When installed via apt, pacman, or similar, the `auto_update` setting is typically ignored.

### 5.2 Database & State Management

Zed uses SQLite (via the custom `sqlez` crate) in WAL mode for local state:

- **Workspace state** — open files, pane layout, window positions
- **Settings** — cached settings and preferences
- **Key-value pairs** — arbitrary persistent storage
- **Trusted worktrees** — directories the user has trusted for extension/LSP execution

The `migrator` crate handles schema migrations. Database files live under the platform-specific data directory.

### 5.3 Crash Reporting

The `crashes` crate manages crash handling:

1. A `crash_handler` process is spawned alongside Zed
2. On crash, minidumps are captured
3. If `telemetry.diagnostics` is enabled, crash reports are submitted to Zed's servers

Crash reports are stored locally under the data directory regardless of telemetry settings.

### 5.4 Telemetry

Telemetry events are defined in `crates/telemetry_events/src`. Two independent toggles control data collection:

| Setting | Data Collected |
|---------|---------------|
| `telemetry.diagnostics` | Crash reports, error logs |
| `telemetry.metrics` | Usage patterns, feature adoption |

Both default to `true`. Disable with:

```jsonc
{
  "telemetry": {
    "diagnostics": false,
    "metrics": false
  }
}
```

> [!NOTE]
> Telemetry settings take effect immediately without restart. All telemetry data is anonymous and does not include file contents or personally identifiable information.

### 5.5 Log Files

Zed logs to the platform-specific data directory. The logging system uses `zlog` (custom logging crate) with configurable levels via `zlog_settings`.

Access logs from within Zed: Command Palette > "zed: open log file".

### 5.6 Collab Server Operations

The collab server (`crates/collab`) is a standalone Rust binary that requires:

1. **PostgreSQL 14+** — stores users, channels, rooms, projects
2. **LiveKit 1.6+** — handles WebRTC audio/video SFU

Kubernetes deployment manifests live in `crates/collab/k8s/environments/`. The collab server API is defined in `crates/collab/src/api/`.

### 5.7 Remote Development Operations

The remote development stack consists of:

- **`remote_server`** — runs on the remote host, provides headless Zed functionality
- **`remote_connection`** — SSH connection management on the client side
- **`remote`** — remote protocol coordination
- **`dev_container`** — Dev container support (Docker-based development environments)
- **`askpass`** — SSH password/passphrase prompting

The remote server is deployed to the target machine over SSH and communicates back through an SSH tunnel. No additional ports need to be opened.

### 5.8 Extension Management

Extensions are WASM-based and managed through the extension UI or CLI:

```sh
# Package an extension
cargo run --package extension_cli -- package ./my-extension

# Publish an extension
cargo run --package extension_cli -- publish ./my-extension
```

Extensions can provide:
- Languages (grammar, highlights, injections)
- Themes
- Language servers
- Slash commands (for the agent)
- Context servers (MCP)
- Debug adapters

The extension API is defined via WIT (WebAssembly Interface Types) in `crates/extension_api/wit/`.

> [!TIP]
> To test an extension locally, place it in the `extensions/` directory at the repository root. Built-in extensions like `html`, `glsl`, `proto`, and `workflows` live there and serve as reference implementations.

---

## 6. Performance

### 6.1 Rendering Pipeline

GPUI renders the entire UI on the GPU. The rendering pipeline:

1. **Layout** — flexbox-like layout engine computes element positions
2. **Paint** — elements emit draw commands (quads, glyphs, paths, shadows)
3. **Composite** — draw commands are batched and submitted to the GPU via wgpu

The renderer targets 120fps on capable hardware. Frame pacing is tied to the display's refresh rate.

### 6.2 Text Engine Performance

The text engine uses two custom data structures optimized for editor workloads:

- **Rope** (`crates/rope`) — a balanced tree of text chunks. Provides O(log n) insert, delete, and index operations. Enables efficient editing of multi-gigabyte files.
- **Sum Tree** (`crates/sum_tree`) — a B-tree that maintains running aggregates (line counts, byte offsets, etc.). Powers the display map, fold state, and diagnostics overlay.

### 6.3 Thread Pool Configuration

Zed uses rayon with the following configuration:
- **Thread count**: half of available parallelism (e.g., 8 threads on a 16-core machine)
- **Stack size**: 10MB per thread

This balances responsiveness (leaving cores for the OS and GPU) with throughput for parallel operations like project-wide search and multi-file formatting.

### 6.4 Memory Allocator

Release builds use **mimalloc** as the global allocator, which provides better performance characteristics than the system allocator for Zed's allocation patterns (many small, short-lived allocations from the UI framework).

### 6.5 Performance Profiling

| Tool | Location | Purpose |
|------|----------|---------|
| `ztracing` | `crates/ztracing` | Custom tracing framework |
| `ztracing_macro` | `crates/ztracing_macro` | Tracing macros |
| `input_latency_ui` | `crates/input_latency_ui` | Input latency measurement UI |
| `miniprofiler_ui` | `crates/miniprofiler_ui` | Mini profiler overlay |
| `etw_tracing` | `crates/etw_tracing` | Windows ETW tracing integration |
| `perf` | `tooling/perf` | Performance benchmarking harness |

Benchmark crates:
- `crates/worktree_benchmarks` — file watching performance
- `crates/project_benchmarks` — project operations performance
- `crates/fs_benchmarks` — filesystem operation performance

### 6.6 Performance-Relevant Settings

| Setting | Impact |
|---------|--------|
| `scroll_sensitivity` | Higher values process more scroll events per frame |
| `git.gutter_debounce` | Lower values increase responsiveness but consume more CPU |
| `indent_guides.enabled` | Disabling saves render time on large files |
| `scrollbar.git_diff` / `scrollbar.diagnostics` | Disabling saves computation on large files |
| `file_scan_exclusions` | Excluding `node_modules`, `target`, etc. significantly reduces file watcher load |

---

## 7. Security

### 7.1 Extension Security Model

Extensions run in a sandboxed WASM environment with capability-based security:

- Extensions have NO filesystem access by default
- Network access, clipboard access, and other capabilities must be explicitly granted via `granted_extension_capabilities`
- The WIT interface (`crates/extension_api/wit/`) defines the exact API surface available to extensions
- Extensions cannot access arbitrary memory or execute native code

```jsonc
{
  "granted_extension_capabilities": {
    "untrusted-extension": {}  // No capabilities granted
  }
}
```

> [!WARNING]
> The `granted_extension_capabilities` setting controls what extensions can do. Review capability requests carefully before granting them. An extension with `network_access` can exfiltrate data from files it processes.

### 7.2 Agent Tool Permissions

The agent's tool system uses a three-tier permission model:

| Permission | Behavior |
|------------|----------|
| `allow` | Tool executes without confirmation |
| `confirm` | User must approve each invocation |
| `deny` | Tool is completely blocked |

Tools support regex-based path patterns for granular control:

```jsonc
{
  "agent": {
    "profiles": {
      "safe": {
        "tools": {
          "read_file": {
            "allow": ["src/**", "docs/**"],
            "deny": ["**/.env", "**/secrets/**"]
          },
          "edit_file": "confirm",
          "terminal": "deny",
          "delete_path": "deny"
        }
      }
    }
  }
}
```

Available agent tools: `copy_path`, `create_directory`, `delete_path`, `diagnostics`, `edit_file`, `fetch`, `list_directory`, `move_path`, `now`, `find_path`, `read_file`, `restore_file_from_disk`, `save_file`, `open`, `grep`, `spawn_agent`, `terminal`, `thinking`, `update_plan`, `search_web`.

### 7.3 Trusted Worktrees

When opening a project for the first time, Zed may prompt to trust the worktree. Trusted worktrees are stored in the local SQLite database. Trusting a worktree allows:

- Language server execution
- Task execution
- Extension activation for that project

### 7.4 SSH & Remote Security

Remote development uses standard SSH for transport:

- Authentication via SSH keys or the `askpass` crate for interactive password entry
- All traffic is tunneled through the SSH connection
- No additional ports are opened on the remote host
- The `remote_server` binary runs with the permissions of the SSH user

### 7.5 Credential Management

The `credentials_provider` and `zed_credentials_provider` crates manage sensitive credentials:

- API keys for AI providers
- Authentication tokens for Zed's cloud services
- OAuth tokens for collaboration

Credentials are stored in the platform's native keychain (Keychain on macOS, Secret Service on Linux, Credential Manager on Windows).

> [!CAUTION]
> AI provider API keys configured in `settings.json` are stored in plain text on disk. For production environments, prefer OAuth-based authentication or environment variables over inline API keys.

### 7.6 Network Connections

Zed makes outgoing connections to:

| Destination | Purpose | Can Disable? |
|-------------|---------|-------------|
| `zed.dev` / `collab.zed.dev` | Collaboration, authentication, channels | Don't sign in |
| AI provider APIs | Agent, inline completions, edit predictions | Disable AI features |
| Language server downloads | LSP installation | Use pre-installed servers |
| Extension registry | Extension discovery and installation | Manual extension install |
| Telemetry endpoints | Anonymous usage data | `telemetry: {diagnostics: false, metrics: false}` |
| Update servers | Auto-update checks | `auto_update: false` |
| LiveKit SFU | Audio/video calls | Don't join calls |

---

## 8. Developer Internals

### 8.1 GPUI Framework Architecture

GPUI is Zed's custom, GPU-accelerated UI framework. Key concepts:

#### Entity System

```rust
// Create an entity (actor-lite pattern)
let entity = cx.new(|cx| MyModel::new(cx));

// Read entity state
entity.read(cx);

// Update entity state (foreground executor only)
entity.update(cx, |model, cx| {
    model.do_something(cx);
});
```

Entities mutate only on the foreground executor. Cross-thread communication uses channels or `spawn`-with-`cx.update`.

#### Element Tree

GPUI uses a retained element tree with immediate-mode-style rendering:

1. `render()` method returns an element tree description
2. GPUI diffs against the previous tree
3. Only changed subtrees are re-laid-out and re-painted

#### Actions

Actions are the primary dispatch mechanism:

```rust
#[derive(Clone, PartialEq, Action)]
struct MyAction;

// Register handler
cx.on_action(|&MyAction, cx| { /* ... */ });
```

Actions propagate up the element tree (bubbling) until handled.

### 8.2 Settings Framework

The settings system (`crates/settings`) uses a trait-based approach:

```rust
#[derive(Deserialize, Default)]
struct MySettings {
    #[serde(default)]
    option_a: bool,
}

impl Settings for MySettings {
    const KEY: Option<&'static str> = Some("my_settings");
    // ...
}
```

Settings are registered globally and resolved through the cascade (defaults -> user -> project). The `settings_macros` crate provides derive macros for common patterns.

### 8.3 Language Server Integration

The LSP integration spans several crates:

1. **`lsp`** — JSON-RPC transport and LSP protocol types
2. **`language`** — buffer integration, highlighting, diagnostics
3. **`project/src/lsp_store`** — project-level LSP lifecycle management

LSP servers are configured per-language. Custom initialization options can be passed via settings:

```jsonc
{
  "lsp": {
    "rust-analyzer": {
      "initialization_options": {
        "cargo": {
          "features": "all"
        },
        "check": {
          "command": "clippy"
        }
      }
    }
  }
}
```

### 8.4 Debug Adapter Protocol Integration

The DAP stack mirrors LSP:

1. **`dap`** — DAP transport (JSON over stdio)
2. **`dap_adapters`** — per-adapter configurations (CodeLLDB, debugpy, JS debug, etc.)
3. **`debugger_ui`** — UI panels (variables, call stack, breakpoints)
4. **`debug_adapter_extension`** — DAP support via the extension system

Adapters can be auto-installed when a debug session starts.

### 8.5 Tree-sitter Integration

Zed uses tree-sitter for:

- Syntax highlighting
- Code folding
- Bracket matching
- Outline/symbols
- Indentation computation
- Injection queries (embedded languages)

Grammar management lives in `crates/grammars`. Language configurations (highlights, injections, textobjects) are in `crates/languages` and extensions.

### 8.6 Protobuf RPC Layer

The collaboration and remote protocols use protobuf:

- **`proto`** — `.proto` definitions in `crates/proto/proto/`, generated via `prost`
- **`rpc`** — multiplexed connection, message routing, peer management

The RPC layer supports both collaboration (client-server via `collab`) and remote development (peer-to-peer via SSH tunnel).

### 8.7 Edit Prediction System

The edit prediction system provides AI-powered inline completions:

1. **`edit_prediction`** — runtime coordination, accept/reject logic
2. **`edit_prediction_context`** — gathers surrounding code context
3. **`zeta_prompt`** — builds prompts for the prediction model
4. **`edit_prediction_metrics`** — tracks prediction quality
5. **`edit_prediction_ui`** — renders ghost text overlay
6. **`edit_prediction_cli`** — offline evaluation tooling

### 8.8 WASM Extension Runtime

Extensions are compiled to WASM and run in the `extension_host`:

1. Extension author writes Rust (or any language targeting WASM)
2. The `extension_api` crate provides the guest-side API
3. WIT definitions (`crates/extension_api/wit/`) describe the interface
4. The `extension_host` instantiates WASM modules via wasmtime
5. Capability gates control access to host functionality

### 8.9 Crate Dependency Graph (Simplified)

```
zed (binary)
├── workspace
│   ├── editor
│   │   ├── language, language_core
│   │   ├── lsp
│   │   ├── multi_buffer
│   │   │   ├── text
│   │   │   │   ├── rope
│   │   │   │   └── sum_tree
│   │   │   └── buffer_diff
│   │   └── project
│   │       ├── worktree → fs
│   │       ├── git
│   │       ├── dap
│   │       └── remote_connection
│   ├── sidebar
│   │   ├── agent_ui → agent → language_model → provider crates
│   │   ├── git_ui
│   │   ├── debugger_ui
│   │   └── project_panel
│   └── terminal_view → terminal
├── gpui
│   ├── gpui_{macos,linux,windows,web}
│   └── gpui_wgpu
├── extension_host → extension_api
├── settings
├── theme
├── db → sqlez
└── auto_update
```

### 8.10 Key Data Structures

| Structure | Crate | Purpose |
|-----------|-------|---------|
| `Rope` | `rope` | Balanced tree of text chunks for O(log n) editing |
| `SumTree<T>` | `sum_tree` | B-tree maintaining running aggregates |
| `Buffer` | `text` | CRDT-based text buffer with undo/redo |
| `MultiBuffer` | `multi_buffer` | Virtual buffer combining excerpts from multiple files |
| `DisplayMap` | `editor` | Maps buffer positions to display positions (folds, wraps, inlays) |
| `Worktree` | `worktree` | In-memory file tree with filesystem watching |
| `Entity<T>` | `gpui` | Actor-lite wrapper for state management |
| `Subscription` | `gpui` | Event subscription handle (auto-unsubscribes on drop) |

---

## 9. Integration Points

### 9.1 Language Server Protocol (LSP)

Zed acts as an LSP client. Language servers are managed per-project by the `lsp_store` in the `project` crate. Configuration per-server is done via the `lsp` key in settings:

```jsonc
{
  "lsp": {
    "server-name": {
      "initialization_options": { /* server-specific */ },
      "settings": { /* server-specific workspace settings */ }
    }
  }
}
```

### 9.2 Debug Adapter Protocol (DAP)

Zed acts as a DAP client. Adapter configurations live in `crates/dap_adapters/src`. Supported adapters include CodeLLDB, debugpy, and others via the extension system.

### 9.3 AI Providers

Each AI provider has its own crate implementing the `LanguageModel` trait from `crates/language_model`. Provider configuration is done via settings:

```jsonc
{
  "language_models": {
    "anthropic": {
      "api_key": "...",
      "default_model": "claude-sonnet-4-20250514"
    },
    "ollama": {
      "api_url": "http://localhost:11434"
    },
    "openai": {
      "api_key": "...",
      "default_model": "gpt-4o"
    }
  }
}
```

Full provider list: Anthropic, OpenAI, Ollama, LM Studio, Mistral, DeepSeek, Google AI, OpenRouter, AWS Bedrock, GitHub Copilot, xAI, Codestral, Vercel, Zed Cloud.

### 9.4 MCP (Model Context Protocol)

The agent system supports MCP context servers via `crates/context_server`. Context servers provide additional context to agent conversations (documentation, codebase knowledge, external data).

### 9.5 Git Integration

Git support is provided through `crates/git` with `libgit2` bindings and CLI fallback:

- Inline blame (`git.inline_blame`)
- Gutter diff indicators
- Git status in project panel and tabs
- Full Git UI panel (`crates/git_ui`)
- Git graph visualization (`crates/git_graph`)
- Hosting provider integration (`crates/git_hosting_providers`) for GitHub, GitLab, Bitbucket, etc.

### 9.6 Jupyter / REPL

The `repl` crate (`crates/repl`) provides Jupyter kernel integration for interactive code execution. Supports inline output rendering.

### 9.7 IPC (CLI to GUI)

The `cli` binary communicates with the main `zed` process via `ipc-channel`:

- Launch new Zed instance or connect to running one
- Open files/directories
- `--wait` flag blocks the CLI until the file is closed in Zed

### 9.8 Audio & Collaboration

The collaboration stack uses:

- **LiveKit** — WebRTC SFU for audio/video
- **`denoise`** — noise suppression using bundled ML models (in `crates/denoise/models/`)
- **`call`** — call management
- **`channel`** — text and voice channels

### 9.9 Web Search

The `web_search` and `web_search_providers` crates provide web search integration for the agent, allowing it to search the web for relevant information during conversations.

### 9.10 Troubleshooting

#### Common Build Issues

| Problem | Solution |
|---------|----------|
| `protoc` not found | Install Protocol Buffers compiler: `brew install protobuf` (macOS), `apt install protobuf-compiler` (Linux) |
| Missing Linux system libraries | Run `./script/linux` to install all required system dependencies |
| `aws-lc-rs` link failure on GCC >= 14 | Set `REMOTE_SERVER_TARGET=x86_64-unknown-linux-gnu` |
| Windows build fails | Ensure you're using the x64 Native Tools Command Prompt for VS 2022 |
| Rust toolchain mismatch | Run `rustup show` to verify the workspace toolchain from `rust-toolchain.toml` is active |

#### Common Runtime Issues

| Problem | Solution |
|---------|----------|
| Blank/black window on Linux | Verify Vulkan or OpenGL 3.3 drivers are installed; try `MESA_GL_VERSION_OVERRIDE=3.3` |
| High CPU on startup | Large projects trigger file scanning; add exclusions to `file_scan_exclusions` |
| Language server not starting | Check `lsp` settings; verify the server binary is installed and on `$PATH` |
| Extension not loading | Check `granted_extension_capabilities`; verify WASM compatibility |
| `--wait` doesn't block (issue #54203) | Known issue; the CLI may not block correctly in all scenarios |
| Crash staging code blocks (issue #54155) | Known crash when staging certain code blocks |
| Inline blame showing wrong info | Ensure git repository is clean; try `git fsck` |
| Shift-Insert pastes wrong selection on Linux (issue #53446) | Known issue with X11 primary selection handling |
| ESLint/Intelephense not working (issue #54093) | Check LSP configuration and server installation |
| Can't open worktree inside another git repo (issue #53331) | Known limitation with nested git repositories |

> [!WARNING]
> If Zed crashes on startup, check for corrupted state by renaming the data directory (see Section 3.3 for paths). Zed will recreate it on next launch. This loses workspace state but often resolves initialization crashes.

#### Diagnostic Information

From within Zed, access diagnostic info via:

- **Command Palette > "zed: open log file"** — application logs
- **Command Palette > "zed: copy system specs"** — system information for bug reports
- **Command Palette > "zed: open local settings"** — current settings with resolved values

The `system_specs` crate (`crates/system_specs`) gathers comprehensive system information.

> [!TIP]
> When filing a bug report, always include the output of "zed: copy system specs". This includes your Zed version, release channel, OS version, GPU info, and relevant settings.

#### Environment Variables

| Variable | Purpose |
|----------|---------|
| `ZED_FORCE_CLI_MODE` | Force CLI mode when running the binary directly |
| `ZED_STATELESS` | Disable single-instance check (allows multiple Zed processes) |
| `REMOTE_SERVER_TARGET` | Override remote server build target for cross-compilation workarounds |

Additional `ZED_*` environment variables are defined in `crates/zed_env_vars/src`.

#### Log Levels

Zed's logging system (`crates/zlog`, `crates/zlog_settings`) supports configurable log levels. Increase verbosity for debugging:

```jsonc
{
  "log_level": "debug"  // "error", "warn", "info", "debug", "trace"
}
```

#### Database Recovery

If the SQLite database becomes corrupted:

1. Close Zed completely
2. Navigate to the data directory (Section 3.3)
3. Rename or delete the database file
4. Restart Zed (it will create a fresh database)

You will lose workspace state (open files, window positions) but not your settings or keymaps (those are separate JSON files).

---

_Generated May 2026 from zed-industries/zed at 7b0f59b. AI-generated documentation. The library is checked by sampling (three repositories so far); this guide was not individually reviewed. Verify against the project before relying on it. Unofficial; not affiliated with or reviewed by the project._