Getting Started with Claude Code: The Complete Guide to Anthropic’s Command-Line Agent (2026)

Author: Olasunkanmi Adeniyi | Last Updated: May 2026 | Reading Time: 12 minutes

Claude Code is Anthropic’s terminal-based AI coding agent. It reads your codebase, writes and edits files, runs commands, and handles complex multi-file tasks — all from your command line, using natural language. No browser tab switching, no copy-pasting snippets. Just your terminal and an AI that understands your actual project.

How to Start AI Side Hustle Over The Weekend

This guide covers everything you need to get from zero to a productive Claude Code session: system requirements, every installation method, authentication, and configuring repository permissions so Claude works freely inside safe boundaries.

What Is Claude Code?

Claude Code is a command-line tool built by Anthropic that turns your terminal into an AI coding environment. It understands your project structure, can edit files across directories, run shell commands, manage git workflows, and explain complex code — all through plain-language prompts.

Unlike browser-based AI chat assistants, Claude Code operates inside your actual development environment. It can read the files on disk, run your tests, and commit changes directly to your repository. That power comes with a well-designed permission system that puts you in control of exactly what it can and cannot touch.

System Requirements

Before installing, verify you meet these requirements:

Operating System:

macOS 13 (Ventura) or later
Linux: Ubuntu 20.04+, Debian 10+, Fedora, RHEL, Alpine
Windows 10 or later (native or via WSL2)

Account: Claude Code requires a paid Anthropic account. The free Claude.ai tier does not include access. Supported account types are: Claude Pro ($20/month), Claude Max ($100–200/month), Teams, Enterprise, or an Anthropic Console account with API credits. Subscription plans give you a monthly usage allowance; Console API access bills per token consumed.

For npm installation only: Node.js version 18 or later is required. Check your version with:

node --version

If you need to upgrade, use nvm (Node Version Manager) rather than the system package manager. This avoids the permission issues that come up later.

Installation Methods

Anthropic offers several installation paths. The native binary installer is the recommended method as of 2026 — it requires no dependencies, auto-updates in the background, and is the primary method Anthropic tests and supports. The npm method remains valid for developers who need version pinning or use npm as part of their standard workflow.

Method 1: Native Installer (Recommended)

macOS and Linux:

Open a terminal and run:

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

After the script completes, reload your shell configuration:

source ~/.bashrc
# or, for Zsh users:
source ~/.zshrc

Windows (PowerShell):

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

You do not need to run PowerShell as Administrator. The installer downloads the Claude Code binary, places it in your PATH, and configures automatic background updates. The whole process takes under a minute.

macOS via Homebrew:

brew install --cask claude-code

Note: Homebrew installations do not auto-update by default. Run brew upgrade claude-code periodically to stay current, or set the environment variable CLAUDE_CODE_PACKAGE_MANAGER_AUTO_UPDATE=1 to enable background upgrades.

Method 2: npm Global Install

If you prefer npm — for version pinning, consistency with an existing Node-based workflow, or CI pipeline use — run:

npm install -g @anthropic-ai/claude-code

The -g flag installs the package globally, making the claude command available anywhere in your terminal.

Critical warning: Never use sudo npm install -g. Running npm as root causes file permission problems and creates security risks. If you encounter an EACCES: permission denied error, the correct fix is to configure a user-owned npm global directory:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'

Then add the following line to your ~/.zshrc or ~/.bashrc:

export PATH="$HOME/.npm-global/bin:$PATH"

Apply it immediately with:

source ~/.zshrc   # or ~/.bashrc

Then retry the install. The better long-term solution is to switch to nvm entirely, which installs Node.js in your home directory and avoids global permission issues by design.

To upgrade an npm installation later, use:

npm install -g @anthropic-ai/claude-code@latest

Do not use npm update -g — it respects the original semver range and may not move you to the newest release.

Method 3: Linux Package Managers

Claude Code is available on Debian/Ubuntu via apt, on Fedora/RHEL via dnf, and on Alpine via apk. Consult the official setup documentation at code.claude.com/docs/en/setup for the current repository signing keys and install commands, as these can change between releases.

Verifying the Installation

Once installed by any method, confirm everything is working:

claude --version

You should see a version number printed to standard output. If you get a “command not found” error, your npm global bin directory is not on your PATH — revisit the steps above.

Run the built-in diagnostic to catch any configuration issues:

claude doctor

This command checks your Node.js version (for npm installs), authentication state, MCP server health, and file permissions. Run it before manual debugging — it auto-detects most common problems.

Authentication

Claude Code requires authentication before use. Two paths are available.

OAuth (for Claude Pro/Max/Teams/Enterprise subscribers):

Navigate to your project directory and launch Claude Code for the first time:

cd ~/projects/my-project
claude

On first launch, a browser window opens for OAuth authentication. Log in with the Anthropic account tied to your subscription and authorise the connection. A session token is stored locally after authorisation, so you will not need to log in every time.

If the browser redirect does not work — common in corporate proxy environments — try claude logout then claude again. If that does not resolve it, switch to API key authentication below.

API Key (for Console accounts and CI/CD pipelines):

Generate an API key from the Anthropic Console under Settings > API Keys. Then export it in your terminal session:

export ANTHROPIC_API_KEY=sk-ant-your-key-here

Claude Code detects the environment variable automatically and skips the browser OAuth flow. For permanent setup, add the export line to your ~/.zshrc or ~/.bashrc. For CI pipelines and Docker containers, set it as a secure environment variable in your pipeline configuration — never hard-code it in files.

Claude Code also supports connecting through Amazon Bedrock and Google Vertex AI via environment variables, for teams running models through their cloud provider:

# Amazon Bedrock
export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

# Google Vertex AI
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION=us-east1

Your First Session

With installation and authentication done, start a session in any project:

cd your-project
claude

Claude Code reads your project structure and enters an interactive session. Try a task immediately:

> Summarise the architecture of this codebase

Claude will scan your files, identify the stack, and give you a summary of how the project is organised. For a more concrete task:

> Find all places where we make HTTP requests without error handling and add try/catch blocks

Claude Code will identify the relevant files, propose specific changes, and ask for your confirmation before modifying anything — by default.

To exit a session, type /exit or press Ctrl+C.

Configuring Repository Permissions

This is the most important configuration step, and the one most guides skip. Out of the box, Claude Code asks for your approval before almost every file edit, bash command, and tool use. That caution is sensible for a first run but creates constant interruptions once you know what you want Claude to do.

The permissions system lives in .claude/settings.json for project-level configuration, and in ~/.claude/settings.json for user-level defaults that apply across all your projects. There is also .claude/settings.local.json — same format, same capabilities, never committed to Git — for machine-specific and personal overrides.

The hierarchy, from highest to lowest priority, is:

Enterprise managed settings (/etc/claude-code/managed-settings.json)
Session flags (--settings)
Project shared (.claude/settings.json, committed to Git)
Project local (.claude/settings.local.json, not committed)
User global (~/.claude/settings.json)

When the same key appears at multiple levels, the higher-priority scope wins for scalar values, and permission arrays are concatenated (both rule sets apply).

The Permissions Object

The core structure is:

{
  "permissions": {
    "allow": [],
    "deny": [],
    "ask": [],
    "defaultMode": "default",
    "additionalDirectories": []
  }
}

Rules are evaluated in order: deny is checked first, then ask, then allow. The first matching rule wins. Rule format follows the pattern ToolName(content) — for example, Bash(npm run test) or Read(./.env). The tool name is capitalised.

A Practical Starter Configuration

Create .claude/settings.json in your project root and commit it to Git so your entire team shares the same rules:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(npm run build)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git add *)",
      "Bash(git commit *)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl *)",
      "Bash(rm -rf *)",
      "Bash(git push --force *)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

This configuration pre-approves your common build, test, and git commands — eliminating the approval prompts that cause the most friction — while blocking access to environment files, secrets, and destructive commands that should never run without your explicit attention.

Key principles to apply:

Deny access to .env files and secrets directories first. This is the highest-value safety rule and should be in every project’s shared settings.

Use wildcards deliberately. Bash(npm run test) matches that exact command only. Bash(npm run test *) matches any variant with arguments. Bash(npm run *) matches all npm run scripts. Be as specific as your workflow allows.

Separate project-specific rules from general ones. If git is always safe for you, put Bash(git *) in your user-level ~/.claude/settings.json. If hugo * is specific to one project, put it in that project’s .claude/settings.local.json so you do not expose it globally.

Prefer manually editing settings.json over using the “Always allow” option in the prompt. The always-allow prompt adds lines to settings.local.json automatically, which can accumulate into an overly permissive configuration without your realising it.

Wildcards Reference

Claude Code supports two wildcard styles:

Prefix wildcards using prefix:* — legacy format, still functional.

Pattern wildcards using * — modern format, recommended. A single * matches any characters except path separators. A double ** matches across path separators.

Examples:

"Bash(npm run *)"          -- all npm run scripts
"Read(./src/**)"           -- all files under src/
"Write(./src/**)"          -- write access to src/ only
"mcp__github__create_*"    -- all GitHub MCP create actions

MCP tool rules use double-underscore format without parenthesised content — for example, mcp__github__create-pull-request.

Extending File System Access

By default, Claude Code only accesses the directory it was launched from and its subdirectories. To allow access to paths outside the working directory — useful when your project references shared configuration files or monorepo siblings — use additionalDirectories:

{
  "permissions": {
    "additionalDirectories": [
      "~/.config/project-shared",
      "../shared-lib"
    ]
  }
}

Protecting Sensitive Files

To prevent Claude Code from reading files containing API keys, credentials, or secrets, use deny rules in your project-level settings:

{
  "permissions": {
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Read(./config/credentials.*)"
    ]
  }
}

Claude Code automatically creates timestamped backups of configuration files and retains the five most recent, so if you break something with a misconfigured permissions file, your last working config is recoverable.

The CLAUDE.md File: Persistent Project Context

Settings control what Claude is allowed to do. CLAUDE.md controls what Claude knows — and it is the second most important thing you can configure.

CLAUDE.md is a plain Markdown file at your project root. Claude Code reads it at the start of every session. Without it, Claude infers your stack from file contents and makes reasonable guesses that drift across sessions. With it, Claude follows your exact conventions from the first prompt.

Create CLAUDE.md in your project root and include:

Your stack identity (language, framework versions, package manager)
Build and test commands
Code style conventions Claude cannot infer from existing files
Architectural decisions and patterns to follow
Anything Claude should never do (e.g., “never modify generated files in /dist”)

A minimal example:

# Project Context

Stack: Node.js 20, TypeScript, Express 5, PostgreSQL 16
Package manager: pnpm
Test runner: Vitest

## Common commands
- Build: pnpm build
- Test: pnpm test
- Lint: pnpm lint --fix

## Conventions
- Use async/await, never raw Promise chains
- All database queries go through the repository layer in src/db/
- Never edit files in src/generated/ — these are auto-generated

Keep CLAUDE.md under 300 lines. Claude Code wraps it in a system reminder that tells the model to ignore instructions irrelevant to the current task. As instruction count grows, consistency degrades. Focus on what Claude cannot infer from reading your code.

CLAUDE.md supports a three-level hierarchy: user-level (~/.claude/CLAUDE.md), project-level (./CLAUDE.md), and directory-level (./src/CLAUDE.md), merged in order of specificity. Use subdirectory CLAUDE.md files to give Claude additional context when it is working in a specific part of a large codebase.

Verification Checklist

Run through this list after setup:

claude --version           # confirms binary is installed and on PATH
claude doctor              # checks Node version, auth state, MCP health
claude                     # opens a session; verify it reads your project
cat .claude/settings.json  # confirm permissions are as intended
cat CLAUDE.md              # confirm project context is present

Common Issues and Fixes

“command not found: claude” after npm install Your npm global bin directory is not on your PATH. Run npm config get prefix to find the prefix directory, then add <prefix>/bin to your PATH in ~/.zshrc or ~/.bashrc.

EACCES permission error during npm install Do not use sudo. Set a user-owned npm global directory as described in the installation section above, or switch to nvm.

Browser redirect fails during OAuth Try claude logout then claude again. In corporate proxy environments, use API key authentication via ANTHROPIC_API_KEY instead.

Claude keeps asking for permission for the same commands Add those commands to the allow array in .claude/settings.json. Use wildcards to cover variants. Prefer editing the file directly over using the “Always allow” prompt option.

Mixed installation artifacts causing errors If you previously installed an older npm or Bun version and have switched to the native installer, you may have conflicting binaries. Run claude doctor to identify the conflict, then remove old installations. On macOS/Linux: rm -rf ~/.claude && curl -fsSL https://claude.ai/install.sh | bash in a fresh terminal.

Next Steps

With Claude Code installed, authenticated, and configured, you are ready for real work. Three things will improve your experience fastest from here:

Work in a Git repository. Claude Code can read, write, and delete files. Having every change tracked means you always have a rollback point. Use Claude Code on a branch for experimental work, review the diff before merging.

Invest in your CLAUDE.md. The first time Claude misidentifies your test command or uses the wrong import style, add a line to CLAUDE.md. Over time this file becomes a precise specification of how your project works, and sessions become dramatically more consistent.

Learn the slash commands. Inside a session, type /help to see available commands. /config opens a visual settings interface. /bug reports issues directly to Anthropic. /compact summarises the current conversation to free up context window space for long sessions.

Official Resources

Claude Code documentation: https://docs.claude.com/en/docs/claude-code/overview
Setup and installation: https://code.claude.com/docs/en/setup
Settings reference: https://code.claude.com/docs/en/settings
npm package: https://www.npmjs.com/package/@anthropic-ai/claude-code
GitHub repository: https://github.com/anthropics/claude-code
Anthropic Console (API keys): https://console.anthropic.com

This guide reflects the current state of Claude Code as of May 2026. Claude Code is under active development; check the official documentation for the latest installation commands and configuration options.

Olasunkanmi Adeniyi O : Olasunkanmi is a Product Manager, AI Prompt Engineer, and Technical Writer specializing in advanced automation and digital strategy. As the founder of AI Discoveries, he creates high-performance frameworks and digital operating systems designed to help professionals leverage artificial intelligence, optimize workflows, and build scalable global brands.

AI Discoveries