Getting Started

What is Claude Code?

Claude Code is an AI coding assistant that lives in your terminal — the text-based window where developers type commands. Instead of clicking buttons in an app, you type what you want in plain English, and Claude reads your code, suggests fixes, writes new features, runs tests, and even manages files — all by understanding your project directly on your machine.

Before you can use any slash command or build a workflow, you need Claude Code running on your machine. This module walks you through installation, authentication, picking the right terminal and IDE setup, and running your very first session.

Prerequisites

Claude Code runs on macOS 13+, Ubuntu 20.04+ (and other modern Linux distros including Debian 10+ and Alpine Linux 3.19+), and Windows 10 1809+ (native or WSL). You need at least 4 GB of RAM and an x64 or ARM64 processor. An active internet connection is required at all times.

You also need an eligible Anthropic account — a Pro, Max, Ultra, Team, Enterprise, or Console account. The free Claude.ai plan does not include Claude Code access. Alternatively, you can use an API key from the Anthropic Console or connect through Amazon Bedrock, Google Cloud’s Agent Platform, or Microsoft Foundry.

On native Windows, Git for Windows is optional but recommended: when it’s installed, Claude Code uses Git Bash for the Bash tool. Without it, Claude Code runs commands through the PowerShell tool instead. When Git Bash is present, the PowerShell tool is available alongside Bash: on by default for claude.ai and Console accounts, and enabled with CLAUDE_CODE_USE_POWERSHELL_TOOL=1 in Amazon Bedrock, Google Cloud’s Agent Platform, and Microsoft Foundry sessions. Set it to 0 to turn the tool off.

Installing the CLI

The recommended way to install Claude Code is the native installer. It auto-updates in the background so you always have the latest version.

On macOS or Linux (including WSL):

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

On Windows via PowerShell:

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

On Windows via CMD:

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

The alternative installation methods differ in how they update. Homebrew, WinGet, apt, dnf, and apk installations do not auto-update by default, so upgrade them with your own tooling. An npm installation does auto-update, because Claude Code runs npm to update itself. Homebrew: brew install --cask claude-code (stable channel) or brew install --cask claude-code@latest (latest channel). WinGet: winget install Anthropic.ClaudeCode. npm: npm install -g @anthropic-ai/claude-code (requires Node.js 22+). On Linux, you can also use system package managers: sudo apt install claude-code (Debian/Ubuntu), sudo dnf install claude-code (Fedora/RHEL), or apk add claude-code (Alpine).

After installation, verify it worked:

claude --version

For a more detailed check of your installation and configuration, run claude doctor — it validates your setup, MCP servers, and settings.

You can control the update channel through /config — choose between latest (newest features) and stable (tested releases, about one week behind).

Authentication

When you run claude for the first time, it automatically opens your browser for OAuth authentication. Sign in with your Anthropic account and you’re ready to go.

If you’re using an API key instead, set the environment variable before launching:

export ANTHROPIC_API_KEY=sk-ant-...
claude

For enterprise or cloud provider setups, use the corresponding environment variables:

• Amazon Bedrock: CLAUDE_CODE_USE_BEDROCK=1
• Google Cloud’s Agent Platform: CLAUDE_CODE_USE_VERTEX=1
• Microsoft Foundry: CLAUDE_CODE_USE_FOUNDRY=1

Your credentials are stored securely — in the macOS Keychain on Mac (with a fallback to ~/.claude/.credentials.json mode 0600 when the Keychain is locked, e.g. over SSH), in ~/.claude/.credentials.json (mode 0600) on Linux, and in %USERPROFILE%\.claude\.credentials.json on Windows, where they inherit the access controls of your user profile directory.

To switch accounts or re-authenticate at any time, use /logout. You can also explicitly trigger authentication with claude auth login — it opens the browser OAuth flow, or if the browser can’t open, prints a URL you can paste into any browser and then paste the authorization code back into the terminal. Additional options include claude auth login --email to pre-fill your email, claude auth login --sso for SSO-enabled organizations, and claude auth login --console for API key authentication through the Anthropic Console.

Logins created with /login eventually expire. When yours is within three days of expiring, Claude Code shows a startup warning — Your login expires in 3 days · run /login to renew — and you renew by running /login. The warning is informational and never blocks a request: authentication keeps working until the login actually expires, after which every model request fails with Login expired · Please run /login until you sign in again. You can check ahead of a failure with /status, which shows a Login row reading Expired — log in again (Claude Code v2.1.210+). This applies only when a claude.ai login is the active credential — not when a cloud provider, ANTHROPIC_API_KEY, or apiKeyHelper supplies it. Renewing early matters most for unattended runs: a background or Remote Control session that outlives its login stops making progress until you sign in again.

Your Terminal: Warp Recommended

Claude Code works in any terminal — Terminal.app, iTerm2, Windows Terminal, Alacritty, Kitty, Ghostty, and more. But for the best experience, we recommend Warp.

Warp has an official Claude Code plugin that provides native desktop notifications when Claude completes a task, needs your input, or requests permissions. This is especially useful for long-running operations where you switch to another window.

To set up the Warp plugin, run these commands inside Claude Code after installation:

/plugin marketplace add warpdotdev/claude-code-warp
/plugin install warp@claude-code-warp

Restart Claude Code after installation to activate the plugin. You’ll get native OS notifications for task completions, idle states, and permission requests — no more checking back manually.

By default, Claude Code only sends desktop notifications in Ghostty, Kitty, and iTerm2. In any other terminal, set preferredNotifChannel to "terminal_bell" to ring the terminal bell instead, or configure a Notification hook for a custom sound. Shift+Enter for a newline also works without setup in most terminals; in VS Code, Cursor, Devin Desktop, Alacritty, and Zed, run /terminal-setup once to write that keybinding.

To pick how the interface shows the turn-end clock and the transcript-viewer timestamps, set timeFormat and timeZone in any settings file (Claude Code v2.1.257+). timeFormat accepts a 12-hour, 24-hour, or 24-hour-utc preset — pick these from /config under Time format — or any strftime pattern. timeZone accepts an IANA name such as "UTC" or "Europe/Dublin", and is ignored when timeFormat is "24-hour-utc". /config has no row for timeZone, so set it in a settings file:

{
  "timeFormat": "24-hour",
  "timeZone": "Europe/Dublin"
}

Where Claude Code Runs: IDEs, Desktop App & Web

Claude Code started as a CLI tool, but it isn’t terminal-only — it runs on several surfaces: the terminal, IDE extensions, a desktop app, and the web. Each surface connects to the same underlying Claude Code engine, so your CLAUDE.md files, settings, and MCP servers work the same across all of them. Pick whichever fits the moment, or move a session between them. You can also use more than one at once — for example, the CLI for heavy terminal work and the IDE extension for in-editor convenience.

VS Code is the most mature integration. Install it from the VS Code Marketplace or run code --install-extension Anthropic.claude-code. It gives you a native graphical interface, visual diff review, file references, conversation history, and the ability to run multiple conversations in tabs.

JetBrains has an official plugin in beta, available in the JetBrains Marketplace for IntelliJ IDEA, WebStorm, PyCharm, and other JetBrains IDEs. It orchestrates the CLI with the IDE’s diff viewer for a seamless experience.

Cursor, Devin Desktop (renamed from Windsurf in v2.1.162), and Kiro are VS Code forks that support the VS Code extension and the integrated terminal. In VS Code, Cursor, and Devin Desktop, /terminal-setup turns off the integrated terminal’s GPU acceleration (to prevent garbled text) and adjusts its scroll sensitivity for smoother fullscreen scrolling, and /ide and /scroll-speed use the new Devin Desktop label too.

Beyond IDE extensions, there’s a standalone Desktop App for running Claude Code outside your terminal or editor — review diffs visually, run multiple sessions side by side, schedule recurring tasks, and start cloud sessions, no terminal needed. The app bundles Claude Code, so you don’t install the CLI separately. It’s available for macOS (Intel and Apple Silicon), Windows (x64 and ARM64), and, in beta, Ubuntu 22.04+ or Debian 12+ (x86_64/arm64, installed via Anthropic’s apt repository or a downloaded .deb; see the Linux setup docs for details). Computer Use, dictation, and Fedora/RHEL aren’t in the Linux beta yet, and the CLI still covers a wider range of distros. There’s also Claude Code on the Web (claude.ai/code), which runs tasks on Anthropic-managed cloud infrastructure so you can work from any desktop browser — or the Claude mobile app for iOS and Android — with no local setup.

Your First Session

Navigate to any project directory and launch Claude Code:

cd my-project
claude

You’ll see a welcome message and a prompt. Just type what you want Claude to do in plain English. You can also paste images with Ctrl+V — a “Pasting…” hint appears in the footer while the image is being read from the clipboard:

What files are in this project and what does it do?

Claude will read your files, analyze the structure, and give you a summary. From here, you can ask it to make changes, fix bugs, run tests, or explain code. When Claude needs to perform actions like editing files or running commands, it will ask for your permission first.

That’s it — you’re ready. Head to the next module to learn the slash commands that make Claude Code truly powerful.