Skip to content
BENIBIX Learn

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

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.

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 reads four places, then waits for your yes. claude doctor in the shell only reads.

Worked 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.