Install, Update and Doctor
Level 1 · Get started
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 contentsLesson 2 of 17
Level 1 · Get started
Level 2 · Inside a conversation
Level 3 · Parallel work and review
Level 4 · Setup and extensions
Level 5 · Scripts and servers
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
12 mincovers 9 glossary entries
Worth reading first: Slash Commands and the CLI
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.
claude install stable
claude doctor
claude --safe-mode
claude purge ~/work/old-repo --dry-runWorked 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.
The words for this lesson9
Check yourself
Claude Code will not start at all. Which checkup can you still run?
Finished this lesson?
Marking it complete also marks its 9 glossary entries learned, which updates your roadmap and your saved page. 0 are already marked.