> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dotbot.ch/llms.txt
> Use this file to discover all available pages before exploring further.

# Project health checks with dotbot doctor

> Run dotbot doctor to scan for stale locks, orphaned worktrees, missing dependencies, and task queue issues — with remediation steps for each.

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:

```powershell theme={null}
dotbot doctor
```

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 |

<Tip>
  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.
</Tip>

## What doctor checks

### Dependencies

Verifies that the required tools are present on your PATH:

* **git** — required for worktree management and version control
* **Coding-agent CLI** — at least one of `claude`, `codex`, `agy` (Antigravity), `opencode`, or `copilot` must be present. `gh` also counts, since it can run the preview `gh copilot`.

A missing coding-agent CLI is a hard failure.

### Settings integrity

Resolves the merged settings for the project and confirms the result carries both the `execution` and `analysis` configuration blocks. Also checks that `theme.default.json` is valid JSON if present. Settings that cannot be resolved prevent 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 the project's PowerShell scripts — the CLI scripts under `.bot/src/cli/` and any workflow scripts materialised in `.bot/content/workflows/` — for `Write-Host` calls and direct `[Console]::Error.Write` traces. Both bypass dotbot's themed output helpers and can produce noisy or unparseable terminal output, so doctor flags each occurrence with its file and line number.

## 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:

```powershell theme={null}
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:

```powershell theme={null}
git worktree prune
```

Run `dotbot doctor` again to confirm the warning is cleared.

### 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 bootstrap installs a small PATH shim that reads `$env:DOTBOT_HOME` and runs the CLI from your checkout. On Windows the shim is placed in `%LOCALAPPDATA%\Microsoft\WindowsApps`, which is already on PATH on Windows 10 and later; on macOS and Linux it goes in `~/.local/bin`. Either way, the new PATH entry and the `DOTBOT_HOME` variable only take effect in shell sessions started after the install.

On Windows, if PowerShell blocks dotbot scripts with an execution policy error, run the following and then retry:

```powershell theme={null}
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```