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

# doctor

> Diagnose session, log, and hook problems in a repository, and offer to fix them.

Diagnose problems in the current repository and offer to fix them.

```bash theme={null}
entire doctor [flags]
```

| Flag | Description |
| - | - |
| `-f, --force` | Fix all issues without prompting (condense if possible, otherwise discard) |

## What Doctor Checks

| Check | What it reports |
| - | - |
| Disconnected metadata branches | The local and remote `entire/checkpoints/v1` branches share no common ancestor. Doctor fixes this by cherry-picking local checkpoints onto the remote tip. |
| Operational logs | Entire cannot write to `.entire/logs`, so diagnostics may be missing. |
| Codex hook trust | Installed Codex hooks lack a `trusted_hash` entry in your Codex config. Review and approve them with `/hooks` in Codex. |
| Hook config drift | Installed agent hooks differ from the current CLI configuration. Run `entire enable --force` to reinstall them. |
| Stuck sessions | See [Stuck Sessions](#stuck-sessions) below. |

## Stuck Sessions

A session is considered stuck if:

* It is in ACTIVE phase with no interaction for over 1 hour
* It is in ENDED phase with uncondensed checkpoint data on a shadow branch

For each stuck session, you can choose to:

* **Condense**: Save session data to permanent [checkpoint storage](/guides/checkpoints/checkpoint-storage.md)
* **Discard**: Remove the session state and shadow branch data
* **Skip**: Leave the session as-is

Without a terminal to prompt on, such as an agent or CI, `entire doctor` reports each issue and points at `--force` instead of prompting.

## doctor migrate-checkpoints

Convert the checkpoints on the `entire/checkpoints/v1` branch into per-checkpoint refs under `refs/entire/checkpoints/<shard>/<id>`, the layout the ref-based backend uses.

```bash theme={null}
entire doctor migrate-checkpoints [flags]
```

| Flag | Description |
| - | - |
| `--dry-run` | Report what would be migrated without writing refs |
| `--remote NAME` | Remote to push migrated refs to. Defaults to the checkpoint sync remote |

Each checkpoint keeps its 12-character hex ID as the ref name, and its current tree is wrapped in a fresh commit. The command does not remap the existing branch commits and does not delete the branch. It skips checkpoints it has already converted, so re-running it after more branch activity is safe.

Run it while the branch backend is still primary. Once `checkpoints.primary.type` is `git-refs`, the command reports that there is nothing to migrate and exits, because the refs are authoritative at that point.

New refs are queued for push. Run interactively, the command asks whether to push them now. Run without a terminal, it leaves them queued, and they flush on the next `git push` once the ref-based backend is primary.

> [!NOTE]
>
> Migration is optional. See [Both Backends Stay Readable](/guides/checkpoints/checkpoint-storage.md#both-backends-stay-readable) for how readers resolve branch-backed checkpoints after a switch.

## doctor logs

Show recent operational logs.

```bash theme={null}
entire doctor logs [flags]
```

| Flag | Description |
| - | - |
| `-f, --follow` | Stream new log lines as they are written |
| `--tail N` | Show the last N lines. Use `0` for all. Defaults to `100`. |

## doctor bundle

Produce a diagnostic bundle for bug reports.

```bash theme={null}
entire doctor bundle [flags]
```

| Flag | Description |
| - | - |
| `-o, --out PATH` | Path to write the bundle archive. Defaults to the OS temp directory. |
| `--raw` | Skip secret redaction. Use only when support has asked for an unredacted bundle. |

## doctor trace

Show hook performance traces for debugging slow Git operations.

```bash theme={null}
entire doctor trace [flags]
```

| Flag | Description |
| - | - |
| `--hook TYPE` | Filter by hook type, such as `post-commit`, `prepare-commit-msg`, or `pre-push` |
| `--json` | Output as JSON |
| `--last N` | Show the last N hook invocations. Defaults to `1`. |
| `--slow` | Only include traces flagged slow, meaning those logged at WARN |
| `--summary` | Aggregate across traces instead of showing each one, reporting which step dominates per hook. Uses `--last 200` unless you set `--last`. |

```bash theme={null}
# The most recent hook trace
entire doctor trace

# The last five post-commit traces
entire doctor trace --last 5 --hook post-commit

# Which step dominates, across the slow traces only
entire doctor trace --summary --slow
```

Hooks that take 1.5 seconds or longer are traced by default, at WARN level, so a slow hook records its own breakdown with no configuration. Set `ENTIRE_PERF_SLOW_MS=0` to turn that off. A `log_level` above WARN also hides them.

> [!NOTE]
>
> To trace every hook, including fast ones, raise verbosity: set `ENTIRE_LOG_LEVEL=DEBUG` in your shell profile, or add `"log_level": "DEBUG"` to `.entire/settings.json`.