IDE setup (VS Code + Zed + clangd)¶

Use this page to get working code navigation in VS Code or Zed. Both editors use clangd as the C/C++ language server (VS Code disables Microsoft IntelliSense explicitly), and clangd needs a Meson build directory that contains compile_commands.json.

Quick start¶

1. Configure one build directory with every backend your host has a toolchain for (see below).
2. Open the repository in VS Code or Zed.
3. Restart clangd so it re-reads compile_commands.json.
4. Open a backend file such as core/src/feature/cuda/ or core/src/feature/sycl/ and confirm there are no "undeclared identifier" errors.

Which build directory each tool reads¶

The tools do not all read the same directory. Make sure the directory each one reads exists, or configure both:

meson setup build core writes build/; a make build writes core/build/. For VS Code, configure core/build (or change --compile-commands-dir locally); for Zed, configure build.

Make sure the build directory covers every backend you touch¶

compile_commands.json only contains entries for files that were actually compiled. If the build directory was set up CPU-only, clangd has no include paths for CUDA / SYCL headers and lights up every VmafCudaBuffer / sycl::queue symbol as "undeclared identifier".

Configure the IDE build with every backend for which the host has a toolchain:

# CUDA + SYCL (full GPU IDE build)
source /opt/intel/oneapi/setvars.sh
CC=icx CXX=icpx meson setup build core \
    -Denable_cuda=true -Denable_sycl=true \
    -Denable_float=true

Then restart clangd so it re-reads compile_commands.json.

If you need separate backend build directories¶

Do not turn the IDE build into an enable-only-one-backend directory. Use named build directories alongside it:

# CUDA-only test build
meson setup build-cuda-test core \
    -Denable_cuda=true -Denable_sycl=false -Denable_float=true

# SYCL-only test build (icx/icpx required)
CC=icx CXX=icpx meson setup build-sycl-test core \
    -Denable_cuda=false -Denable_sycl=true -Denable_float=true

The cross-backend gate scripts under scripts/ci/ accept a selected binary through --vmaf-binary.

Symptoms of a misconfigured build directory¶

• unknown type name 'VmafCudaBuffer' / VmafCudaState under core/src/feature/cuda/;
• 'sycl/sycl.hpp' file not found under core/src/feature/sycl/; or
• a cascade of include-cleanliness warnings after clangd's first fatal error.

If clangd otherwise works, regenerate the compilation database with the backend enabled before changing source includes.

Zed editor¶

The checked-in contract targets Zed 1.18.1 (bebe92f469834a287f5a57ed78e8d51a918b8ada). It was verified against that exact upstream source revision and the current official Zed documentation on 2026-09-24. .zed/ and .vscode/ coexist; neither editor needs the other's configuration.

Project settings versus user settings¶

Zed parses .zed/settings.json with its restricted project-settings schema. The repository therefore keeps only settings that can actually be applied to this worktree:

These belong in the developer's user settings, not in the project: agent, agent_servers, UI preferences, telemetry, and extension installation. Project settings cannot install ACP agents or set native-agent permissions, and keeping them out of the repository is a trust boundary: cloning a project must not silently choose a provider, model, or permission policy for a developer.

Zed opens new worktrees in Restricted Mode. Trust the worktree only after reviewing .zed/settings.json; until then Zed deliberately will not launch the project's language or MCP servers.

Extensions¶

Install the Meson extension for the Meson file association. C, C++, Go, Python, CodeLLDB, Debugpy, and Delve support are built into Zed or installed on first use. The repository does not use auto_install_extensions: Zed reads that key from user settings only.

External agents (ACP)¶

Open zed: acp registry and install whichever external agents you use. The current registry IDs for the team's three common clients are claude-acp, codex-acp, and gemini. If a developer prefers a declarative user-level manifest, this is the supported shape in ~/.config/zed/settings.json:

{
  "agent_servers": {
    "claude-acp": { "type": "registry" },
    "codex-acp": { "type": "registry" },
    "gemini": { "type": "registry" }
  }
}

Do not add provider model IDs here. External ACP agents own their authentication, subscription, model selection, and native permission policy. Zed's agent.tool_permissions applies to the native Zed Agent and is user-global; it is not a project-level substitute for an external agent's write mode.

Dev container and MCP¶

For vmaf, vmaf-tune, AI, and MCP work, build the exact-source image first and then start the service from Zed's task picker:

1. Dev container: build exact source
2. Dev container: start
3. MCP: probe running container

The context-server process is equivalent to:

docker exec -i vmaf-dev-mcp vmafx-mcp

The server is the Go binary from cmd/vmafx-mcp (ADR-1229). The old Python vmaf-mcp command is retained only as a compatibility surface and is not the IDE default. Current Zed custom MCP entries use command plus args; the old source: "custom" field is not part of the 1.18.1 shape.

Checked-in tasks¶

.zed/tasks.json keeps the three governance tasks introduced by the HISS adoption and adds current, executable workflows:

The container mounts /workspace read-only, so the fast-gate task writes its build directory under /probes; a task that tries to create /workspace/build will fail by design.

Checked-in debug scenarios¶

.zed/debug.json provides:

• CodeLLDB launch and attach scenarios for the vmaf CLI;
• CodeLLDB scenarios for test_feature in normal and ASan/UBSan builds;
• Debugpy for the active pytest file and the current vmaftune.cli module; and
• Delve for the Go cmd/vmafx-mcp server.

Zed only falls back to .vscode/launch.json when no .zed/debug.json configurations exist, so the checked-in Zed list must remain complete enough for the advertised workflows.

Regression check¶

Run the focused contract after editing any .zed/ file or this guide:

python3 -m pytest -q scripts/ci/tests/test_zed_project_config.py

The test rejects project-ignored agent / agent_servers keys, the retired numbered workspace root, the deprecated Python MCP entrypoint, deleted helper paths, the pre-package vmaf-tune module path, and loss of the governance tasks.

Authoritative Zed references¶

• Project settings parser at the verified 1.18.1 commit
• Settings-store project parser at the verified commit
• External agents
• Model Context Protocol
• Edit predictions
• Tasks
• Debugger

The older dated migration documents remain historical evidence only. Do not copy their version-specific snippets into current configuration.