The ButlerUseful technology. Clearly explained.
Home / AI setup guides
The Butler field guides

Claude Code: a first project without a complicated setup

Use the desktop interface or native installer, understand account choices, and verify a small change before expanding access.

Documentation checked November 14, 2026. Installation paths have not all been hands-on tested. Follow the linked official requirements if they change.

What this is for

Claude Code helps you work inside a real code project rather than only generating snippets. For a first session, choose a project you can safely restore. Avoid starting with a production server, a folder of private documents or a vague instruction to “fix everything.” A focused task makes it much easier to tell whether the tool is useful and whether its changes are correct.

The graphical route

If terminals are unfamiliar, use the official desktop guide and its platform download links. Sign in, select the Code interface and choose the project folder. Keep the first session local rather than adding remote machines or services. The desktop interface is an alternative starting point; you do not have to install a separate CLI just to follow a terminal tutorial.

The terminal route

The documented baseline includes macOS 13+, Windows 10 version 1809+, Ubuntu 20.04+ or Debian 10+, with at least 4 GB RAM and internet access. Check the complete platform requirements for other distributions.

These native installers execute downloaded code. Review the official source and choose only your system's command.

Windows PowerShell

irm https://claude.ai/install.ps1 | iex

macOS, Linux or an existing WSL terminal

curl -fsSL https://claude.ai/install.sh | bash

Run the WSL command inside the Linux distribution, not PowerShell. Native Windows installation does not require Administrator. Git for Windows is optional; it adds Git Bash support.

Confirm it works and sign in

claude --version
claude doctor

The first command should print a version; the second reports installation and settings diagnostics. Native installs update automatically; package-manager installs have different update steps. See setup and maintenance.

From your project folder, run claude and complete the browser sign-in. The quickstart lists eligible Claude subscriptions, Console billing and supported cloud-provider routes. Select the account you intend to pay with. A configured API key can change that choice; do not assume an existing consumer subscription covers arbitrary API requests. Our billing guide separates the options.

Try this first

  1. Back up the project or make a Git checkpoint.
  2. Ask: “Identify the starting page and explain how to run this project. Do not edit files.”
  3. Compare the response with the folder you selected.
  4. Ask for one visible change, such as improving a button label, without changing behavior.
  5. Review the diff, run the suggested relevant checks and open the page.

Expected result: a clear explanation of your project and a small change you can inspect. If the tool cannot run a check, that should be reported as untested, not passed. Keep the original until you are satisfied.

Common first-session mistakes

A missing command after installation can mean your old terminal has not picked up the new path; reopen it before retrying. A project that will not run may need its own dependencies, not a new Claude installation. A billing or usage-limit message is not a reason to keep reinstalling either. Record the exact error without including credentials, then use the official diagnostics.

Keep permission prompts meaningful. Allow only the folder and actions needed for the task, avoid copying secrets into chat, and review third-party plugins before installation. Before uninstalling or clearing configuration, preserve anything you want to keep and follow the instructions for your actual installation method. The Butler checked documentation for this guide; it has not performed every platform installation.

Official references

Choose another guide