setup-zed-workspace

Setup Zed Workspace

Bootstrap a project so every AI coding tool sees the same multi-root workspace context. This skill is a thin orchestrator: the real work is done by the zw CLI and zed-workspace-mcp server. The skill never re-implements manifest logic — it shells out to zw.

What it produces

Artifact	Tool that wrote it	For
.zworkspace.toml	zw init (then user edits)	the source of truth
.zed/settings.json, tasks.json, debug.json	zw open	Zed
.claude/settings.json MCP entry	scripts/wire-claude.sh	Claude Code
.opencode/opencode.json MCP entry	scripts/wire-opencode.sh	OpenCode
.mcp.json	scripts/wire-generic-mcp.sh	Cursor, Windsurf, Codex
AGENTS.md workspace block	scripts/update-agents-md.sh	any agent at session start

Honest scope

• Native slash commands: only Claude Code and OpenCode have real command systems. This skill ships commands for both.
• Everything else (Cursor, Windsurf, Codex) gets the workspace via a .mcp.json entry and an AGENTS.md block — not slash commands. There is no universal slash-command standard; do not promise one.
• All config writers deep-merge — they never overwrite an existing config.

Prerequisites

Before doing anything, verify zw is installed:

command -v zw >/dev/null || echo "zw not found"

If absent, tell the user to install it and stop:

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

Do not proceed without zw — this skill delegates to it.

Workflow

Step 1 — Scaffold the manifest

If no .zworkspace.toml exists in the target directory:

zw init .

Then help the user edit .zworkspace.toml: set workspace.name, add each project folder as a [[roots]] entry, and add any [zed], [[tasks]], [env] blocks they want. See references/manifest-quickref.md.

Step 2 — Validate

zw check .

Fix any reported error before continuing.

Step 3 — Materialize Zed config

zw open . --dry-run    # preview what will be written
zw open .              # write .zed/ config and open Zed

zw writes .zed/settings.json (including the context_servers stanza for zed-workspace-mcp), tasks.json, and debug.json into every root.

Step 4 — Wire the other AI tools

Determine the absolute manifest path, then run the wiring scripts for whichever tools the user uses. Each script deep-merges — safe to re-run.

MANIFEST="$(pwd)/.zworkspace.toml"
WS_NAME="$(grep -m1 '^name' .zworkspace.toml | sed 's/.*= *//; s/\"//g')"

bash skills/setup-zed-workspace/scripts/wire-claude.sh      "$WS_NAME" "$MANIFEST"
bash skills/setup-zed-workspace/scripts/wire-opencode.sh    "$WS_NAME" "$MANIFEST"
bash skills/setup-zed-workspace/scripts/wire-generic-mcp.sh "$WS_NAME" "$MANIFEST"
bash skills/setup-zed-workspace/scripts/update-agents-md.sh "$WS_NAME"

When invoked as a plugin, the scripts live under ${CLAUDE_PLUGIN_ROOT}/skills/setup-zed-workspace/scripts/.

Step 5 — Confirm

Tell the user which tools were wired and how to verify:

• Zed: open the workspace; the agent panel can call workspace_info.
• Claude Code: /mcp lists zed-workspace-mcp.
• OpenCode: the MCP server appears in its tool list.

Related commands

• zw-setup — runs this whole workflow.
• zw-debug-config — scaffold or edit a [debug] launch config.
• zw-debug-start — open the workspace and start a configured debug session.

Boundaries

• Never overwrite a tool's existing config — always merge.
• Never re-implement what zw does — shell out to it.
• Do not claim slash-command support for tools that lack a command system.