Claude Code: install, configure and use the terminal coding agent

Introduction

Claude Code is the Anthropic coding agent from the same family as Claude Opus 5.5. It reads a codebase, edits files, runs commands, works with git and connects to external tools over MCP. It runs in the terminal, in VS Code and JetBrains extensions, in a desktop app and in the browser, and every surface shares the same project configuration.

This guide is the working manual: install, sign-in, memory files, permissions, subagents, skills, MCP and the workflows that pay off daily. Agent files get their own deep dive in Claude Code subagents; the side-by-side view with OpenCode is in Building AI agents.

Install

The native installer is recommended on macOS, Linux and WSL, and it updates itself in the background:

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

On Windows, use PowerShell or CMD depending on your shell:

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

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

Package managers work too. Homebrew has a stable cask and a faster-moving one; Homebrew and WinGet installs do not auto-update:

brew install --cask claude-code brew install --cask claude-code@latest winget install Anthropic.ClaudeCode

Debian, Fedora, RHEL and Alpine users can install from the package manager repositories; the setup page linked below lists the exact commands. After installing, open a new terminal and check:

claude --version claude doctor

claude doctor runs installation diagnostics without starting a session: duplicate installs, PATH problems, unparseable settings and pending updates. If the shell says claude: command not found, the install directory is not on PATH yet; the troubleshooting page walks through a fix. Git for Windows is recommended on native Windows so the Bash tool has a real shell.

Prefer an editor or a window? The VS Code and Cursor extension, the JetBrains plugin, the desktop app and the web version at claude.ai/code share the same engine and configuration. The desktop app bundles the command line, so you do not install the CLI separately for it. Installation details: code.claude.com setup.

Sign in and providers

The first run prompts for a login. Two main routes:

• Claude subscription: sign in with the same account you use on claude.ai. Plan limits apply to Claude Code usage and are shared with the web and mobile apps.
• Anthropic Console: use an API key from the Console. Pay-as-you-go billing, no plan limits, better for automation and CI.

For scripts, set ANTHROPIC_API_KEY in the environment and approve the key when asked; Claude Code then skips the login prompt. Teams on cloud platforms can route through Amazon Bedrock, Google Cloud or Microsoft Foundry instead of the Anthropic API; the provider variables live in the third-party integration docs.

export ANTHROPIC_API_KEY=sk-ant-... claude

Inside a session, /login and /logout switch accounts, and /status shows which account, plan and model are active. Subscription sessions can also sync skills from your claude.ai account; API-key sessions do not.

CLAUDE.md and memory

Every session starts with a fresh context window, so durable rules belong in files. CLAUDE.md is the project instruction file; it is read at the start of every conversation. Locations, from broadest to most specific:

• Managed policy: deployed by administrators, for example /etc/claude-code/CLAUDE.md on Linux.
• User: ~/.claude/CLAUDE.md — personal preferences for every project.
• Project: ./CLAUDE.md or ./.claude/CLAUDE.md — committed and shared with the team.
• Local: ./CLAUDE.local.md — your private notes for this project; add it to .gitignore.

Files from the working directory upward are concatenated, closest last. Files in subdirectories load on demand when Claude touches a file there. Run /init once to generate a starting file, /memory to open and edit the files, and /context to confirm what loaded.

Repositories that already use AGENTS.md do not need a duplicate: Claude Code reads AGENTS.md in place of CLAUDE.md when no CLAUDE.md or CLAUDE.local.md exists in the working directory or above it. A one-line CLAUDE.md importing it with @AGENTS.md keeps both tools on the same file when a CLAUDE.md already exists or the version is older.

# CLAUDE.md @AGENTS.md ## Claude Code - Use plan mode for changes under src/billing/.

Imports with @path expand at launch and can nest four hops deep. For larger projects, split instructions into .claude/rules/ files; a rule with paths: frontmatter loads only when Claude works with matching files. Keep each file under about 200 lines: longer files cost context and reduce adherence. Claude also keeps its own auto memory at ~/.claude/projects/<project>/memory/, with a MEMORY.md index; browse it with /memory.

Settings and permissions

Settings live in JSON files with a clear precedence: managed policy, then user ~/.claude/settings.json, then project .claude/settings.json, then local .claude/settings.local.json. The permissions block is the safety layer. Rules are evaluated as allow, ask and deny, with the tool name plus an optional specifier. Shared project rules go in .claude/settings.json:

vi .claude/settings.json

{ "permissions": { "allow": [ "Bash(git status:*)", "Bash(git diff:*)", "Bash(npm run test:*)" ], "ask": ["Bash(git push:*)"], "deny": [ "Read(./.env)", "Read(./secrets/**)", "Bash(curl:*)" ] } }

Project rules and hooks only take effect after you trust the workspace once; a cloned repository cannot approve its own configuration. Permission modes change how much prompting happens:

• default: asks when a tool is not covered by a rule.
• plan: read-only research first; Claude presents a plan and waits for approval before editing. Start complex work here.
• acceptEdits: file edits go through without prompting; shell still asks.
• auto: a classifier approves or blocks calls against your rules; fewer prompts, same guardrails.
• bypassPermissions: no prompts at all. Use only in disposable sandboxes and CI, never on a laptop with production secrets.

Set the mode per session with --permission-mode or switch inside a session with /permissions. Deny rules and hooks are the only layers that hold even in auto mode, so put the truly forbidden paths there: .env, credentials, deployment keys.

Subagents

Subagents are specialized workers with their own context window, system prompt, tool list and model. Claude delegates to them by matching the task against each subagent description, and they return only the summary, which keeps exploration and logs out of the main conversation. Files live in .claude/agents/ (project) or ~/.claude/agents/ (personal). Example file .claude/agents/code-reviewer.md:

mkdir -p .claude/agents

vi .claude/agents/code-reviewer.md

--- name: code-reviewer description: Reviews changes for correctness, security and missing tests. Use after every code change. tools: Read, Grep, Glob model: opus --- You are a strict reviewer. Report findings in severity order, each with file and line. Never edit files.

Ask for one by name when you want it explicitly: Use the code-reviewer subagent on my staged changes. Built-in subagents such as Explore, Plan and general-purpose cover search and multi-step work without any files. Files, fields, tools, models, memory, worktree isolation and complete examples are in Claude Code subagents.

Skills and commands

A skill packages a repeatable procedure. It is a directory with a SKILL.md inside; the body loads only when the skill is used, so long checklists cost almost nothing at rest. Project skills live in .claude/skills/<name>/SKILL.md. Example file .claude/skills/summarize-changes/SKILL.md:

mkdir -p .claude/skills/summarize-changes

vi .claude/skills/summarize-changes/SKILL.md

--- description: Summarizes uncommitted changes and flags risks. Use when the user asks what changed. allowed-tools: Bash(git diff:*) --- ## Current changes !`git diff HEAD` Summarize in two or three bullets, then list risks: missing error handling, hardcoded values, tests to update.

Two ways to run it: Claude invokes the skill automatically when the description matches, or you type /summarize-changes. Frontmatter controls the rest: disable-model-invocation makes a skill manual-only, allowed-tools pre-approves tools for the turn, paths limits activation to matching files, and context: fork runs the skill in its own subagent. A markdown file in .claude/commands/ is the older command format and still works; custom commands and skills were merged.

Skills follow the Agent Skills open standard, and .claude/skills/ is also read by OpenCode as a compatibility location — one directory, two assistants. Claude Code ships bundled skills too, including /code-review, /verify and /run; list them with /skills. Format details and more examples: Writing skills for AI assistants.

MCP servers

MCP connects Claude Code to issue trackers, databases, design files and monitoring. Add a remote server over HTTP:

claude mcp add --transport http notion https://mcp.notion.com/mcp claude mcp add --transport http secure-api https://api.example.com/mcp \ --header "Authorization: Bearer your-token"

For a local tool that runs as a process, everything after the double dash is the launch command:

claude mcp add airtable --env AIRTABLE_API_KEY=YOUR_KEY -- npx -y airtable-mcp-server

Three scopes decide who sees the server: local (only you, this project), project (committed to .mcp.json and shared with the team) and user (all your projects). Check and manage them with claude mcp list and /mcp; project servers wait for your approval the first time. Treat every server as code you are running: verify the publisher before connecting, because a server that fetches external content can carry prompt injection.

Hooks

Instructions in CLAUDE.md are guidance; hooks are enforcement. They run shell commands at fixed lifecycle points, configured under the hooks key in a settings file: before a tool call (PreToolUse), after it (PostToolUse), when a session starts or ends, and when instructions load. Typical uses: format after every edit, run the lint gate before commit, or block a command outright. Project hooks go in .claude/settings.json:

vi .claude/settings.json

{ "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "npx prettier --write $CLAUDE_FILE_PATHS" } ] } ] } }

Hooks run with your permissions and apply to the whole session, so keep them small and deterministic. The hooks guide linked below covers every event, matcher and exit-code contract: code.claude.com hooks.

Daily workflows

• Plan before editing. Start non-trivial changes in plan mode; read the proposed plan, correct it, then approve. Cheaper than reverting a wrong refactor.
• Review with a subagent. After the build pass, ask the read-only reviewer for a verdict on the staged diff. Fresh context catches what the builder normalized.
• Verify against the app. /verify builds and runs the project to confirm a change works, instead of trusting tests alone; /run drives the app to see it.
• Pipe it. Non-interactive mode turns Claude Code into a Unix tool: tail -200 app.log | claude -p "summarize the errors" or git diff main --name-only | claude -p "review these for security issues".
• Commit and PR. Claude stages changes, writes commit messages and opens pull requests. Keep the permission rules from Settings so push stays behind a prompt.
• Parallel sessions. Background agents and the desktop app run several sessions side by side; scheduled tasks handle recurring work such as morning PR review.

The full map of surfaces and automation is in the official docs: code.claude.com overview.

Troubleshooting

• Command not found after install. The install directory is not on PATH; open a new terminal, then follow the PATH section of the install troubleshooting guide.
• AGENTS.md seems ignored. A CLAUDE.md or CLAUDE.local.md exists in the working directory or above it, so it wins. Import AGENTS.md from CLAUDE.md, or set Project instructions to read both.
• Instructions not followed. Run /context and check Memory files: a file that is missing there was never loaded. Then make the rule specific and verifiable instead of a general request.
• MCP server not connecting. Run claude mcp list: Needs authentication means sign in from /mcp, Pending approval means approve the project server in an interactive session.
• Something is generally wrong. Run claude doctor in the shell or /doctor in a session, and /doctor prompt-audit to find conflicting instructions in CLAUDE.md files, skills and commands.

Article author: Arthur Isaev