Claude Code: fundamentals

What Claude Code is and the agent loop

Claude Code is Anthropic's agent for code. It lives in your terminal (also in the IDE and on the web) and, unlike the chat, it has tools: read and write files, run shell commands, search the code, do git, fetch the web.

Its operation is an agentic loop:

1. You give a goal.
2. It thinks, picks a tool, calls it (read a file, run a test...).
3. It observes the tool result.
4. It repeats until the goal is reached, then answers you.

That is the fundamental difference from chat: Claude Code acts, observes, corrects autonomously. You don't dictate each command, you give it a goal and a guardrail.

Install: npm install -g @anthropic-ai/claude-code then claude in your project folder. The first thing it reads is your CLAUDE.md (next lesson).

CLAUDE.md: the project memory

CLAUDE.md is a markdown file at the root of your project (or globally in ~/.claude/) that Claude Code reads automatically on startup. It is its persistent memory of your conventions.

What goes in it:

• The project's commands (build, test, lint, deploy).
• The code and style conventions.
• The absolute rules never to violate.
• The routing to other docs or sub-projects.

Pierre's CLAUDE.md is a textbook case: it encodes his non-negotiable rules (never an em-dash, no emoji, archive never delete, the exact path is 00_SEPT TOOLS with an underscore) and his session-startup routing. These instructions override the model's default behavior.

Generate a first draft with the /init command: Claude scans the repo and proposes a CLAUDE.md. You then refine it. Core rule: a short, sharp CLAUDE.md beats a sprawling one nobody respects.

The essential slash commands

Slash commands drive the session. The essentials:

• /init: generates the CLAUDE.md by scanning the repo.
• /clear: resets the context to empty. Do this between unrelated tasks, to start clean.
• /compact: summarizes old context without throwing it all away. Use it mid-task when context fills up but you want to keep continuity.
• /agents: manage the specialized sub-agents.
• /mcp: connect and manage MCP servers.
• /hooks: configure lifecycle hooks.
• /review: code review of the current diff.

The most useful daily distinction: /clear forgets everything, /compact summarizes. Too many people let context swell until quality degrades. The pro reflex: /clear when you change subject, /compact when you are mid big task.

You can also create your own slash commands (reusable prompt templates) in .claude/commands/. That is the gateway to skills (module 5).

Permissions and plan mode

Claude Code can run real commands. The permissions system controls what it does without asking you. Four core modes:

• Ask every time (cautious default): it asks before each sensitive action.
• Accept edits: it edits files without asking, but asks for the rest.
• Plan mode: it does not act, it proposes a plan first. You approve, then it executes. Ideal for big changes.
• bypassPermissions: it acts without asking anything. Fast, but no guardrail.

You set this in settings.json (global or project), also with a precise allowlist: "allow npm run build and git status without asking, but ask for any rm".

Pierre's case is instructive: he runs in bypassPermissions by default (speed), so the automatic guardrail on rm is disabled. His countermeasure is not technical but an absolute rule in the CLAUDE.md: archive to _ARCHIVES/, never delete. Lesson: the more autonomy you grant, the more your written rules matter.

Install Claude Code and first run

Claude Code is Anthropic's command-line coding agent. It reads your files, writes code, runs commands, and reasons over your entire project, all from a terminal. Before you can use it you need Node.js (the JavaScript runtime) version 18 or higher, and its bundled package manager npm (Node Package Manager). Check what you have by running node -v and npm -v in any terminal.

Install Claude Code globally with a single npm command so it is available from any folder on your machine:

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

The -g flag means "global": npm places the claude binary on your system path. Once installed, authenticate once by running claude with no arguments. Claude Code opens a browser window (or prints a URL) so you can log in with your Anthropic account. Your credentials are stored locally and reused in every future session.

Where you launch Claude Code matters. The home directory is your user folder (for example C:\Users\yourname on Windows or /Users/yourname on Mac). Starting Claude there loads only your global memory and settings. The project directory is the folder that holds your code. Starting Claude inside it loads project-specific memory and gives Claude Code full context about that codebase. Always cd into your project first, then run claude.

• Requirement: Node.js 18+ and npm (both come with a standard Node install).
• Install: npm install -g @anthropic-ai/claude-code
• First launch: run claude and complete the browser login.
• Every session after that: cd your-project then claude.

The prompt box: modes and steering

The Claude Code prompt box does more than accept text. It is also a steering wheel you can grab at any point during a task. Understanding its modes keeps you in control instead of waiting helplessly for a long run to finish.

When Claude Code is running, pressing Escape sends an interrupt signal (a request to stop the current action). Claude Code finishes the atomic step it is on, then pauses and returns control to you. You can then redirect, correct, or continue with a new instruction.

For multiline input (multiple lines in one prompt, useful for pasting a spec or a code block), press Shift+Enter to insert a newline without submitting. Press Enter alone to send.

Three prompt modes let you shape how Claude Code responds:

• Normal mode: type your instruction and press Enter. Claude Code picks tools and acts autonomously.
• Plan mode (--plan): Claude Code drafts a step-by-step plan and waits for your approval before touching any file.
• Auto-accept mode (--dangerously-skip-permissions): all permission prompts are skipped automatically. Use only in a safe sandbox, never on production files.

Pointing at files with @

In Claude Code, the @ reference is how you point at a file or folder without copying its contents. Type @ followed by a path and Claude Code reads that file directly from your disk. This means you never have to paste walls of code into the chat.

As you type @, Claude Code shows a tab-completion menu of files and folders in your project. Press Tab to cycle through matches and Enter to confirm. You can reference multiple items in one message.

Why does this beat pasting? Three reasons:

• Accuracy: Claude reads the file as it exists on disk, so nothing is lost to copy-paste errors or outdated clipboard contents.
• Context efficiency: Claude Code sends only what it needs from the file, keeping your context window (the total amount of text Claude can hold in memory at once) from filling up unnecessarily.
• Folder references: Pointing at a folder with @src/ lets Claude scan the whole directory tree and pick the relevant files itself, which would be impractical to paste manually.

You can mix @ references with plain instructions in the same message. For example: Review @src/auth.js and check @tests/auth.test.js for missing coverage.

Running shell commands

Claude Code can execute real shell commands on your machine through its built-in Bash tool. A shell (also called a terminal or command line) is the text interface that controls your operating system. When you ask Claude Code to install a package, run tests, or check a file, it sends those commands to the Bash tool and reads the output before responding.

Before running any command, Claude Code shows you what it is about to execute and waits for your approval. This permission prompt is your safety gate. You can approve the command, edit it, or deny it. Once approved, the output feeds directly back into Claude Code so it can react to errors or results without you copying and pasting anything.

You can control which commands need approval. The allowed list in your settings lets you whitelist safe commands (such as npm test or ls) so they run without interruption. Dangerous operations like deleting files will still prompt unless you explicitly allow them.

• Read output: Claude Code sees stdout and stderr (the normal output and the error stream) and reasons about them.
• Multi-step chains: It can run several commands in sequence, using the result of one to decide the next.
• Background tasks: Long-running commands (like a dev server) can be launched in the background so the session stays responsive.
• Working directory: Commands run in the project folder you opened, not in a random location.

Reading and approving edits

When Claude Code modifies a file it shows a diff (short for "difference"), a side-by-side or inline view where lines marked with - are removed and lines marked with + are added. Nothing is written to disk until you approve.

Claude Code aims for surgical edits: it touches only the lines that need to change, leaving the rest of the file intact. This keeps diffs small and easy to review. If a proposed change looks larger than expected, that is a signal to read carefully before accepting.

You have three responses available each time an edit is proposed:

• y / yes: accept and write the change to disk.
• n / no: reject and ask Claude Code to try a different approach.
• e / edit: open the diff in your editor so you can adjust it manually before saving.

If you are running Claude Code with the --dangerously-skip-permissions flag (auto-approve mode), all edits are written immediately without a prompt. Use that flag only in throw-away environments where speed matters more than review.

Git from inside Claude Code

Claude Code understands Git (the version-control system that tracks every change to your code) natively. You can describe what you want in plain English and Claude Code will run the right Git commands, explain the output, and ask before doing anything destructive.

The four everyday Git operations Claude Code handles for you are: checking status (what has changed), reading a diff (the exact lines added or removed), writing a commit message (a saved snapshot with a description), and opening a pull request (a formal proposal to merge your changes into the main codebase).

Claude Code also manages branches (parallel versions of the codebase). You can ask it to create a branch, switch to one, or merge changes, all without memorising flags. The key commands it runs under the hood are git status, git diff, git add, git commit, git checkout -b, and gh pr create (using the GitHub CLI).

• Status: "What files have I changed?" Claude Code runs git status and summarises.
• Diff: "Show me what changed in auth.js." Claude Code runs git diff auth.js and explains the changes in plain English.
• Commit: "Commit these changes with a good message." Claude Code stages files and writes a concise, conventional commit message.
• Branch: "Create a branch called fix/login-bug." Claude Code runs git checkout -b fix/login-bug.
• Pull request: "Open a PR to main with a summary." Claude Code uses gh pr create and drafts the title and body for you.

The task list

When you give Claude Code a complex, multi-step job, it does not hold the entire plan in its head invisibly. Instead, it maintains a task list: a structured checklist of subtasks it creates at the start of the job and updates as it works. Think of it as a shared whiteboard between you and the agent.

The task list serves two purposes. First, it keeps Claude Code on track across many file edits, tool calls, and decisions. Second, it lets you watch progress in real time without reading every line of output. Each item moves from "pending" to "in progress" to "completed" (or "blocked") as the session advances.

You can interact with the task list at any point:

• Type a follow-up message to add a new subtask or reprioritize existing ones.
• Ask Claude Code to pause after a specific task so you can review before it continues.
• Say "skip step 3" or "focus only on steps 1 and 4" and the agent will adjust.
• If a task is blocked (for example, a missing file), Claude Code will flag it and wait rather than silently skip it.

In the VS Code extension and the web interface, the task list appears as a collapsible sidebar panel. In the CLI (command-line interface, the terminal version), it is printed inline as the session runs. Either way, completed items are checked off and the current item is highlighted.

Plan mode in depth

Plan mode is a read-only phase in Claude Code where the agent analyzes your codebase and proposes a structured plan before writing or modifying a single file. Think of it as a blueprint review: Claude maps out every step, and nothing changes on disk until you give the go-ahead.

To enter plan mode, pass the --plan flag when you start a task, or type /plan inside an active Claude Code session. Claude will read files, trace dependencies, and output a numbered action list. During this phase it has no write permissions, so it cannot accidentally overwrite your work.

Once the plan appears, you have three options:

• Approve: type yes or press Enter to let Claude execute every step in order.
• Edit: paste the plan back with your corrections, then approve the revised version.
• Abort: type no or press Ctrl+C to cancel without touching any file.

Use plan mode whenever a task touches multiple files, involves a risky refactor, or when you want a second opinion before committing changes. It costs a bit more time upfront but prevents hard-to-reverse mistakes and gives you a clear audit trail of what Claude intends to do.

Permission modes and bypass

Claude Code asks for your approval before taking actions like editing files or running commands. How often it asks depends on its permission mode, a setting that controls the balance between safety and speed.

There are four modes you need to know:

• default: Claude asks before every file edit and every shell command. Safest, but requires the most clicks.
• acceptEdits: Claude applies file edits automatically but still asks before running shell commands. A common middle ground for coding sessions.
• plan: Claude only reads and plans; it never writes or executes anything. Useful when you want to review a strategy before committing.
• bypassPermissions: Claude acts without asking for any approval. Maximum speed, minimum safety net.

You can set a mode for a single session with the --permission-mode flag (for example, claude --permission-mode acceptEdits), or you can lock it in for a project by adding it to .claude/settings.json under the key permissionMode.

The safety tradeoff is real: bypassPermissions removes the guardrail that catches accidental deletions or destructive shell commands. Use it only in throwaway environments, sandboxes, or when you have version control and know exactly what Claude will do.

The status line

Every time Claude Code responds, a status line appears at the bottom of the terminal. It gives you a live snapshot of three things: how much of the context window (the total memory Claude can hold for your session) you have used, the estimated cost of the session so far in USD, and the active model identifier.

The context usage is shown as a fraction and a percentage, for example 12 340 / 200 000 tokens (6%). A token is roughly three to four characters of text. When you approach 100 percent, Claude begins to lose the earliest parts of the conversation, so watching this number helps you decide when to start a fresh session with /clear.

The status line is driven by a small script called statusline.cjs. Claude Code sends a JSON object to that script after each turn. The object includes these fields:

• context_window: tokens used and total capacity.
• cost: cumulative USD for the session.
• rate_limits: rolling usage over the last 5 hours and 7 days (these fields are absent when Claude Code does not emit them, so the usage bar simply disappears rather than showing stale data).
• model: the active model id, for example claude-sonnet-4-6 or claude-opus-4-8.

You can fully customize what the status line displays by editing statusline.cjs in your Claude Code config folder. Parse the incoming JSON with Node.js (not jq, which may not be installed) and format the output string however you like: color codes, extra fields, abbreviated labels, or anything else your terminal supports.

/init and onboarding a repo

When you open a project for the first time in Claude Code (the CLI and IDE coding agent), run /init in the chat panel. Claude Code scans your repository and generates a file called CLAUDE.md at the project root. This file is the single source of truth Claude reads at the start of every future session, so it never has to rediscover what the project is about.

During the scan, /init inspects several things:

• Package manifests and lock files (package.json, pyproject.toml, go.mod, etc.) to identify the language and dependencies
• Framework config files (Astro, Next.js, Vite, Django, and so on) to understand the build system
• Common entry points such as src/index.* or main.* to map the project structure
• Existing README or CONTRIBUTING files for conventions the team already documented

The resulting CLAUDE.md contains a short project description, the commands for running, testing, and building the project, any coding conventions Claude inferred, and a placeholder section for you to add team rules manually. You should review and edit this file before committing it: remove anything wrong, add constraints Claude missed (environment variables, forbidden packages, style rules), and keep it concise because Claude reads every word on each session start.

Once CLAUDE.md exists, every collaborator (human or agent) who opens the repo in Claude Code inherits the same context automatically. If the project evolves, re-run /init at any time to refresh the file, or edit it directly like any other text file.

Keyboard shortcuts and vim mode

Claude Code runs inside your terminal, so it relies on keyboard shortcuts rather than mouse clicks. Learning a handful of bindings turns slow, repetitive interactions into fast, fluid ones. The shortcuts below work in the default readline mode (the standard line-editing layer built into most Unix-style shells and terminals).

The most valuable bindings during a session are navigation and history. Ctrl+A jumps to the start of the current line, Ctrl+E jumps to the end. Ctrl+U clears everything before the cursor, which is faster than holding Backspace. Ctrl+W deletes the last word. To cycle through your prompt history, use the Up arrow and Down arrow keys, or use Ctrl+P (previous) and Ctrl+N (next) as alternatives.

Claude Code also ships an optional vim mode for the prompt input. Vim is a keyboard-driven text editor whose "modal" design lets you switch between inserting text and issuing movement or editing commands. To enable it, run /vim inside a Claude Code session. Once active, the input starts in Insert mode (type normally). Press Escape to enter Normal mode, where single keys become commands: h j k l for movement, dd to delete a line, 0 to go to the start, $ to go to the end. Press i to return to Insert mode. Press Enter in either mode to submit the prompt.

A few additional shortcuts are worth knowing at the session level:

• Ctrl+C: interrupt (cancel) the current running task without closing the session.
• Ctrl+L: clear the terminal screen while keeping the session alive.
• Ctrl+R: reverse-search your prompt history (type a fragment to find a past prompt).
• /clear: typed command that resets the conversation context inside Claude Code.
• /vim: toggle vim mode on; run it again to toggle it off.