# Install, Update and Doctor

> How Claude Code gets new versions, and how to pin one. Then the checkups to run when it misbehaves, from claude doctor to safe mode and a bug report.

**Course:** [Claude Code Commands](https://learn.benibix.com/learn/ai-claude-code-commands)  
**Time:** 12 min

**After this lesson you can:**

- Move to a set version with claude install
- Pick claude doctor or /doctor for a fault
- Find a broken add-on with --safe-mode

## How to update Claude Code, and check it when it breaks

A native install of Claude Code updates itself in the background. claude update fetches a new version right now. claude install moves to a version you name: an exact number such as 2.1.118, stable, or latest. Stable is usually about a week old and skips releases with big faults.

An update does not reach a session that is already open. That session keeps the old version until it restarts. /restart closes it and opens it again with the same chat. It needs a personal Claude plan and a native install on macOS or Linux. Its other name is /update.

Not every install updates itself. A Homebrew install waits for you to run Homebrew's own upgrade. If claude -v still shows the old number after an update, check how you got Claude Code in the first place.

When something is wrong, there are two checkups with one name. claude doctor runs in your shell, with no session. It only reads: install health, settings files with mistakes, and whether Remote Control can work here. /doctor runs inside a session. It checks the install, settings, add-ons and CLAUDE.md, then offers fixes.

The rule is simple. If Claude Code will not start, use claude doctor, because /doctor needs a session to run in. If it starts but acts oddly, use /doctor, because it can also fix what it finds. It changes nothing until you say yes. Its other name is /checkup.

If an add-on is to blame, --safe-mode proves it. It starts Claude Code with CLAUDE.md, skills, plugins, hooks, MCP servers, themes and auto memory all left off. Sign-in, the model, the built-in tools and your permissions still work. If the fault goes away, one of your add-ons caused it.

For a fault that comes and goes, /debug turns on a debug log from that moment and reads it for you. Add a few words about the problem to point it the right way. /bug sends a report about a problem, after a screen shows you what goes with it. /feedback sends a note about the product.

claude purge is the last resort for one project. It deletes what Claude Code keeps for it: chat transcripts, task lists, debug logs, edit history and prompt history. Add --dry-run first to see the list. Add --all and it clears every project, so read that list twice.

```bash
claude install stable
claude doctor
claude --safe-mode
claude purge ~/work/old-repo --dry-run
```
Pin stable and check the install. Then start with add-ons off, and see what a purge would delete.

![/doctor checks four places: the install, the settings files, the extensions and CLAUDE.md. It proposes a fix, such as repair line 12. A yes leads to fixed, and a no leads to nothing changes. A note says to run claude doctor in the shell if Claude Code will not start at all.](https://learn.benibix.com/diagrams/cmd-doctor.svg)

### Example: Jack's session will not start

Jack updates, and Claude Code exits the moment it opens. /doctor is no use, because there is no session to type it in.

He runs claude doctor in his shell. It names one settings file with a stray comma on line 12. He fixes the comma, and Claude Code starts again.

**Words in this lesson:** [claude install Command](https://learn.benibix.com/term/ai/claude-install-command), [claude update Command](https://learn.benibix.com/term/ai/claude-update-command), [/restart Command](https://learn.benibix.com/term/ai/restart-command), [claude doctor Command](https://learn.benibix.com/term/ai/claude-doctor-command), [/doctor Command](https://learn.benibix.com/term/ai/doctor-command), [--safe-mode Flag](https://learn.benibix.com/term/ai/safe-mode-flag), [/debug Command](https://learn.benibix.com/term/ai/debug-command), [/feedback Command](https://learn.benibix.com/term/ai/feedback-command), [claude purge Command](https://learn.benibix.com/term/ai/claude-purge-command)

**Question:** Claude Code will not start at all. Which checkup can you still run?

**Answer:** claude doctor, in your shell. Every slash command needs a running session. claude doctor runs from the shell, reads the install and the settings files, and names what is wrong.

---

Source: https://learn.benibix.com/learn/ai-claude-code-commands/install-update-and-doctor
Author: Behnia Zarei (a developer in Vienna, Austria, who builds and teaches data, AI and business intelligence at BENIBIX)
Publisher: BENIBIX Learn (https://learn.benibix.com/)
Last updated: 2026-11-19
Licence: CC BY 4.0 (https://creativecommons.org/licenses/by/4.0/). Quote freely with attribution.
