Getting started with Claude Code

Who this is for

This guide is for someone who wants to use Claude Code on a real project, not just try it once. Read the install and first session first, then the project memory in CLAUDE.md, then the permission modes. By the end you should be able to install Claude Code, start a session, write a CLAUDE.md, add a subagent and know which permission mode you are in.

What it is

Claude Code is an agentic coding tool. You can use it in your terminal, in an IDE, in the desktop app and in the browser ^[2]. Most of these surfaces require a Claude subscription or an Anthropic Console account ^[2].

Before you install

Claude Code is billed by API token consumption ^[12]. Subscription plans for Pro, Max, Ultra, Team and Enterprise are listed at claude.com/pricing ^[12]. On Team and Enterprise plans, usage draws from each member's seat allowance. On the Claude Console and on cloud providers, usage is billed per token to the organisation ^[12].

If you install with npm, the package requires Node.js 22 or later ^[4].

Install and first session

On macOS, Linux and WSL, the recommended native install command is ^[2]:

curl -fsSL https://claude.ai/install.sh | bash

On Windows PowerShell, use irm https://claude.ai/install.ps1 | iex ^[2]. Homebrew installs it with brew install --cask claude-code. Homebrew offers two casks: claude-code follows the stable release channel and claude-code@latest follows the latest channel ^[2]. On Windows you can use winget install Anthropic.ClaudeCode and later update with winget upgrade Anthropic.ClaudeCode ^[2]. The quick start also lists apt, dnf and apk for Debian, Fedora, RHEL and Alpine ^[2].

If you prefer npm, install the package globally ^[4]:

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

To upgrade an npm installation, run npm install -g @anthropic-ai/claude-code@latest. Avoid npm update -g, and do not use sudo npm install -g ^[4].

Run claude --version to confirm the installation worked ^[3]. Then start a session from inside your project directory ^[3]:

cd /path/to/your/project
claude

Inside a session, /help shows the commands available, /clear starts a new conversation and /exit leaves Claude Code ^[3]. Type / to see the list, or type / followed by letters to filter it. A command is recognised only at the start of a message, and any text after it becomes its arguments ^[11]. /cost is documented as an alias for /usage, which shows the session cost, plan usage limits and activity statistics. /stats is another alias ^[11].

CLAUDE.md: standing instructions

CLAUDE.md is a Markdown file that gives Claude persistent instructions. Claude reads it at the start of every session ^[5]. It can live in several places, and each one has a different scope ^[5]:

• ~/.claude/CLAUDE.md holds your instructions for all projects.
• ./CLAUDE.md or ./.claude/CLAUDE.md holds instructions for one project.
• ./CLAUDE.local.md holds local personal preferences for one project.

Files in the directory hierarchy above the working directory are loaded at launch. Files in subdirectories are loaded on demand, once Claude reads, writes or edits a file in that subdirectory ^[5]. Keep the project file short and specific. Anything you would repeat in every session belongs there.

Subagents

A subagent is a separate Claude with its own system prompt and tool set. Subagent files live in .claude/agents/ for the current project, and in ~/.claude/agents/ for all your projects ^[6]. A file has YAML frontmatter for its configuration, followed by the system prompt in Markdown. Only name and description are required ^[6].

The documented frontmatter fields include name, description, tools, disallowedTools, model, permissionMode, maxTurns, skills, mcpServers, hooks, memory, background, effort, isolation and color ^[6]. The official minimal example is ^[6]:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

This subagent can only read and search with Read, Glob and Grep, and it runs on the sonnet model. The description tells Claude when to hand work to it. Keep the system prompt focused on one job.

Custom commands and skills now share one mechanism. A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy and work the same way ^[7]. The .claude directory holds single-file prompts in commands/*.md, subagent definitions in agents/*.md, and reusable prompts in skills/<name>/SKILL.md, which are invoked with /name ^[14].

Permission modes

Claude Code supports six permission modes: default, acceptEdits, plan, auto, dontAsk and bypassPermissions ^[9]. The two you will meet first are these:

• In default mode Claude Code asks for permission the first time each tool is used. The alias manual also refers to this mode. In acceptEdits mode it accepts file edits and common filesystem commands such as mkdir, touch, mv and cp automatically ^[9].
• In plan mode Claude reads files and runs read-only shell commands to explore, but it does not edit source files ^[9].

bypassPermissions skips every permission prompt. The docs recommend it only in isolated environments such as containers or VMs ^[9].

Permission rules use three behaviours, allow, ask and deny, which are evaluated in that order. Each rule follows the format Tool or Tool(specifier). The default mode for new sessions is set with defaultMode in a settings file ^[9]. Claude Code reads settings from ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json and managed-settings.json ^[13].

You can switch modes with Shift+Tab in the CLI ^[10]. To start in a particular mode, pass a flag, for example claude --permission-mode plan ^[10].

Hooks

Hooks are user-defined actions that run automatically at set points in Claude Code's lifecycle. A hook can be a shell command, an HTTP endpoint, an MCP tool call, an LLM prompt or a subagent ^[8]. The hook reference groups its events into two lists. The first includes SessionStart, Setup, UserPromptSubmit, PreToolUse, PermissionRequest, PostToolUse, PostToolUseFailure, Notification and MessageDisplay, along with a few others ^[8]. The second includes SubagentStart, SubagentStop, Stop, PreCompact, PostCompact and SessionEnd, among others ^[8]. Check the reference before you write one, because the event names are exact.

A hook is most useful for things that must always happen, such as checking a tool call before it runs. Put the rule in a hook instead of relying on a reminder in CLAUDE.md.

How we use it

TellWorld is maintained with Claude Code working directly in the project repository. The repository holds a Go API, an Astro website and a Node.js content pipeline ^[1]. These are our choices, not general best practice.

We keep two instruction files. A user-level CLAUDE.md holds rules for every project, and a project-level CLAUDE.md holds TellWorld's conventions. Both are loaded at the start of each session ^[1].

Some of our user-level rules are general. For example, we never kill the user's browser process. We ask for confirmation before adding any database table or column. Compiler warnings are removed by rewriting the code, not by suppressing them. Unwanted build artefacts such as source maps are stopped in the build tool's configuration, not deleted after the build ^[1].

The project-level file is about cost. It asks the agent to spend as little quota as possible: poll less, take fewer screenshots, read fewer large files and keep reports short ^[1].

Claude Code also keeps a file-based memory whose index is MEMORY.md. We use it to record a standing choice about which external models not to use for writing and image generation ^[1].

Production access stays behind a human decision. In auto mode, an SSH command from Claude Code to TellWorld's production server was blocked until the maintainer explicitly granted that permission ^[1].

The repeated news update is packaged as a Claude Code skill and started with the slash command /news-update ^[1]. The skill is covered in the companion article on writing an Agent Skill.

Limits and common questions

• Cost depends on the plan. On an API or Console account you pay per token, so watch /cost during long sessions ^[11][12].
• **bypassPermissions is not a shortcut.** It removes the prompts for everything. Use it only in an isolated environment ^[9].
• **Subdirectory CLAUDE.md files load late.** They appear only after Claude touches a file in that folder ^[5].
• A command and a skill with the same name collide. Both create the same slash command, so pick one name for each ^[7].

Next steps

Read the official docs in this order: the overview for surfaces and requirements ^[2], the quick start for the first session ^[3], the memory page for CLAUDE.md ^[5], the subagent page ^[6], the permission pages ^[9][10], the hooks reference ^[8], and the settings page for precedence ^[13].