Installing Claude Code and Connecting Your First Project
Claude Code is installed once from your terminal, then launched from inside any project directory you want it to work on.
This page walks through that setup end to end: install, connect to a real project, and run a first request.
Summary
Installing Claude Code is a single CLI command, similar to installing any other global developer tool.
Once installed, the CLI has no persistent connection to a project until you launch it from inside that project's directory.
Each session starts fresh in whichever folder you were in when you typed the launch command.
The first session in a new project is a good moment to let Claude Code orient itself before asking for anything complex.
Getting this initial setup right avoids most of the confusion new users run into in their first week.
Recipe
Quick-reference recipe card - copy-paste ready.
# 1. Install the CLI globally
npm install -g @anthropic-ai/claude-code
# 2. Confirm it installed
claude --version
# 3. Move into the project you want help with
cd ~/projects/my-app
# 4. Launch the interactive session
claudeWhen to reach for this:
- The first time you set up Claude Code on a new machine.
- Connecting Claude Code to a project it has not worked in before.
- Onboarding a new developer onto a team that already uses Claude Code.
- Reinstalling after switching machines or updating your Node.js toolchain.
Working Example
# A full first-session walkthrough, from a clean terminal
# Install the CLI (Node.js and npm must already be installed)
npm install -g @anthropic-ai/claude-code
# Verify the install
claude --version
# Navigate into the project you want to connect
cd ~/projects/my-app
# Launch Claude Code in that project
claude
# At the prompt that opens, describe your first task in plain language
> Summarize what this project does and list its main dependenciesWhat this demonstrates:
- The install step is a one-time, global action independent of any specific project.
- Connecting to a project is just a matter of
cd-ing into it before launching. - A good first request asks Claude Code to summarize or orient, which lets you sanity-check that it read the project correctly.
- The session opens a REPL prompt (
>) where every subsequent request is typed.
Deep Dive
How It Works
- The CLI itself is a small binary; the actual agent work happens in a session that starts once you run
claudefrom a directory. - On launch, Claude Code reads the current working directory as the project root and begins building context about it.
- There is no separate "connect" step beyond launching from the right folder; the CLI does not require you to register a project ahead of time.
- Authentication happens once per machine (or session, depending on your setup) and is separate from the per-project connection step.
First-Session Checklist
| Step | Why it matters |
|---|---|
Confirm claude --version works | Confirms the install and PATH are correct before you rely on it |
cd into the actual project root | Claude Code reads from the current directory, not a path you type later |
| Ask an orientation question first | Confirms it read the project correctly before you hand off real work |
| Pick a starting permission mode | Decide up front whether you want approval prompts on this first session |
CLI Notes
# Update to the latest version later on
npm update -g @anthropic-ai/claude-code
# Check where the binary is installed if `claude` is not found
npm root -gGotchas
- Launching from the wrong directory - Claude Code reads the current working directory as the project root, so launching from your home folder instead of the project folder gives it the wrong context. Fix: always
cdinto the actual project root before runningclaude. - Assuming install connects it to a project automatically - installing the CLI is global and project-agnostic; it does not remember or attach to any specific project until you launch it from inside one. Fix: treat every
claudelaunch as a fresh connection scoped to the current directory. - Skipping the version check - a broken
PATHafter install can silently makeclauderesolve to nothing or an old cached version. Fix: runclaude --versionimmediately after installing, before starting real work. - Jumping straight into a complex request - asking for a large multi-file change before Claude Code has any context on the project produces a weaker plan. Fix: start with a small orientation request so it reads relevant files first.
- Forgetting Node.js is a prerequisite - the CLI installs via
npm, so a missing or very old Node.js install will cause the install command to fail outright. Fix: confirmnode --versionandnpm --versionwork before installing Claude Code.
Alternatives
| Alternative | Use When | Don't Use When |
|---|---|---|
Launch with claude and no flags | You want your configured defaults for permission mode | You need a specific permission mode just for this session |
| Launch with an explicit permission flag | You want to be sure of the mode for a one-off session | You already have a project-level default you trust |
| Reinstall from scratch | Your install is broken or badly out of date | A simple npm update -g would fix the same problem faster |
FAQs
Do I need to install Claude Code separately for every project?
No. The install is global, done once per machine. Connecting to a specific project just means launching claude from inside that project's directory.
What do I need installed before I can install Claude Code?
- Node.js and npm, since the CLI installs as an npm global package.
- A terminal you can run commands in.
- An Anthropic account with access to Claude Code for authentication.
How do I know the install actually worked?
Run claude --version right after installing. A version number back confirms both the install and your PATH are correct.
What happens if I launch `claude` from the wrong folder?
Claude Code treats whatever directory you launched from as the project root, so it will read and reason about the wrong files. Exit, cd into the correct project, and relaunch.
What should my very first request be in a new project?
Something low-stakes and orienting, like asking it to summarize the project or list its dependencies. This confirms it read the project correctly before you hand off real work.
Is there a project-level config file, or is everything per-session?
Project-level configuration exists for things like permission defaults, but the core connection step is simply launching from the project directory each time; there is no separate registration step.
Can I use Claude Code on more than one project at a time?
Yes, but each session is scoped to the directory you launched it from. Working across two projects at once means running two separate sessions, typically in two terminal tabs.
Do I need to choose a permission mode before my first session?
It helps. Deciding up front whether you want ask-every-time or auto-accept for that first session avoids surprises, especially in an unfamiliar or important codebase.
How do I update Claude Code after it's installed?
npm update -g @anthropic-ai/claude-codeRun claude --version afterward to confirm the update took effect.
What if `claude` is not found after installing?
This usually means the global npm bin directory is not on your shell's PATH. Run npm root -g to find where global packages install, and confirm the corresponding bin directory is on your PATH.
Does installing Claude Code require sudo or admin rights?
It depends on how your npm global installs are configured on your machine. If you hit permission errors, that is a sign your npm global directory needs adjusting rather than something specific to Claude Code.
Related
- Claude Code 101 Basics - a fuller set of first-session examples beyond install and connect.
- The Claude Code Mental Model: Agent, Not Autocomplete - what to expect once your first session is running.
- Navigating the Claude Code REPL: Prompts and Slash Commands - how to use the session once it's connected.
- Permission Modes Explained: Auto-Accept vs Ask-Every-Time - decide your starting mode before your first real request.
Stack versions: Written against the Claude model lineup current as of ~June 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (the default), and Claude Haiku 4.5. Model names, pricing, and product features move quickly - verify current specifics at platform.claude.com/docs before relying on them.