DDEV Zed

Zed editor integration for DDEV projects: tasks for everyday ddev commands, a ready-to-use Xdebug listener, and a ddev zed command to open the project.

Install

ddev add-on get jfeid/ddev-zed

To also connect Zed’s Agent Panel to DDEV, opt in to the MCP server (see DDEV MCP server):

DDEV_ZED_MCP=true ddev add-on get jfeid/ddev-zed

What it installs

Canonical copies live in .ddev/zed/.

DDEV MCP server (optional)

Setting DDEV_ZED_MCP=true during install writes .zed/settings.json with a context_servers entry that runs ddev-mcp (source) via npx -y ddev-mcp. Nothing is installed at that moment: npx downloads the package the first time Zed starts the server, so Node.js 20+ must be available on your PATH.

ddev-mcp is a Model Context Protocol server that exposes DDEV as tools. Once Zed loads it, the Agent Panel can:

• start, stop, restart the project and read ddev describe output
• read container logs
• import, export and snapshot the database
• run any command inside the web container through ddev_exec (composer, drush, wp-cli, artisan, phpunit, …)

so you can ask the agent things like “restart ddev and run the migrations” instead of switching to a terminal. The server runs commands in the project the Agent Panel is open in.

This works with Zed’s built-in agent and with external agents such as Claude Code running inside Zed. Zed forwards its configured context servers to external agents, so a Claude Code thread started from the Agent Panel sees the same ddev_* tools. The built-in agent needs a model first: Zed’s free plan doesn’t include one, so add an API key under Configure Providers, use a local Ollama model, or use an external agent with its own account.

Tool calls are subject to the Agent Panel’s normal confirmation flow. ddev-mcp also blocks commands it classifies as dangerous (for example destructive Platform.sh or database operations) unless ALLOW_DANGEROUS_COMMANDS=true is set in the server’s env block in .zed/settings.json.

If .zed/settings.json already exists and has no #ddev-generated marker, the add-on leaves it alone and prints a message. Copy the context_servers block from .ddev/zed/settings.json into your file manually. If you skip the opt-in, .zed/settings.json is not created and the Agent Panel is unaffected.

Ownership

Files containing #ddev-generated belong to the add-on and are updated on reinstall. Delete that line to take ownership; the add-on will then skip the file on install and keep it on removal. When it skips a file, it lists the template entries your file doesn’t have (task and debug labels, or the ddev-mcp server) so you can merge them by hand from .ddev/zed/.

Debugging

1. Start “DDEV: Listen for Xdebug” from the debug panel.
2. Run the ddev: xdebug toggle task.
3. Load the page.

The listener binds to 0.0.0.0:9003 so the web container can reach it, and maps /var/www/html to $ZED_WORKTREE_ROOT, the task variable Zed resolves to the project root. If breakpoints don’t trigger, see the FAQ: the usual causes are a host firewall blocking port 9003 or, rarely, the variable not resolving.

Keybindings

Zed’s keymap.json is global, so the add-on doesn’t touch it. Example:

[
  {
    "context": "Workspace",
    "bindings": {
      "ctrl-alt-d s": ["task::Spawn", { "task_name": "ddev: start" }],
      "ctrl-alt-d x": ["task::Spawn", { "task_name": "ddev: xdebug toggle" }],
      "ctrl-alt-d h": ["task::Spawn", { "task_name": "ddev: ssh" }]
    }
  }
]

FAQ

See FAQ.md for firewall setup, path mapping fallbacks, and merging into user-owned files.

Remove

ddev add-on remove zed

Contributed and maintained by @jfeid