Getting Started with Claude Code: Your First Session

You need a terminal, a project to work in, and one of: a Claude Pro, Max, Team, or Enterprise subscription; a Claude Console account (pay-as-you-go API credits); or access through Amazon Bedrock, Google Cloud, or Microsoft Foundry.

Install with the native installer, which Anthropic recommends:

1# macOS, Linux, WSL2curl -fsSL https://claude.ai/install.sh | bash3 4# Windows PowerShell5irm https://claude.ai/install.ps1 | iex

Alternatives are brew install --cask claude-code on macOS and winget install Anthropic.ClaudeCode on Windows. Open a new terminal and run claude --version. If the shell says claude is not found, the install directory is not on your PATH yet.

Then start Claude Code inside a project and log in:

1cd ~/code/my-project2claude

On first use Claude Code opens a browser to log in. Credentials are stored, so you do this once. Use /login later to switch accounts. If ANTHROPIC_API_KEY is set in your environment, Claude Code asks whether to use it, and if you approve it skips the browser login and bills that key instead of your subscription.

Claude Code reads files as it needs them, so you do not paste code in. The safest first prompts change nothing:

1what does this project do?2where is the main entry point?3how are the tests run, and do they pass right now?

Questions like these show you how Claude searches the codebase, which files it opens, and whether it understands the build. They also tell you how far to trust its later edits.

Next, run /init. It writes a starter CLAUDE.md based on the project. Claude reads that file at the start of every session, so it is where you put what Claude cannot work out from the code: the exact test and build commands, conventions that differ from the defaults, and gotchas.

1# Commands2- Test: pnpm test -- --run3- Typecheck: pnpm tsc --noEmit4 5# Conventions6- Use the logger in src/lib/log.ts, never console.log7- New API routes need a test in tests/api/

Keep it short. Anthropic's guidance is to ask of each line whether removing it would cause mistakes, and to cut it if not. A long CLAUDE.md gets parts of it ignored. Run /context to confirm the file loaded, and commit it so the team shares it.

The permission mode decides what Claude can do without asking. Press Shift+Tab to cycle modes; the status bar shows the current one.

• Manual (default): asks before file edits, most shell commands, and MCP tools.
• acceptEdits: edits files without asking, still asks for commands.
• plan: reads and plans, makes no changes.
• auto: a separate classifier model reviews actions and blocks those that look risky, such as reaching beyond the task or touching unknown infrastructure. Routine work runs without prompts.

With Claude Code v2.1.283 or later, auto mode is the starting mode for interactive terminal and VS Code sessions. That surprises people who expect a prompt before every command. If you want to approve each edit and command yourself while you learn, switch to Manual with Shift+Tab, or start with claude --permission-mode default.

Whatever the mode, you can pre-approve commands you trust and forbid things you never want with permission rules in .claude/settings.json:

1{2  "permissions": {3    "allow": ["Bash(pnpm test *)", "Bash(pnpm tsc *)"],4    "deny": ["Read(./.env)", "Read(./.env.*)"]5  }6}

Rules are covered in depth in Claude Code Permissions, and the modes in Claude Code Auto Mode.

Claude stops when the work looks done. Without something that returns pass or fail, you are the only check. Anthropic's best-practices page puts this first: give Claude a test, a build, or a script it can run, and it will run it, read the result, and keep going until it passes.

Compare two prompts for the same task:

1# vague: success is "looks done"2add email validation to signup3 4# checkable: success is a passing test5add a validateEmail function in src/lib/validate.ts.6user@example.com is valid; "invalid" and user@.com are not.7add these as tests, run pnpm test, and fix any failures.

For a change that touches several files or code you do not know, separate thinking from editing. Switch to plan mode, ask Claude to read the relevant code and propose a plan, and press Ctrl+G to edit the plan yourself. Then leave plan mode (approve the plan or press Shift+Tab) and let Claude implement it and run the tests. Finish by reading the diff before you ask for a commit.

Planning has a cost. For a typo, a log line, or a rename, ask directly. A useful rule from the docs: if you could describe the diff in one sentence, skip the plan.

Mistakes are cheap if you know the controls:

• Esc stops Claude mid-turn. Context is kept, so you can redirect it.
• Esc twice, or /rewind, opens the rewind menu. Every prompt you send creates a checkpoint, and you can restore the code, the conversation, or both to any of them, or summarise part of the conversation.
• /clear resets the conversation. Use it between unrelated tasks.
• claude -c continues the most recent conversation in the directory; claude -r lets you pick an older one. /rename gives a session a name you can find later.

Checkpoints have a hard limit: they only track edits made through Claude's file-editing tools. Files changed by a Bash command, an npm install, a database migration, or a push are not restored by a rewind. That is why the docs say checkpoints are not a replacement for git. Commit before you ask for anything large, and you can always get back with git.

The other common failure is a cluttered session. If you have corrected Claude twice on the same problem, the context is full of failed attempts. /clear and write a better first prompt that includes what you learned; a fresh session with a clear prompt usually beats a long one.

Every surface uses the same Claude Code engine, so your CLAUDE.md files, settings, and MCP servers apply in all of them. The differences are where the code runs and how you review changes. The terminal, IDE extensions, and the desktop app work on files on your machine. The web and mobile app run sessions in Anthropic-managed cloud environments against a cloned repository.

Sessions can move between surfaces. claude --teleport pulls a web or mobile session into your terminal, /desktop hands the current terminal session to the desktop app, and Remote Control lets you keep driving a local session from your phone or a browser. Teleport and the /desktop handoff need a claude.ai subscription.

Each surface has its own guide on this site: VS Code, JetBrains, Desktop app, web sessions, and mobile.

Use a small repository with a working test command.

1. Install, run claude --version, start claude in the repository, and log in. 2. Ask: "what does this project do, how are tests run, and do they pass?" Check the answer against what you know. 3. Run /init, then cut the generated CLAUDE.md to the lines Claude could not have guessed. Confirm it loaded with /context. 4. Check the mode in the status bar. Switch to Manual with Shift+Tab for this exercise. 5. Commit, then ask for a small change with a test as the check, using the "checkable" prompt pattern above. Approve the edit and the test run when prompted. 6. Press Esc twice, rewind the code to before the change, and confirm with git status that the working tree is clean again.

Pass criterion: Claude's description of the test command matches reality, the change ends with a passing test run you can see in the transcript, and the rewind leaves no edited files behind.