Installing and Setting Up Claude Code

1. What Claude Code is and who should install it

Claude Code is Anthropic's agentic command-line assistant that works directly in the terminal, and unlike classic autocomplete tools it doesn't just suggest individual lines of code, it independently reads files, makes changes, runs shell commands, and plans multi-step tasks. For PHP and Magento developers this is a fundamental shift from typical IDE integration: instead of single suggestions in the editor, Claude Code carries out complete work steps, for example scaffolding a new module with interfaces, view models, and layout XML in one pass, as long as the task is clearly specified.

Installing it pays off especially for developers who want to automate repetitive but context-heavy tasks, such as generating boilerplate that follows project conventions, debugging across multiple files, or writing PHPStan-compliant classes with complete PHPDoc documentation. A realistic view matters here too: Claude Code does not replace code review, does not replace test coverage, and does not replace an understanding of your own architecture. Taking installation and initial configuration seriously avoids later surprises around permissions, cost, and model choice, all of which are covered in detail in the sections below.

2. System requirements: Node.js, npm, and terminal

Claude Code requires a current Node.js installation, version 18 or newer, since the CLI ships as an npm package and runs internally on the Node runtime. On development machines already set up for Hyvä themes with Tailwind CSS and its build process, this requirement is usually already met, since bin/npm and bin/node exist in the Docker setup regardless. Before installing, it's worth a quick check of the existing versions to rule out compatibility issues up front.

macOS, Linux, and Windows are all supported, though on Windows using WSL (Windows Subsystem for Linux) is recommended, because shell integration and filesystem operations there are considerably more reliable than in native PowerShell. A working terminal with bash or zsh is required, along with a user account without root privileges for the npm installation, since a package installed globally with sudo can later cause permission problems during updates. Git should also be installed, since Claude Code performs many operations against the existing Git history and working tree.

3. Installing via npm: step by step

Installation happens through npm with a single global command. Once it completes, the claude command is available system-wide in the terminal, independent of the current working directory. A follow-up version check confirms the installation succeeded and shows which version is active, which serves as the first diagnostic step for later update issues.

# Install Claude Code globally via npm
npm install -g @anthropic-ai/claude-code

# Verify the installation and check the active version
claude --version

# If npm's global bin directory is not writable, configure a
# user-owned prefix instead of using sudo
npm config set prefix "$HOME/.npm-global"
export PATH="$HOME/.npm-global/bin:$PATH"

If global npm permissions cause trouble, configuring a user-owned npm prefix directory in the home folder is the better fix, rather than forcing the installation with elevated privileges. That avoids permission conflicts permanently and makes later updates via npm update -g far less troublesome. Alternative installation paths, such as a native install script, exist as well, but for Node environments that already exist in a Magento context they're usually unnecessary, since the npm route fits seamlessly into existing tool chains.

4. First login: account login or API key

On first launch, Claude Code prompts for authentication. Two paths are available: signing in with an existing Claude account (Pro or Max subscription) via an OAuth flow in the browser, or using an Anthropic API key from the developer console with usage-based billing. Account login is usually the simpler and cheaper option for individual developers with predictable usage, while the API key suits teams that want to bill usage centrally through the console and separate it by project or client.

# Option 1: interactive login via browser (OAuth), tied to a
# Claude Pro or Max subscription
claude login

# Option 2: authenticate with an Anthropic API key instead,
# billed per token usage via the developer console
export ANTHROPIC_API_KEY="sk-ant-api03-your-key-here"
claude

# Reset the current session and switch authentication method
claude logout

For agencies handling multiple client projects, the decision isn't trivial: an API key allows granular cost control through separate keys per project, but requires its own spending monitoring, since billing follows token usage and can rise quickly during large refactors. Account login with a subscription offers predictable fixed costs, but is bound to a usage cap per time window. Both methods can be reset at any time with claude logout, in case switching between an account and an API key becomes necessary.

5. Understanding and configuring permission modes

The permission mode determines how independently Claude Code is allowed to make file changes and run shell commands before asking for confirmation. In the default mode, the CLI asks individually before every file change and every terminal command, which offers maximum control but leads to constant interruptions on larger tasks. The acceptEdits mode applies file changes automatically but still asks before potentially dangerous shell commands. Plan mode lets Claude Code act read-only at first and produce a plan that must be explicitly approved before any actual changes happen.

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(bin/magento:*)",
      "Bash(bin/composer:*)",
      "Edit(src/app/code/**)"
    ],
    "deny": [
      "Bash(git push --force:*)",
      "Bash(git reset --hard:*)",
      "Bash(rm -rf:*)"
    ]
  }
}

For work on production Magento stores, a full bypass mode that skips every confirmation is clearly not advisable, since destructive commands like git reset --hard or deleting configuration files would run without any prompt. A more sensible approach is a granular configuration in settings.json with explicit allow and deny lists for specific command patterns, for example permitting bin/magento commands while forbidding git push --force at the same time. This configuration can live project-specifically in .claude/settings.json and applies automatically on every start within that repository.

6. Choosing a default model: Sonnet, Opus, and Haiku

Claude Code supports several models with different tradeoffs between speed, cost, and capability. For everyday Magento and PHP tasks such as writing view models, plugins, or PHPStan-compliant classes, the default model from the Sonnet line is usually sufficient, offering a good balance between response quality and speed. For complex architectural decisions, such as planning a new module with multiple dependencies or tracing a hard-to-follow bug across many files, switching to the more capable Opus model can be worthwhile.

{
  "model": "claude-sonnet-5",
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}

The default model can be switched temporarily within a running session via the /model command, or set permanently in the configuration file so every new session starts automatically with the desired model. This matters for budget planning: more capable models generally consume more tokens for the same task, and therefore more cost or usage allowance, which is why a deliberate model choice per task type pays off over the long run, rather than always reaching for the most capable model on simple tasks.

7. Setting up CLAUDE.md and project context

A CLAUDE.md file at the project root is automatically read by Claude Code at the start of every session and serves as project-specific context for coding standards, directory structure, preferred patterns, and team conventions. For Magento projects, it makes sense to document guidance there such as using view models instead of block classes, constructor property promotion, the path to the Docker wrapper scripts, and PHPStan exceptions, so every session knows the same ground rules without needing to be told again. The /init command inside a running session analyzes an existing repository and automatically proposes a first CLAUDE.md based on the detected structure.

Beyond CLAUDE.md, it's worth setting up .claudeignore early, which excludes directories like vendor, node_modules, or generated static content folders from analysis, so the context window and response times aren't burdened unnecessarily. In monorepos or projects with multiple vendor variants, such as the dual-vendor workflow common in this project between Mironsoft and Abrams, a clearly structured CLAUDE.md helps ensure changes are reliably carried through both codebases in sync, instead of having to point that out manually with every request.

8. Verifying the setup: your first task

After installation, authentication, and basic configuration, a deliberately simple first test is worthwhile before letting Claude Code touch production code. A sensible starting point is a purely read-only task, such as asking it to summarize the structure of an existing module or explain a single method. This confirms that authentication, model access, and file access all work correctly, without risking any changes to the code.

The next step is a small, clearly scoped write task, such as adding a missing PHPDoc block to a single method or fixing an obvious typo. This lets you observe how the chosen permission mode behaves in practice, which confirmations get requested, and what the proposed diff looks like before it's accepted. This gradual approach, ideally in a separate Git branch or a test copy of the project, builds trust in the tool before it gets used on more complex, production-relevant tasks.

9. Common first-run problems

Even with a careful installation, typical problems show up on the first run, and most can be narrowed down quickly. The most common error message, command not found: claude, almost always points to the global npm binary directory not being on the terminal's PATH, which happens especially after a fresh Node installation via a version manager like nvm. Authentication errors often stem from expired OAuth tokens after a period of inactivity, or from an invalid API key that accidentally picked up spaces or line breaks when it was copied.

# Check Node.js and npm versions
node --version
npm --version

# Confirm the global npm bin directory is on PATH
npm config get prefix
echo $PATH | tr ':' '\n' | grep npm

# Re-authenticate after a token or API key issue
claude logout
claude login

# Test connectivity to the Anthropic API through a proxy
curl -I https://api.anthropic.com

Another common issue in corporate environments is a firewall or proxy blocking connections to api.anthropic.com, which usually shows up as timeouts without a concrete error message. The table below summarizes the most common startup problems, their causes, and the recommended fix for each.

Diagnosis usually follows the same pattern: check the Node and npm versions first, then check the proxy and API key environment variables, and only afterward retry the login. Following this order resolves the vast majority of first-install problems within a few minutes, without having to redo the whole installation.

10. Summary

Installing and setting up Claude Code is technically straightforward, but the deliberate configuration decisions right after installation matter most. Node.js 18 or newer, a single npm command, and a version check cover the raw installation. The choice between account login and an API key determines the billing model, while the permission mode determines how much control over file changes and shell commands stays with the user. A production-ready permission mode with explicit allow and deny lists is mandatory for Magento projects, not optional.

A well-maintained CLAUDE.md file and a deliberately chosen default model save time and money over the long run, because every session starts with the same project context instead of having conventions explained repeatedly. A simple first test, a read-only task followed by a small write task, confirms that authentication, model access, and permissions work together correctly before Claude Code gets used on production-relevant code. The most common startup problems can usually be resolved within a few minutes through PATH, token, and network checks.

11. FAQ: Installing and Setting Up Claude Code