The Complete Guide to Claude Code: Agentic Coding in Your Terminal

What Claude Code Is

Claude Code is an agentic coding tool that runs in your terminal. Unlike Claude.ai — where you paste code into a chat window and manually apply suggestions — Claude Code reads your local files directly, writes changes to disk, and executes shell commands. Changes happen in your actual repository.

This is the distinction that matters: Claude Code operates on your real codebase. It can explore your project structure, understand the context of what's already built, write changes across multiple files simultaneously, run your tests, and report results — all in a single session.

Installation

Prerequisites

Claude Code requires Node.js 18 or higher. Verify your version:

node --version

Install Globally

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

This makes the claude command available in any terminal.

Windows PowerShell Setup

On Windows, two additional steps may be required after install:

1. Add npm global directory to PATH

If claude is not found after install:

npm config get prefix
# Typical output: C:\Users\[Username]\AppData\Roaming\npm

Add this path to your system PATH via System Properties → Environment Variables → Path → New.

2. Allow script execution

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Configure Your API Key

macOS / Linux:

echo 'export ANTHROPIC_API_KEY=sk-ant-...' >> ~/.zshrc
source ~/.zshrc

Windows PowerShell (add to $PROFILE for persistence):

$env:ANTHROPIC_API_KEY = "sk-ant-..."

Or set it permanently via System Properties → Environment Variables.

Your First Session

Navigate to a project and start:

cd /your/project
claude

Claude Code opens an interactive REPL. Try:

What does this project do? Give me a 3-sentence summary based on the files you can see.

Watch it read your actual files — no pasting required.

For a one-off task without entering interactive mode:

claude -p "List all TypeScript components and the props each one accepts"

CLAUDE.md: The Most Important File You Will Create

CLAUDE.md is a Markdown file in your project root that Claude Code reads automatically at the start of every session. It is your persistent project instructions — tech stack, conventions, commands, and constraints.

A complete CLAUDE.md has six sections:

# [Project Name] — Claude Code Instructions

## Tech Stack
- React 18 + TypeScript (strict mode)
- Tailwind CSS — utility classes only
- Supabase v2 for database and auth
- Vitest + Testing Library for tests
- Lucide React for icons (no other icon library)

## Conventions
- One component per file, PascalCase
- All Supabase calls in src/services/, never in components
- No any/unknown TypeScript types
- Named exports only from utilities

## Project Structure
src/
  components/   # Shared UI organized by category
  pages/        # Route-level components
  services/     # All data fetching and mutations
  hooks/        # Custom React hooks
  types/        # TypeScript interfaces

## Commands
- Test: npm run test
- Typecheck: npm run typecheck
- Build: npm run build

## Workflow
- Run typecheck before reporting any task complete
- Fix failing tests before proceeding to next task

## Constraints
- Do not add npm packages without explicit permission
- Do not modify src/legacy/ — frozen code
- Never use console.log — use the project logger

Generate an initial CLAUDE.md automatically:

claude
/init

Claude Code analyzes your codebase and produces a draft. Review it and add conventions that are not visible from the code itself — team rules, frozen files, architectural decisions.

Slash Commands

`/init` — Generate CLAUDE.md from codebase analysis. Always review the output.

`/clear` — Reset conversation history. Claude still has filesystem access; only the conversation resets. Use when Claude starts making inconsistent decisions after a long session.

`/compact` — Compress conversation into a summary, preserving the task thread. More useful than /clear when you want to continue the same long task without starting over.

`/memory` — View and edit persistent memory that survives across sessions and projects. Use for personal cross-project conventions.

`/status` — Show current model, context size, and working directory.

Working Modes

Interactive mode — The default REPL for multi-step tasks and debugging:

claude

One-shot mode — Single task, then exit. Best for automation:

claude -p "Add TypeScript strict types to all form component props in src/components/forms/"

Continue mode — Resume the most recent session with its history intact:

claude --continue

Agentic Task Framing

Structure complex tasks with four components for maximum autonomous accuracy:

GOAL: Add server-side pagination to the TaskList component.
Page size 20. Show current page and total count.

SCOPE: src/components/TaskList.tsx,
src/services/tasks.service.ts,
src/hooks/useTasks.ts

VERIFICATION: Run npm run typecheck and npm run test.
Both must pass before reporting complete.

ESCALATION: If existing tests require structural changes
beyond updating page parameters, stop and describe
what you found before proceeding.

The Explore-Plan-Execute Pattern

For risky refactors or anything touching many files:

I need to migrate auth state from React Context to Zustand.

First, produce a plan:
- List every file that imports from AuthContext
- Describe what each file uses
- Flag any complications
- Propose a migration sequence

Do not make any changes yet. Show me the plan.

Review the plan. Then:

The plan looks correct. Proceed in the order described.
Run typecheck after each file. Stop if tests need significant rework.

Combining Claude Code with Claude.ai

Claude.ai — Better for architecture decisions, technical writing, tradeoff exploration, and code review from a fresh perspective.

Claude Code — Better for implementation, multi-file changes, running tests, and autonomous execution against your real project.

The workflow: design in Claude.ai, implement in Claude Code.

[Claude.ai]
Design a notification system for a React + Supabase app.
Output a technical spec I can hand to my coding tool.

[Claude Code]
Implement the notification system based on this design:
[paste design]
Read CLAUDE.md for conventions.
Run typecheck and tests after each major step.

Git Is Your Safety Net

Always use Claude Code inside a git repository with a clean working tree:

git status      # Confirm clean before starting
# After session:
git diff        # Review all changes
git add -p      # Stage interactively, hunk by hunk
git commit      # Only after review

If something went wrong:

git checkout .  # Discard all unstaged changes
git clean -fd   # Remove untracked files

Without git, Claude Code's file changes are permanent. With git, everything is tracked and reversible.

For the security model, permissions configuration, and what to auto-approve: Claude Code Security Model, Permissions, and Safe Workflow Practices.

Explore the full lesson-by-lesson Claude Code tutorial.