Over time, interrupted AI sessions or abrupt process terminations can leave a dotbot project in an inconsistent state — stale lock files, worktrees pointing to deleted paths, or task files with malformed JSON. The dotbot doctor command scans your project for these issues and reports a clear pass, warn, or fail for each check category.
Running the health check
Run dotbot doctor from your project root — the directory that contains the .bot/ folder:
The command exits with one of three codes:
| Exit code | Meaning |
|---|
0 | All checks passed — no issues found |
1 | One or more warnings — project can run but attention is recommended |
2 | One or more errors — project may not run correctly until issues are resolved |
Run dotbot doctor after any unexpected crash or process kill, and before retrying a stalled workflow. It is also a good habit to run it after pulling changes that include .bot/ updates from a teammate.
What doctor checks
Dependencies
Verifies that the required tools are present on your PATH:
- git — required for worktree management and version control
- Provider CLI — at least one of
claude, openai (Codex), or gemini must be present
- powershell-yaml — PowerShell module required by the MCP server for YAML parsing
A missing provider CLI is a hard failure. A missing powershell-yaml module is a warning, and doctor prints the install command inline.
Settings integrity
Parses settings.default.json and confirms it is valid JSON containing both the execution and analysis configuration blocks. Also checks that theme.default.json is valid JSON if present. A malformed settings file prevents dotbot from starting any workflow.
Stale process locks
Scans .bot/.control/launch-*.lock files and checks whether the PID recorded in each lock file corresponds to a currently running process. Lock files whose PIDs are no longer alive are reported as stale. They prevent new workflow runs from starting and must be deleted manually.
Orphaned worktrees
Reads the worktree map at .bot/.control/worktree-map.json and verifies that every recorded worktree path still exists on disk. Entries pointing to missing paths indicate worktrees that were cleaned up outside of dotbot’s normal flow — for example, by a manual git worktree remove or a file system operation.
Task queue health
Walks every JSON file under .bot/workspace/tasks/ and checks for:
- Invalid JSON — files that cannot be parsed (reported as errors)
- Missing required fields — task files without an
id or name field (reported as warnings)
A corrupted task file can cause a workflow to fail partway through, so addressing these before a run is recommended.
Output hygiene
Scans PowerShell scripts in your project’s hook and workflow directories for patterns that may produce noisy or unparseable terminal output. Scripts with issues are flagged so you can update them before they cause problems during task execution.
Common issues and fixes
Stale lock files
Symptom: Doctor reports PID XXXXX no longer running (stale) for one or more lock files.
Fix: Delete the stale lock files manually:
Remove-Item .bot\.control\launch-*.lock
Orphaned worktrees
Symptom: Doctor reports path missing: ../worktrees/... for a worktree entry.
Fix: Remove the stale entry from dotbot’s worktree map, then prune git’s own worktree list:
Run dotbot doctor again to confirm the warning is cleared.
Missing powershell-yaml module
Symptom: Doctor reports powershell-yaml missing.
Fix: Install the module for the current user:
Install-Module powershell-yaml -Scope CurrentUser
Invalid task JSON
Symptom: Doctor reports task files with invalid JSON.
Fix: Open the affected file in .bot/workspace/tasks/ and repair or remove it. Doctor prints the file name alongside the error, so you can locate it directly.
When to run doctor
Run dotbot doctor in these situations:
- After a crash — any time dotbot or an AI provider process exits unexpectedly
- Before retrying a workflow — to confirm no residual locks or corrupted tasks will block the run
- After pulling team changes — when a colleague’s
.bot/ updates land in your working tree
- When a workflow starts but immediately stalls — stale locks are a common cause of this pattern
Troubleshooting installation issues
If the dotbot command is not found after installation, restart your terminal. The installer adds ~/dotbot/bin to your PATH, but the change only takes effect in new shell sessions.
On Windows, if PowerShell blocks dotbot scripts with an execution policy error, run the following and then retry:
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser