TL;DR

Claude Code is Anthropic’s agentic coding environment for reading a codebase, editing files, running commands, integrating with IDEs, and coordinating work across developer tools. The practical mental model is simple: Claude Code is not just a chatbot inside a terminal; it is a coding agent with filesystem access, command execution, project memory, tool permissions, hooks, subagents, and MCP connectors.

For most developers, the highest-leverage setup is:

  1. Install Claude Code with the native installer or with npm via advanced setup.
  2. Run /init to create a project-level CLAUDE.md.
  3. Use /permissions and .claude/settings.json to define safe tool rules.
  4. Learn /plan, /clear, /compact, /context, /memory, /agents, /mcp, and /hooks.
  5. Treat model IDs, slash commands, and installer behavior as fast-moving details; verify them against the Claude Code changelog before scripting.

The core constraint is context. A useful way to think about every long Claude Code session is:

\[C_{\text{free}} = C_{\text{window}} - C_{\text{conversation}} - C_{\text{files}} - C_{\text{tool outputs}} - C_{\text{memory}}\]

When \(C_{\text{free}}\) gets small, the session becomes more error-prone. Use /compact, /clear, subagents, and targeted file references to keep the working context clean.

1. What Claude Code Is

Claude Code is an agentic coding tool that can inspect a project, edit files, run shell commands, use development tools, and help ship changes. It is available through the terminal, IDE integrations, desktop, and web surfaces.

The most important distinction is that Claude Code works inside a developer loop:

explore → plan → edit → test → review → commit

That loop is why the official best practices guide emphasizes giving Claude a verification path: tests, builds, linters, screenshots, logs, or reproducible checks.

2. Installation and Setup

Native installer

The current official docs present the native installer as the recommended path in the Claude Code overview.

# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows PowerShell
irm https://claude.ai/install.ps1 | iex

npm install

Claude Code can also be installed globally with npm through the advanced setup guide. The npm package requires Node.js 18 or later.

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

Important caveat: do not use sudo npm install -g. The official setup docs warn that this can cause permission and security problems. To upgrade an npm installation, use:

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

Avoid relying on npm update -g, because it may respect the old semver range and fail to move to the latest release.

Health check

Use the CLI health and version tools when something feels wrong:

claude doctor
claude update
claude --version

3. Authentication Options

Claude Code supports several authentication paths through the authentication docs:

Path Best for
Claude.ai subscription Individual Pro, Max, Team, or Enterprise users
Anthropic Console API-key and pay-as-you-go workflows
Amazon Bedrock AWS-managed enterprise deployment
Google Vertex AI GCP-managed enterprise deployment
Microsoft Foundry Azure/Microsoft enterprise deployment

For local development, the common path is signing in with a Claude.ai account. For CI, controlled automation, or cost attribution, an API-key or cloud-provider setup is often cleaner.

4. Core CLI Commands

The CLI reference lists the main commands for starting, resuming, and scripting sessions.

Command Purpose
claude Start an interactive session
claude "query" Start a session with an initial prompt
claude -p "query" Run non-interactive print mode, then exit
cat file \| claude -p "query" Pipe content into Claude Code
claude -c Continue the most recent conversation in the current directory
claude -c -p "query" Continue the latest session in non-interactive mode
claude -r "<session>" "query" Resume a named or specific session
claude update Update Claude Code
claude install stable Install or reinstall a native binary
claude mcp ... Manage MCP servers
claude auth login Sign in from the command line
claude plugin ... Manage plugins

Example headless workflow:

claude -p "fix lint errors" \
  --output-format stream-json \
  --verbose \
  --max-turns 5 \
  --allowedTools "Bash(npm run lint:*)" "Edit"

Use headless mode when the task has a clear success condition, such as fixing lint, updating generated files, summarizing logs, or running a review pass.

5. Slash Commands You Should Actually Learn

The commands documentation describes slash commands as session-level controls for models, permissions, context, memory, agents, and workflows.

Command Use
/help Show available commands
/init Generate a starter CLAUDE.md
/memory View and edit loaded memory files
/permissions Manage tool approval rules
/plan Switch into planning before edits
/model View or change model
/effort Adjust reasoning effort where supported
/clear Clear the conversation context
/compact Summarize and compress context
/context Inspect context-window usage
/agents Create or manage subagents
/mcp Manage MCP servers and OAuth
/hooks Configure lifecycle hooks
/status Check account, model, version, and environment status
/doctor Diagnose install/session issues
/resume Resume earlier sessions
/rewind Rewind to a checkpoint
/review Ask for a code review
/config View or update configuration
/ide Connect an IDE integration

The most productive beginner sequence is:

/init
/memory
/permissions
/plan

That sequence gives Claude project knowledge, makes memory editable, prevents unsafe tool usage, and forces a design pass before code changes.

6. CLAUDE.md and Memory

Claude Code’s memory system uses Markdown files such as CLAUDE.md to give Claude persistent project guidance. The file is not magic; it is instructions loaded into the session context.

A good CLAUDE.md should be short, specific, and operational:

# Project instructions

## Build and test
- Install dependencies with `pnpm install`.
- Run unit tests with `pnpm test`.
- Run type checks with `pnpm typecheck`.
- Run lint with `pnpm lint`.

## Code style
- Prefer small pure functions.
- Use 2-space indentation.
- Do not introduce new runtime dependencies without asking.

## Safety
- Never edit `.env`, credentials, or deployment secrets.
- Ask before running database migrations.

Bad memory is vague:

Write good code.
Be careful.
Follow best practices.

Good memory is verifiable:

Before marking a task complete, run `pnpm test` and `pnpm lint`.

Use /memory to inspect which memory files were loaded. If Claude ignores project instructions, first check whether the relevant CLAUDE.md is actually visible to the current session.

7. Settings and Permission Rules

Claude Code uses scoped settings described in the settings documentation. The main scopes are:

Scope Location Shared? Use case
Managed IT / system policy Yes Organization-wide enforcement
User ~/.claude/ No Personal defaults across projects
Project .claude/ in repo Yes Team-shared repo settings
Local .claude/settings.local.json No Personal overrides inside one repo

A practical .claude/settings.json:

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

Permission rules follow the format:

Tool
Tool(specifier)

Examples:

Bash(npm run *)
Read(./.env)
WebFetch(domain:example.com)
mcp__github__get_*

The safe default is:

deny secrets → ask for deployment/destructive actions → allow repeatable local checks

8. Permission Modes

Claude Code supports several permission modes through settings and CLI flags.

Mode Meaning
default Ask on first use of tools
acceptEdits Auto-accept file edits, still ask for riskier actions
plan Read-only planning before tool use
auto Let Claude classify what can run automatically
dontAsk Avoid permission prompts where possible
bypassPermissions Skip prompts; dangerous outside sandboxed environments

The dangerous shortcut is:

claude --dangerously-skip-permissions

Use it only in isolated environments such as disposable containers or controlled CI. In normal development, prefer explicit allowlists plus plan mode.

A reasonable safety formula is:

\[\text{safe autonomy} ==================== \text{least privilege} + \text{sandboxing} + \text{tests} + \text{human review}\]

9. Hooks

Hooks let you run shell commands, HTTP endpoints, or prompt-based checks at specific points in Claude Code’s lifecycle.

Useful hook events include:

Event Typical use
SessionStart Load environment diagnostics
UserPromptSubmit Validate prompt or inject policy
PreToolUse Block unsafe commands
PostToolUse Format files after edits
Stop Run final checks
PreCompact Save state before context compression
SessionEnd Export logs or cleanup
SubagentStart / SubagentStop Track delegated work

Example hook:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/check-command.sh"
          }
        ]
      }
    ]
  }
}

A PreToolUse hook can block an action. This makes hooks useful for policy enforcement, but also risky: hook commands are code, so they should be reviewed like any other automation.

10. MCP: Connecting Claude Code to External Tools

Claude Code connects to external tools through Model Context Protocol. MCP servers can expose issue trackers, databases, monitoring tools, file systems, design tools, internal APIs, or SaaS connectors.

Add a local stdio server:

claude mcp add local-weather -- /path/to/weather-cli --api-key "$API_KEY"

Add an HTTP server:

claude mcp add --transport http sentry https://mcp.sentry.dev/mcp

Add from JSON:

claude mcp add-json weather-api \
  '{"type":"http","url":"https://api.weather.com/mcp","headers":{"Authorization":"Bearer token"}}'

Manage servers:

claude mcp list
claude mcp get sentry
claude mcp remove sentry

Authenticate remote servers:

/mcp

or:

claude mcp login sentry

MCP is powerful because it turns Claude Code from a codebase-only tool into an environment-aware agent. It is also a prompt-injection surface. If an MCP server fetches untrusted external content, treat that content as potentially hostile.

11. Subagents

Subagents are specialized Claude Code workers that run in their own context windows. They are useful when a side task would flood the main conversation with logs, search results, or large file reads.

Use subagents for:

Use case Why
Code review Keeps review findings separate from implementation
Debugging Lets one agent inspect logs while another edits
Research Avoids dumping long search output into the main context
Migration planning Produces a scoped plan before code changes
Database query validation Restricts tools and domain behavior
Large refactors Delegates independent file groups

A project subagent lives under:

.claude/agents/<name>.md

Example:

---
name: code-reviewer
description: Review code changes for correctness, maintainability, and security risks.
tools: Read, Grep, Glob, Bash(git diff *)
model: inherit
---

You are a strict code reviewer. Focus on:
- correctness bugs
- missing tests
- security issues
- brittle abstractions
- unnecessary complexity

Return findings with file paths and concrete suggested fixes.

Subagents are best when they have narrow instructions and limited tools. If the task requires direct collaboration between multiple workers, consider agent teams or separate sessions instead of a single subagent.

12. Custom Slash Commands

Custom slash commands are Markdown files stored in:

.claude/commands/
~/.claude/commands/

Example:

---
allowed-tools: Bash(git add:*), Bash(git commit:*)
description: Create a conventional commit
argument-hint: [message]
---

Stage all changes and create a conventional commit with this message:

$ARGUMENTS

Then run:

/commit fix parser edge case

Good custom commands encode repeatable workflows:

/review-pr
/write-tests
/update-changelog
/triage-issue
/refactor-module

They should not encode secrets, broad permissions, or destructive commands.

The best Claude Code workflow is not “ask it to code immediately.” It is:

1. Ask Claude to inspect the relevant files.
2. Ask for a plan.
3. Approve or edit the plan.
4. Let Claude implement.
5. Run tests.
6. Ask for a review.
7. Commit only after verification.

Example prompt:

Read the auth module and the failing tests. Do not edit yet.
Explain the root cause, then propose a minimal patch plan.

Then:

Implement the plan. After editing, run the focused tests first, then the full test suite if the focused tests pass.

Then:

Review your own diff for correctness, edge cases, and unnecessary complexity.

This keeps the agent grounded and gives it a way to verify its work.

14. Context Hygiene

The official best practices emphasize that context fills quickly. Every tool output, file read, prompt, and memory item consumes budget.

Use these habits:

Habit Why it helps
Use /clear between unrelated tasks Prevents stale assumptions
Use /compact in long sessions Preserves useful state while reducing tokens
Use /context Shows where context is going
Use subagents for research Keeps noisy exploration out of the main window
Reference specific files with @path Avoids broad codebase scanning
Ask for plans before edits Prevents premature changes
Run focused tests first Gives a fast verification loop

A useful rule:

\[\text{agent quality} \propto \frac{\text{relevant context}}{\text{total context noise}}\]

The goal is not to maximize context. The goal is to maximize relevant context density.

15. Models as of July 2026

The current Claude models overview lists the latest model family as:

Model Positioning
Claude Fable 5 Most capable widely released model; long-running agents
Claude Opus 4.8 Complex agentic coding and enterprise work
Claude Sonnet 5 Strong speed-intelligence balance
Claude Haiku 4.5 Fastest model with near-frontier intelligence

For Claude Code, the practical selection rule is:

Need Start with
Hard autonomous coding Opus
Everyday coding and analysis Sonnet
Cheap high-volume simple work Haiku
Highest available capability Fable, where available

Do not hard-code old model IDs unless you need pinned reproducibility. Model naming and aliases move quickly; verify against the current models overview, model IDs and versioning, and Claude Code changelog.

16. Practical Setup Checklist

For a new repository:

claude

Then inside Claude Code:

/init
/memory
/permissions

Create or review:

CLAUDE.md
.claude/settings.json
.claude/commands/
.claude/agents/
.mcp.json

Recommended project files:

CLAUDE.md                         # team-shared project instructions
.claude/settings.json             # shared safe defaults
.claude/settings.local.json       # personal overrides, gitignored
.claude/commands/review-pr.md     # repeatable workflow
.claude/agents/code-reviewer.md   # reusable review subagent
.mcp.json                         # project MCP servers, if shared

Minimum safe .gitignore check:

.claude/settings.local.json
.env
.env.*
secrets/

17. Common Gotchas

Problem Fix
Claude ignores project rules Run /memory and confirm CLAUDE.md is loaded
Session becomes confused Use /compact or /clear
Too many permission prompts Add narrow allow rules
Claude edits too early Start with /plan
Commands fail in headless mode Use --allowedTools and make auth non-interactive
MCP server missing Check /mcp, /status, and active auth method
npm install has permission errors Avoid sudo; reinstall with the official installer or fix npm permissions
Risky automation Use sandboxing, deny rules, and hooks
Model alias changed Check official model docs and changelog

For most individual developers:

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)",
      "Bash(git status *)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)",
      "Bash(docker *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf *)"
    ]
  },
  "defaultMode": "plan"
}

Use defaultMode: "plan" when onboarding a repo or doing risky refactors. Switch to acceptEdits only after the permission rules and test workflow are stable.

19. Bottom Line

Claude Code’s power does not come from one command or one hidden model flag. It comes from combining:

project memory
+ scoped permissions
+ repeatable commands
+ subagents
+ MCP connectors
+ hooks
+ verification loops

The winning workflow is not “let the agent do everything.” It is “give the agent enough context, enough tools, and enough constraints to safely complete a narrow task.”

If you remember one formula, use this:

\[\text{useful Claude Code session} ================================= \text{clear goal} + \text{relevant context} + \text{safe tools} + \text{fast verification}\]

References