zed-workspace

zed-workspace

Portable, named, version-controlled workspace manifests for Zed — plus an MCP server that hands that workspace context to MCP-capable AI tools.

Zed already supports multi-root projects natively (File > Add Folder to Project). What Zed has no equivalent of is VSCode's .code-workspace file: a single, committable, shareable definition of a named multi-root workspace with its settings, tasks, debug configs, and environment. That gap is what this project fills.

---

What this is — and is not

• Is: a .zworkspace.toml manifest format + a launcher (zw) that materializes it into Zed's per-root .zed/ config, and an MCP server that exposes the manifest to AI tools.
• Is not: "multi-root support for Zed" — Zed has that. This adds the persistent, on-disk, version-controlled workspace definition Zed lacks.

MCP vs ACP — they are different things

This project's server speaks MCP (Model Context Protocol — the agent↔tools protocol). It is not an ACP (Agent Client Protocol — the editor↔agent protocol) implementation. Zed's ACP layer forwards MCP servers configured in context_servers to external agents; that is how an ACP-driven agent in Zed ends up able to call this server's tools. But the server itself is a plain MCP stdio server — usable by any MCP-capable client, not just Zed.

---

Parity with VSCode .code-workspace — honest scorecard

Capability	Status
Multi-root folder list, paths anywhere on disk	✅
Portable relative paths (~, $VAR expansion)	✅
Workspace-level settings overlay	✅
Per-folder settings (override workspace)	✅
Workspace tasks + per-folder tasks	✅
Debug launch configs (.zed/debug.json)	✅
Extension recommendations	✅ (advisory — see below)
Workspace environment variables	✅
Cross-root search (for AI tools, via MCP)	✅
UI-state persistence (open files, layout restored per workspace)	❌ Zed-owned — no API
Per-workspace extension enable/disable	❌ Zed has no such concept

Realistic ceiling is ~90%. The last ~10% (UI-state persistence, per-workspace extension toggling) is managed internally by Zed with no file or API a third-party tool can drive. Extension recommendations are emitted as Zed's auto_install_extensions — that recommends installation, it does not enforce per-workspace enable/disable.

---

Components

Crate	Binary	Role
zworkspace-core	—	Shared manifest schema + loader (one source of truth)
zw-cli	zw	Launcher — reads manifest, writes .zed/ config, opens Zed
zed-workspace-mcp	zed-workspace-mcp	MCP server exposing workspace context

---

Install

git clone https://github.com/GQAdonis/zed-workspace
cd zed-workspace
./install.sh

Installs zw and zed-workspace-mcp to ~/.cargo/bin/.

---

Quick start

zw init                 # scaffold a .zworkspace.toml in the current directory
$EDITOR .zworkspace.toml
zw check .              # validate
zw open .               # write .zed/ config and open Zed
zw list                 # list workspaces in ~/.config/zed/workspaces/

---

Workspace manifest (.zworkspace.toml)

[workspace]
name        = "prometheus-core"
description = "UAR · Flint Gate · Identity"
icon        = "🔥"

[[roots]]
path = "~/Projects/prometheus-uar"
name = "UAR"

[[roots.tasks]]                       # per-folder task — only in this root
label   = "test UAR"
command = "cargo test -p uar"

[[roots]]
path = "~/Projects/flint-gate"
name = "Flint Gate"

[zed]
theme          = "One Dark"
tab_size       = 4
format_on_save = "on"

[extensions]                          # advisory — emitted as auto_install_extensions
recommendations = ["tamasfe.even-better-toml"]

[[tasks]]                             # workspace-level task — written to every root
label   = "build all"
command = "cargo build --workspace"

[[debug]]                             # debug launch config — written to .zed/debug.json
label   = "Debug zw"
adapter = "lldb"
program = "$ZED_WORKTREE_ROOT/target/debug/zw"

[env]
RUST_LOG = "debug"

[mcp]
auto_start = true    # emit a context_servers stanza so Zed launches the MCP server

See docs/WORKSPACE_FORMAT.md for the full schema.

---

What zw open does

1. Parses and validates .zworkspace.toml.
2. Resolves all root paths.
3. For every existing root, writes (deep-merged, never clobbering):
   • .zed/settings.json — workspace settings + that root's [roots.zed] override + a context_servers stanza for zed-workspace-mcp.
   • .zed/tasks.json — workspace tasks + that root's [[roots.tasks]], merged by label so hand-written tasks survive.
   • .zed/debug.json — debug launch configs (if any).
4. Calls zed --new-window <root1> <root2> ... <rootN>.