The Complete Claude Code Guide: From First Install to Daily Workflow (2026)

Claude Code is Anthropic's de-facto-standard terminal-native agentic coding tool, released in 2025 and rapidly adopted across the Claude ecosystem. Built on Claude Sonnet / Opus, it pairs CLAUDE.md project memory with a tool-use loop and MCP server extensibility — you describe what you want in plain language, and it edits files, runs commands, searches the codebase, and ships features. This guide, current as of August 2026, covers: full install and config, /init project seeding, CLAUDE.md memory strategy, allow/deny permission boundaries, the six commands you actually use, and a daily workflow that holds up on a real codebase.

TL;DR

• Claude Code = the terminal-native agentic coding tool; CLI is the global package @anthropic-ai/claude-code
• Three core mechanics: CLAUDE.md memory + tool-use loop + MCP server extension
• 2026 status: Claude Code and Claude Agent SDK are two sides of the same coin (CLI is the Agent SDK's headless mode)
• Install: npm i -g @anthropic-ai/claude-code → run claude from the project directory
• First-time essentials: /init lets Claude explore the project and generate CLAUDE.md; then /login for auth
• Permissions via allow / deny allowlist — avoid bypassPermissions unless running in a sandbox

Installing Claude Code

Claude Code is a terminal tool distributed as an npm package. You need Node.js installed first (any recent LTS version works), then:

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

This installs the claude command globally. Verify it is on your path:

claude --version

On first launch, claude walks you through authentication using your Anthropic account (or an API key, or a supported Bedrock / Vertex backend). Once authenticated, navigate into a project directory and run claude with no arguments to start an interactive session. Claude Code is designed to run from the root of your repository so it can read the whole project for context.

There is no separate IDE plugin required. Claude Code works in any terminal, and there are optional integrations for editors like VS Code and JetBrains that launch a session from inside the editor. The terminal is the canonical interface.

Seeding a project with /init

The first command worth running in a new project is /init. It asks Claude to explore your codebase and generate a CLAUDE.md file that captures the essentials a new contributor needs: the build and test commands, the directory layout, conventions, and any quirks worth knowing. The result is a draft you edit down to what is actually useful.

> /init

After /init finishes, open CLAUDE.md and trim anything that is wrong or already obvious. The goal is a short, accurate file — not a comprehensive one. A good CLAUDE.md is two screenfuls: how to run the tests, where the entry points are, and the conventions Claude should follow when writing code. Everything else is noise that costs tokens on every turn.

/init is not mandatory. You can write CLAUDE.md by hand and skip the draft. But running it once on a new project is the fastest way to bootstrap, because Claude reads the actual code rather than guessing.

The CLAUDE.md memory file

CLAUDE.md is the single most important configuration file in Claude Code. It is a plain Markdown file that Claude reads at the start of every session, so anything in it becomes persistent context. Think of it as the instructions you would hand to a new teammate who has never seen the codebase.

Claude Code loads CLAUDE.md from a few places, all merged:

• Project memory — ./CLAUDE.md in the repository root (and nested CLAUDE.md files in subdirectories, loaded when Claude works in that directory). Checked into git, shared with the team.
• User memory — ~/.claude/CLAUDE.md, personal preferences that apply across every project.
• Local overrides — ./CLAUDE.local.md, gitignored, for machine-specific or private notes.

Run /memory at any time to see exactly which files are loaded in the current session. This is invaluable when Claude is behaving as if it forgot something — usually the file you edited is not in the loaded list.

What belongs in CLAUDE.md? The high-value items are: build and test commands, code style and naming conventions, where new code should go, how to run the linter, and any project-specific rules ("never edit the generated dist/ directory", "always add a changelog entry"). Keep it short and imperative. Long, discursive CLAUDE.md files get skimmed by the model just like they get skimmed by humans.

Permissions: allow and deny

Because Claude Code runs commands and edits files, permissions are how you keep it from doing something you did not want. Claude Code evaluates every tool call against rules in your settings, and asks for approval the first time it tries something not covered by a rule.

There are four permission modes you can switch between in a session:

• default — asks for approval before potentially destructive actions (the normal mode).
• acceptEdits — auto-approves file edits, still asks for commands.
• plan — read-only exploration; Claude proposes a plan without making changes.
• bypassPermissions — skips all approval prompts (use with care, typically only in sandboxed environments).

The persistent rules live in settings.json (project-level in .claude/settings.json, user-level in ~/.claude/settings.json) under permissions.allow and permissions.deny:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint)",
      "Read(./src/**)"
    ],
    "deny": [
      "Bash(rm -rf:*)",
      "Read(./secrets/**)"
    ]
  }
}

Two rules that matter in practice: deny always wins over allow (a denied action is blocked even if an allow rule matches), and hooks run before rules (a PreToolUse hook can block or approve a call regardless of the rules). Deny rules on Read and Edit also extend to the file commands Claude recognizes in Bash — cat, head, tail, sed — so you cannot accidentally read a secret file by shelling out.

Tuning permissions is how you reduce approval fatigue without going fully hands-off. A typical setup: allow the test and lint commands, allow reads of the source tree, deny anything that touches secrets or force-pushes, and leave everything else on the default ask.

Commands you will actually use

Claude Code has a set of slash commands for session control. The ones that come up daily:

• /init — generate a draft CLAUDE.md.
• /memory — show which memory files are loaded right now.
• /permissions — inspect and edit the active permission rules.
• /clear — reset the conversation context, keeping the same session.
• /compact — summarize the conversation so far to free up context window.
• /mcp — list connected MCP servers and their tools.
• /model — switch the underlying model.
• /help — list all available commands.

Beyond slash commands, the main interaction is just typing a request in natural language. You can also pipe input in: cat error.log | claude -p "what's causing this error?" runs Claude non-interactively on the piped content and prints a response, which is how you wire Claude Code into scripts and CI.

A daily workflow that holds up

The workflow that tends to produce good results on a real codebase:

1. Start from the repo root so Claude has the full project in scope. Run /memory to confirm the right CLAUDE.md is loaded.
2. Explore in plan mode first. For anything non-trivial, start with plan mode so Claude reads the code and proposes an approach before touching files. Review the plan, adjust, then drop into default mode to execute.
3. Ask for tests alongside changes. When you request a feature or a fix, ask for the test in the same turn. Claude Code is most reliable when the change and its test are written together.
4. Let it run the tests. Allow npm test (or your equivalent) so Claude can verify its own changes. A change that the agent has confirmed passes the test suite is far more trustworthy than one it has not.
5. Review every diff before accepting. Use acceptEdits for speed on mechanical changes, but switch back to default mode for anything subtle. The model writes code you have to maintain.
6. Commit in small chunks. Ask Claude to stage and describe logical groups of changes rather than one big commit. Conventional commit messages come out cleanly if your CLAUDE.md specifies the format.

The pattern across all of these: keep a human in the loop on decisions, let Claude handle the typing. Claude Code is fast at the mechanical work — reading a directory, writing a boilerplate change, running the tests, regenerating a fixture — and weakest when asked to make product judgement calls unsupervised. Lean into the first, supervise the second.

Customizing with skills, commands, and hooks

Once the basics click, the customization layer is where Claude Code gets powerful on a specific project.

• Skills package repeatable procedures into a SKILL.md the model loads on demand — covered in depth in our Claude Code Skills guide.
• Custom slash commands live in .claude/commands/ as Markdown prompt files; type /project:your-command to run them.
• Hooks run scripts at lifecycle events (PreToolUse, PostToolUse, Stop) for things like auto-formatting after every edit or blocking dangerous commands.

These compose. A mature setup might have a skill for the code-review checklist, a slash command for the deploy procedure, and a PostToolUse hook that runs the formatter on every file Claude writes. The payoff is that Claude behaves the way your team expects without you re-explaining it every session.

Claude Code × MCP: wire the CLI into any tool

Claude Code automatically loads configured MCP servers at startup, letting Claude call tools directly — read Slack, query Postgres, fetch GitHub PRs, drive a browser. Two entry points:

Project-level .mcp.json (checked into git) — shared with the team:

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" }
    }
  }
}

User-level ~/.claude.json (personal) — available across projects, e.g. a private SQLite MCP server.

Load order: enterprise managed (MDM) → project .mcp.json → user ~/.claude.json, higher priority overrides lower. When the same slug (e.g. github) appears multiple times, the highest layer wins.

After startup, the /mcp command lists every server and its connection status. Common pitfall: hard-coding tokens in env gets them committed to git — the right pattern is ${ENV_VAR} placeholders + inject from a secrets manager (see the mcp-servers-configuration guide).

Permission modes: four states, and the boundaries between them

The Claude Code permissions docs define four modes, switchable mid-session:

| Mode | Behaviour | When to use | |---|---|---| | default | Asks approval before destructive actions | Daily development | | acceptEdits | Auto-approves file edits; commands still ask | Write-heavy sessions | | plan | Read-only exploration; Claude proposes, doesn't change | Refactoring / exploring unfamiliar code | | bypassPermissions | Skips all approval prompts | Sandbox only (containers, ephemeral environments) |

Pitfall 1: allow / deny rules are order-sensitive. deny always wins — if an action matches both allow and deny, it's blocked. Read and Edit deny rules also extend to equivalent Bash commands (cat, head, tail, sed), so you can't bypass a Read-deny by routing through shell.

Pitfall 2: hooks run before rules. A PreToolUse hook can block or approve a call regardless of the rules — even an allow rule can be overridden by a hook. See Claude Code Hooks docs for patterns.

Pitfall 3: bypassPermissions is one-way. Once enabled in a session, you can't roll back to "ask" mode — only restart. Use it only for temporary containers or CI environments.

In production: CI / Docker / team distribution

Shipping Claude Code into CI or Docker is the most common 2026 scaling path — per the Claude Code GitHub Actions guide:

# .github/workflows/claude.yml
on: [issue_comment, pull_request_review]
permissions:
  contents: read
  issues: write
  pull-requests: write
  id-token: write  # OIDC for Bedrock/Vertex
jobs:
  claude:
    runs-on: ubuntu-latest
    steps:
      - uses: anthropics/claude-code-action@v1
        with:
          trigger: claude_mention  # only @claude triggers, saves tokens
          allowed_users: "octocat,dependabot[bot]"

Three 2026 pitfalls:

1. OIDC audience binding with Bedrock/Vertex — id-token: write is required, and the server-side IAM role must trust the right GitHub OIDC provider (see iam docs).
2. @claude mention is case-sensitive and format-strict — must be lowercase @claude, not @Claude. Capitalisation breaks silently.
3. Fork PRs trigger the action but get no parent-repo secrets — fails with 401. Whitelist allowed_users to repo members.

Docker: drop claude-code-action into a container image with ANTHROPIC_API_KEY baked in (or via runtime injection). When the sandbox + bypassPermissions are scoped to the container, even a misbehaving Claude only damages the container, not the host.

Common Pitfalls and Anti-Patterns: CLAUDE.md, Context, and Session Management

The permission traps (allow/deny precedence, hooks running first, the bypassPermissions one-way door) are covered in the previous section. This one targets the other family of frequent incidents — "Claude didn't remember", "it forgot", "it gets worse over time". Those are almost never model-capability problems; they are context-management problems.

Pitfall 1: You edited CLAUDE.md but Claude "didn't take it in". Symptom: the rule is written down, yet new responses keep ignoring it. Cause: the file is not in the current session's load list — CLAUDE.md exists at multiple levels (project, user, subdirectory), and a file placed at the wrong level (rules in a subdirectory while you work at the repo root) is never read. Fix: run /memory to see which files are actually loaded, move the rule to the right level, and restart the session for mid-session edits to take effect.

Pitfall 2: The longer CLAUDE.md grows, the lower the compliance. Symptom: as rules accumulate, some start being ignored. Cause: the whole file is read into context every turn — long files dilute attention, burn tokens, and get skimmed, by models and humans alike. Fix: keep the body to roughly two screens; move low-frequency detail into on-demand skills or subdirectory CLAUDE.md files, which only load when Claude touches files under that path (see the official memory docs).

Pitfall 3: Long sessions "forget" early decisions. Symptom: naming and structure agreed at the start quietly get abandoned dozens of turns later. Cause: the context window scrolls — early messages are compacted or pushed out. Fix: persist important decisions the moment they are made — write them back to CLAUDE.md or a plan file instead of expecting the model to remember conversation content.

Pitfall 4: Mixing up /clear and /compact. The symptom cuts both ways: quality drops and cost rises after switching to an unrelated task — that was a missing /clear; or detail evaporates mid-task — that was a premature /compact. /clear wipes history but keeps the session, for task switches; /compact summarizes history to free up the window, for a breather inside the same task. One changes the subject, the other continues it — don't swap them.

Pitfall 5: Leaving acceptEdits on with no review. Symptom: a large batch of diffs gets silently accepted, and only the test run reveals the wrong direction. acceptEdits auto-approves every file edit — fine for mechanical bulk changes, but switch back to default and review diffs one by one for subtle logic. For managing spend over long sessions, see the official costs docs.

Real-World Walkthroughs: Three Tasks, Start to Finish

Three everyday tasks, each with the full drive pattern and the reasoning behind it. More official flows in common-workflows.

Case A: Fixing a production bug. CI is red, the log is 200 lines. Step one, read-only diagnosis in non-interactive mode: cat error.log | claude -p "find the root cause, list the files involved" — analysis and reporting only, no code changes. With the root-cause list in hand, open an interactive session to fix it; in the same turn, have it add a regression test and run npm test to prove itself. Finally, review the diff yourself and commit in small chunks. Why: separating diagnosis from repair stops the model from acting on its own assumptions while it analyzes.

Case B: A refactor across 10+ files. Migrating a callback-style REST client to async/await. Start in plan mode: have it produce a migration plan and the list of affected files; execute only after you confirm. Put "don't change public API signatures" in CLAUDE.md; execute in batches with a test run after each; close out by having it summarize a changelog. Why: the biggest risk in a large refactor is going off the rails directionally — plan mode moves the correction cost from "rewrite after it's written" to "before anything is touched".

Case C: A new feature with tests, delivered in one pass. Adding a CSV backend to the export module. One turn, three requirements: implementation, unit tests, updated docs; allow it to run npm test; after you review the diff, have it stage and commit in Conventional Commits groups. Why: generating implementation and tests in the same turn keeps the understanding of interface boundaries from drifting between sessions; grouped commits split "a feature" into independently revertable units.

Frequently asked questions

What is CLAUDE.md and how do I create it?

CLAUDE.md is a plain Markdown file Claude Code reads at the start of every session, making its contents persistent context. The fastest way to create one is to run /init in your project root — Claude explores the codebase and generates a draft capturing build commands, layout, and conventions, which you then edit down. You can also write it by hand. Run /memory at any time to see which CLAUDE.md files are currently loaded.

What are the four permission modes in Claude Code?

default asks for approval before potentially destructive actions; acceptEdits auto-approves file edits but still asks for commands; plan is read-only exploration where Claude proposes an approach without making changes; and bypassPermissions skips all approval prompts. You switch between them in a session, and persistent allow/deny rules live in settings.json.

How do allow and deny permission rules interact?

Deny always wins. If an action matches both an allow rule and a deny rule, it is blocked. Deny rules on Read and Edit also extend to file commands Claude recognizes in Bash such as cat, head, tail, and sed, so you cannot read a denied file by shelling out. Hooks run before rules, so a PreToolUse hook can block or approve a call regardless of the permission rules.

Can I use Claude Code non-interactively in scripts or CI?

Yes. The -p flag runs Claude non-interactively on piped input and prints a response, for example cat error.log | claude -p "what's causing this error?". This is how you wire Claude Code into shell scripts, git hooks, and CI pipelines. The Agent SDK offers the same capabilities programmatically for production automation.

How does Claude Code invoke an MCP server?

It auto-loads the configured servers on startup — .mcp.json (project) + ~/.claude.json (user) + enterprise MDM. Priority: MDM > project > user, higher overrides lower. Misconfig (JSON parse error, missing token) makes Claude Code silently skip that server, but others still load. Run /mcp to see every server's connection state; claude --debug prints the handshake bytes.

What secrets do I need when running Claude Code in a container?

At minimum two: Anthropic-API-Key (auth) + GitHub-Token (if using the GitHub Action trigger). Bedrock / Vertex users also need AWS_REGION + AWS_ROLE_ARN (or the GCP equivalent). Inject secrets at container run-time via docker run -e or Kubernetes Secret references — never bake into the image layers.

My Claude Code session is getting long, slow, and expensive — what should I do?

Run /clear or /compact to manage context proactively. /clear wipes the conversation history while keeping the session — use it when switching to an unrelated task. /compact summarizes everything so far to free up the context window — use it to continue a long-running task. Also write key decisions back to CLAUDE.md or a plan file so they survive compaction.

What is the difference between CLAUDE.md, CLAUDE.local.md, and ~/.claude/CLAUDE.md — where should a rule go?

./CLAUDE.md at the repo root is team-shared project memory, checked into git. CLAUDE.local.md is gitignored and holds machine-specific or private notes. ~/.claude/CLAUDE.md is user memory for preferences spanning projects. Layer by audience: team conventions in project memory, personal habits in user memory, un-committable notes in local. Run /memory to confirm which files the current session actually loaded.

Official references

• Claude Code overview (code.claude.com)
• Claude Code quickstart
• Claude Code memory management (CLAUDE.md)
• Claude Code permissions settings
• Claude Code IAM (cloud backends)
• Claude Code MCP configuration
• Claude Code skills (extensibility)
• Claude Code GitHub Actions integration
• Anthropic — Claude Code

This article reflects publicly available information as of July 2026; relevant APIs may evolve.