Architecture

Zed is structured as a set of Rust crates that compose into a small number of binaries. The desktop editor (zed) is the main binary; everything else is either a supporting tool, a separate runtime (e.g. the collab backend), or a dependency layer.

High-level shape

graph TD
    subgraph Client["Client (your machine)"]
        ZED[zed binary]
        CLI[zed CLI]
        AUH[auto_update_helper]
        ZED -->|spawns| AUH
        CLI -.->|forwards args| ZED
    end

    subgraph Remote["Remote dev host"]
        RS[remote_server]
        ZED <-->|SSH + RPC| RS
    end

    subgraph Cloud["Zed Industries cloud"]
        CO[collab]
        CLOUD[zed.dev REST + LLM gateway]
        ZED <-->|RPC over WS| CO
        ZED <-->|HTTPS| CLOUD
    end

    subgraph External["External services"]
        LSP[Language servers]
        DAP[Debug adapters]
        LLM[LLM providers]
        ZED <-->|stdio JSON-RPC| LSP
        ZED <-->|stdio DAP| DAP
        ZED -->|HTTPS| LLM
    end

The zed binary is one process. The collab backend is a separate Rust service in the same monorepo (crates/collab) deployed by Zed Industries; clients reach it over WebSocket-tunneled protobuf RPC defined in crates/proto.

Layered crate organization

Crates fall into rough tiers. There is no enforced layering beyond Cargo's dependency DAG, but the conceptual stack looks like this:

graph BT
    subgraph L0["L0 — Platform & primitives"]
        gpui[gpui]
        sumtree[sum_tree]
        rope[rope]
        text[text]
        fs[fs]
        util[util]
        proto[proto]
        rpc[rpc]
        clock[clock]
        scheduler[scheduler]
    end

    subgraph L1["L1 — Domain models"]
        language[language]
        buffer_diff[buffer_diff]
        multi_buffer[multi_buffer]
        settings[settings]
        theme[theme]
        ui[ui]
        worktree[worktree]
        lsp[lsp]
        dap[dap]
        task[task]
    end

    subgraph L2["L2 — Major systems"]
        project[project]
        editor[editor]
        workspace[workspace]
        terminal[terminal]
        client[client]
        extension_host[extension_host]
        agent[agent]
    end

    subgraph L3["L3 — UI panels & features"]
        agent_ui[agent_ui]
        debugger_ui[debugger_ui]
        git_ui[git_ui]
        project_panel[project_panel]
        vim[vim]
        outline[outline]
        search[search]
    end

    subgraph L4["L4 — Application binaries"]
        zedbin[zed]
        clibin[cli]
        collab[collab]
        remote_server[remote_server]
    end

    L1 --> L0
    L2 --> L1
    L3 --> L2
    L4 --> L3

The split is a heuristic. Large crates like editor and project are themselves multi-thousand-file modules with internal layering.

Process model and concurrency

• Single foreground thread. All entity updates and UI rendering happen on the main thread under a gpui::App context. This is enforced by the type system (Context<T> is not Send).
• Background threadpool. cx.background_spawn(async move { … }) runs CPU work off-thread. Tasks return Task<R> futures; foreground code awaits them.
• Tokio bridge. The async runtime is GPUI's own executor. Crates that need Tokio (HTTP, gRPC clients, LiveKit) bridge through gpui_tokio.
• Subprocesses. Language servers, debug adapters, and the Node runtime are spawned as child processes. JSON-RPC over stdio for LSP/DAP; the Node sidecar is used by extensions and AI tools that need npm-published packages.

Major subsystems and where they live

Subsystem	Primary crate(s)	Purpose
UI framework	gpui, gpui_platform, gpui_wgpu, gpui_{macos,linux,windows}	Windowing, rendering, input, entity/state model
Editor	editor, multi_buffer, text, rope, buffer_diff	Buffers, cursors, selections, syntax-aware editing
Project model	project, worktree, fs	Open folders, file watching, language servers, tasks
Language services	language, language_models, lsp, tree_sitter (via grammars)	Tree-sitter grammars, LSP wiring, semantic analysis
Debugger	dap, dap_adapters, debugger_ui	DAP client, adapter registry, debug UI panels
Terminal	terminal, terminal_view	Embedded terminals (alacritty)
Workspace + panels	workspace, panel, sidebar, project_panel, outline_panel	Split panes, docks, tabs, navigation panels
AI agent	agent, agent_ui, agent_servers, acp_thread, acp_tools	Agent panel, MCP-style tools, ACP (agent client protocol)
Edit prediction	edit_prediction, edit_prediction_*	Inline AI completion suggestions
Vim mode	vim, vim_mode_setting	Modal editing emulation
Collaboration	collab, collab_ui, call, channel, livekit_client	Multi-user editing, calls, channels, presence
Remote dev	remote, remote_connection, remote_server	Headless server-side editor, SSH transport
Extensions	extension, extension_host, extension_api, extensions_ui	WASM extension runtime + first-party extensions in extensions/
Settings	settings, settings_content, settings_ui, settings_json	JSON settings stack with schema generation
Telemetry	telemetry, telemetry_events, crashes	Event pipeline + crash reporting
RPC	rpc, proto, cloud_api_*	Protobuf schemas and message routing

For deeper coverage, see Systems and Features.

Data flow: opening a file

sequenceDiagram
    participant U as User
    participant W as Workspace
    participant P as Project
    participant Wt as Worktree
    participant L as LanguageRegistry
    participant LS as LSP server
    participant E as Editor

    U->>W: Cmd+P → "src/foo.rs"
    W->>P: open_buffer(path)
    P->>Wt: load_file(path)
    Wt-->>P: Buffer (text + language inferred)
    P->>L: language_for_path("foo.rs")
    L-->>P: Language(rust)
    P->>LS: spawn rust-analyzer if needed
    P->>E: BufferHandle + Language
    E-->>U: editor view with syntax + diagnostics

The same Buffer may be shared between multiple Editors and MultiBuffers — buffers are reference-counted entities, and edits propagate via GPUI events.

Data flow: an agent turn

sequenceDiagram
    participant U as User
    participant AP as AgentPanel
    participant T as Thread
    participant LM as LanguageModel
    participant TL as Tool runner
    participant Pr as Project

    U->>AP: types prompt
    AP->>T: send_user_message(prompt)
    T->>LM: stream_completion(messages, tools)
    LM-->>T: tool_call(read_file, path=...)
    T->>TL: dispatch(tool_call)
    TL->>Pr: read buffer
    Pr-->>TL: text
    TL-->>T: tool_result
    T->>LM: stream_completion(messages + tool_result)
    LM-->>T: assistant text
    T-->>AP: stream chunks → render

See AI agent for the full breakdown.

Build and distribution

• Local dev builds: cargo run from the workspace root. Profile defaults are tuned in Cargo.toml ([profile.dev], [profile.release-fast]).
• Production bundling lives in script/bundle-{mac,linux,windows.ps1,freebsd} with packaging assets under crates/zed/contents/ and crates/zed/resources/.
• Auto-update flow: the running app checks the update server, downloads a new bundle, and hands off to auto_update_helper to swap binaries.
• The cli binary (crates/cli) is the small zed command-line shim that finds and forwards to the GUI app.

Where AI fits

Zed bets heavily on AI features. The agent crate implements an autonomous coding agent with tool use; edit_prediction does inline completions; language_models and its _cloud cousin abstract over Anthropic, OpenAI, Google, Bedrock, Ollama, Mistral, DeepSeek, OpenRouter, Codestral, LMStudio, X.AI, and Zed's own cloud LLM gateway. The Agent Client Protocol (ACP) crates (acp_thread, acp_tools, agent_servers) let external agent backends (e.g. Codex, Gemini CLI) plug into the same UI.