Check the setup
acdev doctor checks what acdev dev and acdev test need on this machine and says how to fix what is wrong; acdev doctor --fix fixes what acdev may fix itself. Run it after installing, in a project you are about to work on, and whenever acdev dev, acdev test or the MCP start does not come up.
acdev doctorok acdev: X.Y.Z on Bun 1.4.4 (/Users/me/.acdev/versions/X.Y.Z)ok PATH: acdev on PATH is this one (/Users/me/.acdev/bin/acdev)ok Bun and Node.js: Bun 1.4+ at /Users/me/.bun/bin/bun; Node.js 22.3+ at /opt/homebrew/bin/nodeok runtime: acdev X.Y.Z (contract level 1) at /Users/me/.acdev/versions/X.Y.Z/libexec/acdev (installed next to acdev)ok contract level: level 1 on both sides (acdev runtime X.Y.Z, SDK X.Y.Z)ok gpu: Apple M3 Pro (Metal, integrated GPU): drew a test frame in 38 msok acdev dev sessions: none runningok project: notes, app (acde.config.jsonc): acdev check finds nothing wrongok platform: macos (desktop, standalone) has every required capabilityok dependencies: installed with bun (runs on Bun 1.4+), @dopame/acde-api X.Y.Zok git: .acde/ (the build output) is ignoredok agent skill: current in /Users/me/.agents/skills/acdev, /Users/me/.claude/skills/acdevacdev doctor: everything acdev needs is hereEach line is <status> <check>: <what it found>:
| Status | Meaning |
|---|---|
ok |
Fine |
warn |
Works, but something will get in the way; a fix: line follows |
error |
acdev dev or acdev test will not work; a fix: line follows when there is one |
skip |
Not checked: there is no project here, or the check needs one that failed |
The last line counts errors and warnings. The exit code is 1 when any check is an error, else 0. acdev doctor <dir> checks the project in <dir> instead of the current directory (a directory with no acde project is then an error), and --online adds whether a newer acdev is out.
What it checks
Section titled “What it checks”| Check | What it looks at |
|---|---|
acdev |
The version of acdev and the JavaScript runtime it runs on |
PATH |
Whether the acdev on PATH is this one, not another install or checkout |
Bun and Node.js |
Bun 1.4+ and Node.js 22.3+ on PATH; acdev test and projects that use bun need Bun |
runtime |
The runtime binary acdev dev would run (ACDEV_RUNTIME, else libexec/acdev of the install), and whether it runs |
contract level |
Whether the runtime runs the contract level this acdev builds, and whether it is the release this acdev pairs with |
gpu, display |
The runtime binary's own check (libexec/acdev doctor): the GPU (it draws a small frame and reads it back), and on Linux whether a host window can open |
acdev dev sessions, approval |
The running acdev dev sessions, and every camera or microphone prompt that waits for an answer |
project |
acdev check of the project |
platform |
Whether this platform has every capability the project's apps require |
dependencies |
The project's dependencies are installed (also when a workspace keeps them in a parent directory), its runtime is on PATH, and its @dopame/acde-api (in package.json and installed) is the version this acdev is built with; an older SDK is reported here once, fixed by acdev sdk update (followed by the directory when acdev doctor was given one) |
git |
Whether git ignores .acde/ |
agent skill |
Whether the acdev skill is installed for coding agents and current |
latest release |
With --online: whether a newer acdev is out |
Common findings
Section titled “Common findings”No runtime:
error runtime: acdev dev needs the Dopame runtime (libexec/acdev of an install) and found none: no /Users/me/.acdev/versions/X.Y.Z/libexec/acdev, which the acdev installer puts there: run the installer again, or set ACDEV_RUNTIME to the runtime binary (target/release/acdev of an acdev checkout) fix: run the installer again: curl -fsSL https://pkgs.dopame.ai/acdev/install.sh | sh (it puts the acdev runtime that pairs with acdev next to it)A runtime that does not start reports why: a missing system library (it exited with code 127: … error while loading shared libraries: …), a file that is not executable (EACCES), or on macOS a binary that a download left in quarantine, with xattr -d com.apple.quarantine <path> as the fix.
A runtime that cannot draw is an error of the gpu check, with the same reason acdev dev would log at startup after web layer unavailable:. On Linux without the GPU's Vulkan driver:
error gpu: the system has a GPU (card0, kernel driver xe) but no usable Vulkan driver was found: install the GPU's Vulkan driver (for example vulkan-intel, vulkan-radeon, nvidia-utils) or point VK_DRIVER_FILES at its ICD (wgpu: No suitable graphics adapter found; …)Install the driver (see The runtime). With only a software driver (lavapipe), gpu is a warning: pages render on the CPU, and a page that animates the whole screen (a live wallpaper) shows only a few frames a second. When it works, the line names the GPU, the graphics API and the driver, such as ok gpu: Intel(R) Graphics (PTL) (Vulkan, integrated GPU, driver Intel open-source Mesa driver Mesa 26.2.5-arch3.1): drew a test frame in 41 ms.
On Linux in a shell with no graphical session (over SSH, for example):
warn display: neither WAYLAND_DISPLAY nor DISPLAY is set, so acdev app and acdev desktop cannot open a host window here: they would try to start a session on the screen (DRM) instead fix: run acdev dev --headless, or run it inside a graphical sessionA camera or microphone prompt that waits:
warn approval: recorder waits for approval of microphone in acdev dev 4242, so its getUserMedia waits until the prompt is answered fix: acdev allow (or acdev deny): approving is the user's decisionFix what it can
Section titled “Fix what it can”acdev doctor --fix runs the checks, prints them, then fixes what it can and checks again:
| Fix | When | Asks first |
|---|---|---|
acdev skills install |
The acdev skill is not installed for any coding agent, or an installed one is outdated or broken | No |
Add .acde/ to the project's .gitignore |
git does not ignore the build output | No |
| Remove and make again the sessions directory | It is a link or a file, not a directory | No |
Run the installer of this acdev version again (install.sh --version <this version> --no-modify-path, install.ps1 -Version … -NoModifyPath on Windows) |
The runtime next to acdev is missing, does not run, or is of another contract level or release; only for an installed acdev, and not when ACDEV_RUNTIME names the runtime |
Yes: it downloads the runtime and replaces the install, all or nothing, as the installer always does |
The project's install (bun install, npm install, …) |
Its dependencies are not installed | Yes: it downloads packages and runs their install scripts |
acdev stop --session <pid> |
A running acdev dev does not answer |
Yes: it ends a process you started |
In a terminal it asks about each fix in the last column. Without a terminal (a script, a coding agent) it skips them and says so, skipped: … (it asks first: pass --yes to allow it), unless it is given --yes. A coding agent passes --yes only when the user agreed.
It never touches what is the user's to decide: a camera or microphone prompt, a GPU driver or a system library, a binary in macOS quarantine, another acdev on PATH, the project's code and config. Those keep their fix: line.
fixing: install the acdev skill for the coding agents found here (acdev skills install)acdev: skill linked to /Users/me/.agents/skills/acdev (Cline, Codex, …)fixed: install the acdev skill for the coding agents found here (acdev skills install)skipped: install the project's dependencies (bun install in /Users/me/notes) (it asks first: pass --yes to allow it)acdev doctor: after fixing:ok acdev: X.Y.Z on Bun 1.4.4 (/Users/me/.acdev/versions/X.Y.Z)…acdev dev points here
Section titled “acdev dev points here”When acdev dev finds no runtime, its error ends with (acdev doctor checks the whole setup). When the runtime exits before the session is ready, acdev dev prints the runtime's log line and then:
acdev: acdev runtime exited (1) before it was ready; acdev doctor checks the runtime, the GPU and this setupIn scripts and agents
Section titled “In scripts and agents”acdev doctor --json prints one object:
{ "ok": false, "checks": [ { "id": "runtime.binary", "title": "runtime", "status": "error", "summary": "…", "fix": "…" } ]}ok is false when a check is an error. A check that --fix can repair carries "repair": {"action", "target", "ask", "does"} (ask is true for the fixes that ask first), and with --fix the object also has "fixed": [{"repair", "result", "said"}], result being fixed, failed or skipped; the progress lines then go to stderr. The ids are acdev, path, runtimes, runtime.binary (the runtime binary; its title is runtime), contract, runtime (when the runtime's own check cannot run), runtime.host, runtime.gpu, runtime.display, sessions, approval, project, platform, dependencies, gitignore, skill and latest; fix is left out when there is none. The MCP server has the same check as its doctor tool, and the fixes that do not ask as doctor_fix (it names the others and leaves them to the user); see MCP.
The runtime's part also runs on its own: the runtime binary's doctor (libexec/acdev doctor, or libexec/acdev doctor --json, in the install directory), with the same exit codes.