0

How Claude Code Actually Works on Your Machine

Posted by

Claude Code isn’t a chatbot that suggests code. It’s an autonomous agent that inhabits your terminal, reads your entire codebase, runs commands, edits files, commits changes, and iterates until the job is done — all from a single natural language instruction.

Table of contents

The Fundamental Shift: From Autocomplete to Autonomous Agent

To understand what Claude Code is, you first need to understand what it isn’t. Traditional AI coding tools — think GitHub Copilot — live inside your editor and predict what comes next as you type. They’re reactive, single-file, and purely suggestive. You remain the executor.

Claude Code flips this model entirely. It is what Anthropic calls an agentic coding tool: you describe a high-level goal, and Claude Code breaks it into steps, executes those steps, reads feedback from your environment (test output, errors, lint warnings), and iterates autonomously until the goal is met. The developer’s role shifts from writing code to reviewing and directing code.

The difference comes down to autonomy and scope. When you tell Claude Code to “add pagination to the user listing API,” it doesn’t paste a snippet. It locates the relevant endpoint, analyzes the current implementation, adds pagination logic following your existing patterns, updates related tests, ensures consistency with database queries, and potentially touches a dozen files — all without you manually orchestrating each step.

Installation and Environment Setup

Installing Claude Code

Claude Code is installed as a command-line tool, available via multiple methods depending on your operating system:

  • macOS/Linux: Install via the Homebrew tap or directly as a binary
  • Windows: Requires Git for Windows to be installed first
  • npm (legacy): Direct npm installation is now deprecated in favor of the above methods

Once installed, you run claude from any directory. That launches the interactive REPL (Read-Eval-Print Loop), Claude Code’s primary interface.

Where It Lives on Your Machine

Claude Code creates a hidden .claude/ directory in your home folder (~/.claude/) for global, user-level settings, and another .claude/ directory at your project root for project-specific configuration. Here’s what lives in each:

~/.claude/
├── CLAUDE.md              ← Global user instructions (personal preferences)
├── settings.json          ← Global permissions and behavior settings
└── projects/              ← Session transcripts and auto-memory per project

<your-project>/
├── .claude/
│   ├── settings.json      ← Project-level permissions, hooks, MCP config
│   ├── settings.local.json ← Personal overrides (git-ignored)
│   ├── commands/          ← Custom slash commands
│   ├── agents/            ← Custom subagent definitions
│   └── skills/            ← Reusable knowledge modules
└── CLAUDE.md              ← Project-level persistent instructions

The First Thing It Does: Reading Your Codebase

When you run claude from a project directory, Claude Code runs from the project root, giving it full visibility into the entire codebase. This is not superficial. Claude Code:

  1. Understands the directory structure and file relationships across the whole project
  2. Reads dependency manifests (package.json, requirements.txt, Cargo.toml, etc.) to understand your tech stack
  3. Identifies build commands, test runners, linters, and other tooling
  4. Locates configuration files to understand environment and deployment context

This full-codebase awareness is why Claude Code can maintain consistency across changes that span dozens of files. When refactoring a data model, it updates every reference, aligns type definitions, handles database migration edge cases, and adds test coverage for the new structure.

CLAUDE.md: The Persistent Memory System

One of Claude Code’s most useful features is CLAUDE.md — a special Markdown file that Claude automatically reads and injects into its system prompt at the start of every session.

Think of it as a letter left for Claude each morning: “Here’s everything you need to know about this project before you start work.”

The Three-Tier Memory Hierarchy

CLAUDE.md files operate in a priority-ordered hierarchy:

  1. Local project memory (<project>/.claude/CLAUDE.md) — Project-specific, personal preferences, git-ignored
  2. Project memory (<project>/CLAUDE.md) — Shared with the whole team, version-controlled
  3. Global user memory (~/.claude/CLAUDE.md) — Applies across all projects on your machine

The precedence rule is: Local > Project > Global. The most specific instruction wins in any conflict.

What Goes in CLAUDE.md?

A well-structured CLAUDE.md typically includes:

# Architecture
- pnpm monorepo with 3 packages: api, web, shared
- Database: PostgreSQL 16 via Prisma 5.x
- Deployment: Docker on Fly.io

# Conventions
- Component names in PascalCase
- Custom hooks prefixed with `use`
- No `any` in TypeScript — use `unknown` and narrow
- All API routes must have JSDoc comments

# Commands
- Build: `pnpm build`
- Tests: `pnpm test --run`
- Lint: `pnpm lint`
- Type check: `pnpm typecheck`

# Important Notes
- The auth module is in active refactoring — do not touch /src/auth/legacy/
- Use the `db` import from shared/db, never import prisma directly

Teams using a shared, well-structured CLAUDE.md of around 120 lines report roughly 35% fewer code review comments related to conventions. Files under 200 lines achieve a rule application rate above 92%, while files beyond 400 lines see this drop to 71%. Keep it focused.

Auto-Memory

Beyond what you write yourself, Claude Code also auto-generates memory as it works. When it discovers important truths about your project — the exact build command, a non-obvious debugging trick, a dependency quirk — it can write these findings to a MEMORY.md file so they persist across future sessions, without you having to document them manually.

How Claude Code Executes a Task: The Core Loop

When you give Claude Code a task (say: “Add rate limiting to the /api/auth/login endpoint”), here is the mechanical sequence of what happens:

1. Context Loading

Claude reads CLAUDE.md files from all applicable tiers, loads session history if resuming, and constructs a full context window representing its current “knowledge state” of the project.

2. Planning Phase

Claude creates a step-by-step plan before writing any code. This typically involves:

  • Identifying all files that will be touched
  • Mapping dependencies between those files
  • Determining the correct order of operations
  • Surfacing potential risks or conflicts

In “Plan Mode” (which can be toggled), Claude shows you this plan and waits for your approval before executing. This is a critical human-in-the-loop checkpoint.

3. Exploration (The Task(Explore) Subagent)

Before implementing, Claude often launches a built-in Explorer subagent that scans the codebase for relevant files, patterns, and existing implementations. This subagent runs in its own isolated context window — crucial for preserving the main agent’s context budget. It returns only a summary of findings to the parent agent.

4. Implementation (Multi-File Editing)

Claude Code uses a diff-based editing system. Rather than rewriting entire files, it sends precise, targeted patches. This is more efficient and makes changes easier to review. A single task might:

  • Modify route handlers
  • Create new middleware
  • Update database schemas
  • Adjust configuration files
  • Update documentation
  • Add or update test coverage

5. Verification Loop

After making changes, Claude Code doesn’t just declare success — it verifies. It runs your test suite, lint checks, type checks, and starts dev servers if needed. If something fails, it reads the error, traces it back through the change it made, and iterates automatically. This cycle repeats until:

  • All tests pass
  • No lint errors remain
  • The implementation satisfies the original requirement

6. Git Integration

Claude Code works directly with git throughout this process. It can:

  • Stage changed files
  • Write meaningful, conventional commit messages
  • Create branches for features
  • Open pull requests with detailed descriptions

The Tool System: How Claude Code Interacts with Your Machine

At its core, Claude Code is powered by a set of tools — specific capabilities that allow it to take actions in your environment. Every action Claude takes maps to one of these tools:

ToolWhat It Does
ReadReads file contents
EditMakes targeted edits to files
WriteCreates or overwrites files
BashExecutes shell commands (npm, git, grep, sed, etc.)
GlobPattern-matches file paths
GrepSearches file contents
LSLists directory contents
WebFetchFetches web pages (docs, APIs)
TaskSpawns subagents

Each tool call is visible to you in the terminal. You can watch Claude Code think step by step — which files it reads, which commands it runs, what changes it makes — so you can see exactly what it’s doing and why.

The Permission System: Control and Safety

Because Claude Code runs commands and edits files on your actual machine, Anthropic built a granular permission system to keep you in control. It operates in five modes:

  1. Default — Claude asks permission before file edits and command execution
  2. Auto-approve edits — File edits are auto-approved; commands still require approval
  3. Auto-approve all — All actions proceed without prompting
  4. Read-only — Claude can explore but not modify anything
  5. Custom — Fully configured via settings.json rules

The permission system is fail-closed: if an action doesn’t match an explicit allow rule, Claude prompts you. You can press Shift+Tab during a session to cycle through permission modes.

Rules-Based Permissions

Your .claude/settings.json can define granular allow/deny rules:

{
  "permissions": {
    "allow": ["Bash(npm run test)", "Bash(npm run build)"],
    "deny": ["Bash(rm -rf *)", "Read(.env)"]
  }
}

The evaluation order is always: deny rules first, then ask, then allow. First match wins.

Hooks: Deterministic Code at Every Step

Hooks are an underappreciated part of Claude Code. They let you attach shell scripts or HTTP endpoints to specific events in the Claude Code lifecycle, running deterministic code at precise moments regardless of what the AI decides to do.

The hook event timeline looks like this:

Session Start
    → [SessionStart hook]
        ↓
User submits prompt
    → [UserPromptSubmit hook]
        ↓
Claude decides to call a tool
    → [PreToolUse hook] ← can BLOCK or MODIFY the call
        ↓
Tool executes
    → [PostToolUse hook] ← can react to results
        ↓
Permission dialog about to show
    → [PermissionRequest hook] ← can auto-approve or deny
        ↓
CLAUDE.md loaded
    → [InstructionsLoaded hook] ← useful for audit logging

Hook Exit Codes

Hooks communicate back to Claude Code via exit codes and JSON:

  • Exit 0 — Allow; optionally return JSON with additional context for Claude
  • Exit 2 — Block the action entirely (hard stop)
  • JSON output on exit 0 — Fine-grained control: allow, deny, or escalate to user

Practical Hook Examples

  • Auto-format on save: Run Prettier after every Edit tool call on .ts files
  • Type-check gate: Run tsc --noEmit before accepting any TypeScript edit
  • Date injection: Run a script at SessionStart that injects today’s date into context (so Claude always knows the correct current date)
  • Lint-before-commit: Run ESLint before every Bash(git commit) call
  • Security guard: Block any Bash command matching dangerous patterns like DROP TABLE

Custom Slash Commands: Packaging Repeatable Workflows

Every project has repetitive workflows — PR reviews, deployments, scaffolding new components, running specific test suites. Instead of typing the same long prompts repeatedly, Claude Code lets you package these into custom slash commands.

How Commands Are Structured

Create a file at .claude/commands/review-pr.md:

Please review the changes in the current git diff. Check for:
1. Logic errors and edge cases
2. Security vulnerabilities (SQL injection, XSS, IDOR)
3. Missing test coverage
4. Performance regressions
5. Violations of our conventions in CLAUDE.md

Return a structured report with a PASS/FAIL summary and itemized findings.
Arguments: $ARGUMENTS

Now you can run /review-pr or /review-pr focus=security. Commands accept $ARGUMENTS as a placeholder for runtime parameters.

Built-in slash commands include:

  • /clear — Wipe conversation history for a clean slate
  • /compact — Summarize and compress the context window to save tokens
  • /model — Switch between Claude models mid-session
  • /bug — Report a Claude Code issue directly to Anthropic
  • /hooks — Interactive menu-based hook configuration
  • /init — Initialize a new project with a CLAUDE.md and settings scaffold

Subagents and Multi-Agent Orchestration

For complex, long-horizon tasks, Claude Code goes beyond a single agent. The Task tool allows the main Claude agent to spawn specialized subagents, each operating in their own isolated context window.

Built-in Subagents

  • Explorer — Scans the codebase to find relevant files, patterns, and relationships
  • Planner — Analyzes Explorer’s findings and produces a structured implementation plan
  • General-purpose agents — Execute the tasks defined in the plan

Why Subagents Matter: Context Window Management

Each subagent works in its own context window and only returns its conclusion to the parent. This matters because it prevents the main agent’s context from filling up with intermediate exploration noise. On a massive codebase, the Explorer might read hundreds of files to find the five that matter — but the parent agent only sees the clean summary.

Parallel Multi-Agent Workflows

Claude Code also supports spawning multiple agents to work simultaneously:

  • A lead “orchestrator” agent coordinates the overall plan
  • Multiple worker agents attack different subtasks in parallel (e.g., one writes the backend endpoint while another writes the corresponding frontend component and a third writes the tests)
  • The orchestrator merges results and resolves conflicts

This mirrors how engineering teams actually work, and it compresses the time needed for large features.

MCP: Connecting Claude Code to the Rest of Your Stack

The Model Context Protocol (MCP) is an open standard that lets Claude Code reach beyond your local filesystem and shell to interact with external tools and data sources.

How MCP Works

MCP servers act as bridges between Claude Code’s terminal environment and other applications. You configure them in .mcp.json at the project level or ~/.claude.json globally. Once connected, Claude Code can call these services directly as tools during its reasoning process.

What You Can Connect

Popular MCP integrations include:

  • Google Drive / Notion — Read design docs, PRDs, and specs directly
  • Jira / Linear / Asana — Create, update, and close tickets as part of workflows
  • Slack — Post deployment notifications or retrieve context from threads
  • Figma — Pull design tokens and layout specs
  • GitHub / GitLab — Open PRs, read issue details, check CI status
  • Databases — Query schemas, run migrations, seed test data
  • Custom internal tooling — Any service you wrap in an MCP server

A workflow that used to involve you copying a Jira ticket description into the terminal, fetching a Figma spec, and then writing code can now happen in a single command: “Implement the UI for PROJ-4521 according to the Figma spec in the design system folder.”

CI/CD Integration: Claude Code Without a Human

Claude Code isn’t limited to your local machine. Via GitHub Actions or GitLab CI/CD, it can run as part of your automated pipelines:

  • Automated code review: Trigger Claude Code on every opened PR to check for bugs, security issues, and style violations, then leave review comments
  • Issue triage: When a new GitHub issue is opened, Claude Code can reproduce the bug, trace it to the root cause, and suggest a fix
  • Automated test generation: On every commit, generate missing test coverage for changed code
  • Documentation sync: Keep API docs, READMEs, and changelogs in sync with code changes

In CI contexts, Claude Code runs in headless mode using the --dangerously-skip-permissions flag (appropriate when operating in an isolated, ephemeral container with no persistent state to protect).

Context Management: The Critical Skill

Claude Code’s context window — the amount of conversation and code it can hold in “working memory” at once — is finite. Managing it well is the difference between productive long sessions and degraded, confused output.

The Problem: Context Rot

As a session grows longer, earlier instructions and context get diluted in the window. Claude may “forget” architectural decisions made early in the conversation, produce inconsistent code, or repeat work it has already done. This is called context rot.

Strategies for Managing Context

/clear — The most important habit. Between distinct tasks, wipe the context entirely. A fresh session with a good CLAUDE.md is more effective than a stale 10,000-token conversation.

/compact — Rather than wiping, this command asks Claude to summarize the current conversation into a dense, token-efficient representation and continue from there. Useful when you need to preserve some session state.

Auto-compaction — Claude Code can be configured to auto-compact when the context reaches a fill threshold (controllable via CLAUDE_AUTOCOMPACT_PCT_OVERRIDE).

Subagents for isolation — Delegate exploration and research to subagents so that detailed intermediate work doesn’t pollute the main agent’s context.

Small, focused prompts — Rather than “build me the entire user authentication system,” break it into: “Build the login endpoint,” then start fresh and “Build the registration endpoint.” Smaller, tighter prompts yield better reasoning and fewer hidden assumptions.

The .claude/ Folder: Complete Anatomy

Here’s the full picture of every file and folder inside a well-configured .claude/ directory:

.claude/
├── settings.json           ← Permissions, hooks, env vars, UI customization
├── settings.local.json     ← Personal overrides — always git-ignored
├── .mcp.json               ← MCP server configurations
├── commands/               ← Custom slash commands
│   ├── review-pr.md
│   ├── deploy-staging.md
│   └── scaffold-component.md
├── agents/                 ← Custom subagent definitions
│   ├── security-reviewer.md
│   └── test-writer.md
├── skills/                 ← Reusable knowledge modules, lazy-loaded
│   ├── auth-patterns.md
│   └── db-conventions.md
└── hooks/                  ← Hook scripts
    ├── PreToolUse.ts
    ├── PostToolUse.sh
    └── SessionStart.sh

Environment Variables: Fine-Grained Control

Claude Code recognizes roughly 70 environment variables that control its behavior. The most useful ones:

VariableEffect
ANTHROPIC_DEFAULT_SONNET_MODELOverride which Sonnet variant Claude uses
CLAUDE_AUTOCOMPACT_PCT_OVERRIDEControl when auto-compaction triggers
ANTHROPIC_API_KEYYour API key (if using the API directly)
CLAUDE_PROJECT_DIRAvailable inside hooks and scripts

Working with Images and Visual Context

Claude Code accepts images in the terminal. You can drag and drop:

  • Screenshots of UI designs — “Implement this layout from the Figma export”
  • Architecture diagrams — “Build the service described in this diagram”
  • Error screenshots — “Here’s the visual bug, find and fix it”
  • Whiteboard photos — “Here’s the data model we sketched, implement it”

This is particularly useful for frontend work, where describing a UI in words is less precise than just showing a picture.

Real-World Scale: What Claude Code Can Actually Handle

For a concrete example: Rakuten’s engineering team asked Claude Code to implement a specific activation vector extraction method in vLLM, an open-source library with 12.5 million lines of code spanning Python, C++, and CUDA. Claude Code completed the entire implementation autonomously in seven hours of sustained work, with the ML engineer providing only occasional guidance — writing zero lines of code themselves.

Anthropic’s internal surveys report that engineers using Claude Code handle roughly 60% of their work with Claude’s help and see a 50% productivity boost. The gains compound: Claude Code maintains consistency across large changes, catches edge cases, and cuts down the debugging cycle.

The Developer’s New Role: Orchestrator, Not Typist

Claude Code does not eliminate the need for engineers. It changes the nature of the work.

With Claude Code, your job becomes:

  • Defining clear goals — Claude performs best when it understands why something exists, not just what to build
  • Reviewing proposed changes — You maintain control by approving plans and reviewing diffs
  • Setting guardrails — CLAUDE.md, permissions, and hooks encode your standards
  • Architecting at a higher level — Claude handles the routine; you focus on the design decisions that matter

The developers who get the most from Claude Code treat it not as a magic code generator, but as an exceptionally capable junior engineer who needs clear requirements, good context, and thoughtful review.

Summary: The Full Picture

Claude Code works on your machine by doing the following in concert:

  1. Inhabiting your terminal — running natively in your shell alongside your existing tools
  2. Reading your entire codebase — building a complete understanding of structure, patterns, and conventions
  3. Loading persistent memory — CLAUDE.md files at global, project, and local levels encode everything it needs to know
  4. Planning before acting — breaking goals into discrete, verifiable steps
  5. Executing via tools — reading, editing, writing files and running shell commands with full transparency
  6. Verifying via your own toolchain — running your tests, lint, and type checks to confirm correctness
  7. Managing context intelligently — using subagents to isolate complexity and /clear to stay sharp
  8. Integrating with everything — git, CI/CD, external services via MCP, your IDE, and the browser
  9. Learning over time — auto-memory persists discoveries across sessions
  10. Respecting your boundaries — a robust permission and hooks system keeps humans in control

The result is a development partner that can take on entire features, debug production issues, refactor legacy code, and maintain quality standards — not by replacing engineers, but by multiplying what they can get done.

Claude Code was launched as a research preview in February 2025, became generally available in May 2025, and reached $1 billion in annualized revenue by November 2025. As of March 2026, it remains one of the fastest-growing developer tools ever shipped.

“The question is not what the machine can do, but what you’ll do with the time it gives back.”-Rushi