Troubleshooting

This page maps devkit symptoms to safe fixes. Start with devkit status and devkit doctor.

bash

devkit status     # version, source/channel, sync age, missing tools
devkit doctor     # deep check: symlinks, personal config, tools
devkit version    # installed versions

Symptom, cause and fix

Symptom	Cause	Fix	Verify
Signature or checksum error	Artifact incomplete, changed, or from the wrong source	Check devkit config show, then devkit sync. If it still stops, do not bypass it.	devkit status shows the expected version
Skills or agents missing	Sync incomplete	devkit sync, then devkit doctor.	devkit list skills shows entries
Personal skill seems overwritten	Name collision; the guard kept your file and left the shared one inactive	Rename one of the two.	devkit doctor reports no collision
Config is stale	Background fetch not applied yet	devkit sync.	Sync age is fresh in devkit status
Tool missing, such as gitleaks	Not installed	devkit tools --outdated, then devkit tools --upgrade.	No missing tools in devkit status
Tool has the wrong version	An older binary comes first in PATH	Compare which -a <tool>, remove the foreign npm/nvm/volta/brew copy, then devkit sync.	<tool> --version matches the pin
Regression after update	New version is unwanted	devkit rollback or devkit rollback <version>.	devkit status shows the target
Hooks do not fire	Hooks not wired	devkit sync; devkit hook-install wires only the hooks.	Expected hook output appears
Need to switch the setup off	Debugging, foreign machine or foreign repository	devkit off removes links and hooks but keeps version and config; devkit on restores them.	devkit status says off
Doctor says a default MCP server is disabled	/mcp wrote it to disabledMcpServers; claude mcp remove does not clear that	Re-enable it in /mcp.	devkit doctor no longer names it
devkit init reports foreign-context7	Hand-maintained Context7 entry in the project .mcp.json	At a terminal devkit init asks whether to replace it (default yes); otherwise devkit init --replace-context7 removes only that block, the global server stays.	The next run reports no Context7 work
Startup warns about Write(...) permissions	Legacy Write(path) rule	devkit init removes it where Edit(path) exists.	No warning at startup
Neither od nor devkit responds	The command became devkit in v0.12.0 and the PATH links reconcile at the next session start	~/.onedot-devkit/current/bin/devkit bin-reconcile. Do not re-run the installer; it fetches and syncs immediately.	which -a devkit shows one entry
git push stops with sandbox proxy refused SSH auth to github.com	The Claude Code sandbox proxy passes only HTTP(S), never SSH	Once per machine: git config --global url."https://github.com/".insteadOf "git@github.com:", then gh auth setup-git.	git push --dry-run passes
Auto mode keeps prompting for a read-only command	The command is not on the default allowlist	After real usage, /fewer-permission-prompts writes a prioritized allowlist from the project transcripts into .claude/settings.json.	The command runs without a prompt

The macOS menu bar switch has its own page with its symptom table.

Set up or update a project

devkit init sets up a project checkout for devkit — new, or from an older devkit version — one Git checkout per call. Git is required because Git is the undo.

bash

devkit init --dry-run   # shows the plan
devkit init             # applies it
devkit init --dry-run   # verifies: "Nothing to do"

It strips dangling .hooks entries whose script is gone (PROJECT_HOOK_DANGLING/PROJECT_HOOK_STRIPPED), removes stale model pins — Opus and Sonnet ID pins alike, no longer normalized to an alias — and Write(X) permission rules, ignores agent-state caches, moves a legacy spec tree, rebuilds .agents/context/ and the managed block in AGENTS.md, and turns CLAUDE.md into the one-line @AGENTS.md import. A local skill file naming a script under .claude/scripts/ that no longer exists is reported as PROJECT_LOCAL_SKILL_DANGLING.

Projects set up by the old npx-ai-setup are no longer cleaned up: remove its leftovers, such as .ai-setup.json and the copied template files under .claude/ and .codex/, by hand.

Closing state	Meaning
clean	Nothing to do; the project is set up.
pending	The dry-run found changes; run devkit init without --dry-run.
applied	Changes were written.
attention	Nothing was written; a phase stopped short of your decision.

Full reset

bash

devkit unlink  # remove runtime and state; keep MCP client entries
curl -fsSL https://devkit.one-dot.io/install.sh | sh

The hosted installer performs fresh onboarding and repairs incompatible runtime contracts.