Claude Code — Anthropic’s coding agent in your terminal

What it is

Claude Code is a coding agent made by Anthropic. It runs in the terminal, and you can also use it in code editors such as VS Code and JetBrains, in the Claude desktop app and on the web.

It can show a plan before it changes anything, and it asks before editing files or running commands — you decide what it may do (permissions). Rules for your project go in CLAUDE.md, which it reads at the start of every session.

What you need

• An account: a Claude Pro, Max, Team or Enterprise plan, or a Console (API) account. The free claude.ai plan does not include Claude Code.
• A computer: macOS 13 or later, Windows 10 (1809) or later, Ubuntu 20.04 or Debian 10 or later, at least 4 GB of memory, and an internet connection.
• A project folder to work in — ideally a Git repository, so every change can be reviewed and undone.

Install

On macOS, Linux and WSL run the first line; on Windows run the PowerShell line. Installed this way, it updates itself in the background. Homebrew and WinGet installs do not update by themselves.

macOS · Linux · WSL

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

Windows PowerShell

irm https://claude.ai/install.ps1 | iex Copy

Homebrew

brew install --cask claude-code Copy

WinGet

winget install Anthropic.ClaudeCode Copy

npm (Node.js 22+)

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

Check the installation

Open a new terminal window. claude --version should print a version number, and claude doctor shows the state of the installation. If you see “command not found”, open the terminal again and check your PATH.

First run — five steps

1. Go to your project folder and run claude. The first time, a browser opens so you can log in.
2. Ask “What is in this project?” so it reads the project.
3. Run /init to create CLAUDE.md, then add your test command and the rules to follow.
4. Press Shift+Tab to switch to plan mode and ask for a change. Read the plan, fix it, then approve it.
5. Read what changed with git diff, run the tests yourself, then commit.

Learn more on SONUB

• Claude Code 1: set up a project and give lasting instructions
• Claude Code 2: plan, change, test, review
• Agents and sub-agents: how an AI works step by step
• Goal and Ralph Loop: let an agent keep going until it is really done
• The claude-skill agent skill — learn Claude Code step by step and keep up with new features

Official documentation

• Claude Code — Overview
• Claude Code — Advanced setup
• Claude Code — Quickstart
• Claude Code — Common workflows

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

CLAUDE.md — project instructions read every session

CLAUDE.md is a Markdown file that Claude Code reads every time a session starts. Write down what you are tired of repeating: build and test commands, code rules, things it must not do. Run /init and it reads the project and writes a first CLAUDE.md. CLAUDE.md files in several places do not override each other — they are all read together.

• ~/.claude/CLAUDE.md — your personal instructions for every project
• ./CLAUDE.md or ./.claude/CLAUDE.md — project instructions the team shares (commit it to Git)
• ./CLAUDE.local.md — instructions only you use in this project (add it to .gitignore). But if even one exists, AGENTS.md is not read
• CLAUDE.md in a subfolder — also read when Claude reads or edits files in that folder. Rule files in .claude/rules/ can apply to certain files only, with paths

# My App

## Commands
- Install: npm install
- Test: npm test
- Lint: npm run lint

## Rules
- TypeScript strict mode. Do not use `any`.
- Put new API routes in src/routes/.
- Never edit files in vendor/.
- Run the tests before you say a task is done.

@docs/architecture.md

Keep it short (the official docs suggest under 200 lines). It is read every time, so a long file takes up room and buries the important rules. /memory shows the instruction files that were loaded and opens them for editing, and @path (like @docs/architecture.md) pulls in another file. If you use several AIs together, it is best to keep only AGENTS.md in the project instead of CLAUDE.md — see the section right below.

Use only AGENTS.md — so every AI works from the same instructions

Why do this? If one project uses other AIs such as Codex, Cursor or Gemini alongside Claude Code, separate instruction files for each tool soon drift apart. AGENTS.md is an open format that many coding agents read. Write the rules once in AGENTS.md and every AI follows the same instructions, whichever one you work with. The method below exists for exactly this — so that in one project, many AIs all use the same instructions through AGENTS.md.

Claude Code can read AGENTS.md directly too (v2.1.277 or later), but not quite like CLAUDE.md.

• With the default setting it reads AGENTS.md only when there is no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md in the working folder or any folder above it. Adding just one CLAUDE.local.md for personal notes stops AGENTS.md from being read (~/.claude/CLAUDE.md and .claude/rules/ do not count here).
• An AGENTS.md in a subfolder is read only when Claude opens a file there with the Read tool. When it writes a new file straight into that folder, it may not know the rules yet. A subfolder CLAUDE.md is read on reads, writes and edits.
• AGENTS.local.md, AGENTS.override.md and files under a .agents/ folder are not read, and neither is the AGENTS.md of a folder added with --add-dir.

The best way is not to use CLAUDE.md in the project folder at all and use only AGENTS.md. Your global instructions in ~/.claude/CLAUDE.md are still loaded by default, and in the project folder AGENTS.md is used. Other AIs such as Codex read the same AGENTS.md, so you edit the rules in one place only — AGENTS.md.

But if you use CLAUDE.md in even one place — the project folder, the current folder, a parent folder or a subfolder — you must use CLAUDE.md in every folder. If there is even one CLAUDE.md in the working folder or above it, Claude Code does not read AGENTS.md, so mixing them means some folders' rules are read and others are left out. If you still want to use AGENTS.md in that case, just add one line, @AGENTS.md, to each CLAUDE.md. @path is the syntax that pulls a file's contents in at that spot, and the official docs say this import never makes Claude read AGENTS.md twice.

1. Write the shared rules (install and test commands, code rules, things not to do) in AGENTS.md at the top of the project. You can also create it with Codex's /init.
2. Do not create CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md anywhere in the project (not in the current folder, parent folders or subfolders).
3. Keep your personal instructions for every project in ~/.claude/CLAUDE.md — it is always loaded together with AGENTS.md.
4. If a subfolder has its own rules (for example api/), put an AGENTS.md there as well.
5. Open /memory in Claude Code and check that AGENTS.md was loaded. If you decided to use CLAUDE.md, also check that every folder's CLAUDE.md has the one line @AGENTS.md.

~/.claude/CLAUDE.md    ← your personal rules (still loaded by default)

my-project/
├── AGENTS.md          ← shared rules for every AI (Claude Code, Codex, Cursor, Gemini …)
└── api/
    └── AGENTS.md      ← rules only for api/

(no CLAUDE.md anywhere in the project)

my-project/
├── AGENTS.md
├── CLAUDE.md          ← @AGENTS.md
└── api/
    ├── AGENTS.md
    └── CLAUDE.md      ← @AGENTS.md

@AGENTS.md

Good to know, and other ways. ① With AGENTS.md only, a subfolder's AGENTS.md is read when Claude opens a file there with Read. ② Set Project instructions in /config to claude-md-and-agents-md and each folder's AGENTS.md is read right after its CLAUDE.md. ③ A symbolic link (ln -s AGENTS.md CLAUDE.md) also works, but with Windows in the mix the one line @AGENTS.md is safer.

• The order in which Codex reads AGENTS.md — Codex Intermediate

Permissions and modes — decide what it may do without asking

Claude Code asks before it edits a file or runs a command. If approving the same thing every time gets tiresome, turn it into a rule, and switch modes to suit the job.

• Shift+Tab — switch modes: default (ask every time) → acceptEdits (file edits without asking) → plan (read only and show a plan). If you started in auto mode, the first press switches to default.
• /permissions — see and edit the allow, ask and deny rules and which file each one comes from.
• .claude/settings.json holds rules the team shares (commit it), .claude/settings.local.json holds rules only you use, and ~/.claude/settings.json holds rules for all your projects.
• Rules are checked in the order deny → ask → allow. Anything denied anywhere cannot be allowed elsewhere, so block secret files such as .env with deny.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

bypassPermissions (--dangerously-skip-permissions) turns every check off. Use it only where damage does not matter, such as a container or virtual machine with no internet access.

Managing context — when the conversation gets long

How much Claude can see at once (the context window) is fixed. The conversation, the files it read and command output all pile up there, and when it is full the earlier part gets summarized. The longer it grows, the fainter earlier instructions become, so make tidying up a habit.

• /context — see, as coloured blocks, what is taking up the context and how much.
• /compact — summarize the conversation so far to free up room. You can say what to keep (for example /compact focus on the login bug fix).
• /clear — start a fresh conversation when you begin unrelated work.
• claude -c continues the last conversation in this folder, and claude -r or /resume lets you pick an earlier one to continue.
• Esc twice (or /rewind) — pick an earlier point from the checkpoint list and roll back the conversation and code. Files deleted or moved with Bash are not restored, so it does not replace Git commits.

One job per conversation. When the job changes, starting fresh with /clear is the easiest way to tidy up.

Asking well — where, what and how to check

A good request has three parts: where (files and folders), what (the behaviour you want) and how to check it (tests, commands, screens). The clearer the three are, the less Claude wanders and the more it checks its own results.

• Vague request: "Fix the login"
• Clear request: "In @app/Http/Controllers/LoginController.php a wrong password gives a 500 error. Make it return 422 with an error message, add a test to tests/Feature/LoginTest.php and check that it passes."

• Type @ to pick a file and attach it to your request (@src/login.ts).
• For error screens and design mock-ups, paste or drag in a screenshot.
• For a big job, start with "Read first and show me only a plan — do not change anything yet", or enter plan mode with /plan.
• For a hard problem, raise the model and effort level in /model, or put ultrathink in your request so it thinks harder on that turn only.

Intermediate practice — try it in your own project

1. Create AGENTS.md at the top of your project with the test command and three rules, and check that there is no CLAUDE.md in the project.
2. Open /memory and check that AGENTS.md and ~/.claude/CLAUDE.md were loaded.
3. In .claude/settings.json allow one test command and deny .env, then check with /permissions.
4. Ask for one small feature in plan mode, read and adjust the plan, then approve it.
5. Look at how much is used with /context, shrink it with /compact and look again.

Done all five? Move on to the [Advanced] tab.

Official documentation

• Memory — CLAUDE.md · AGENTS.md
• Permissions
• Settings
• Checkpointing

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

Agent skills — teach it jobs you repeat

A skill is a folder with a SKILL.md in it. Normally Claude knows only each skill's name and description; when a job matches the description, it reads the body and follows it. So many skills take up almost no room. The old custom commands (.claude/commands/) have now been merged into skills.

• .claude/skills/<name>/SKILL.md is for this project, ~/.claude/skills/<name>/SKILL.md for all your projects.
• Say clearly in description what it does and when to use it, so Claude picks it on its own.
• You can also call it directly with /<skill name>, and /skills shows the list.
• Keep scripts and reference documents in the same folder and point to them from SKILL.md. Keep SKILL.md short, under 500 lines.

---
name: release-notes
description: Write release notes from the git log. Use when the user asks for release notes, a changelog or "what changed since the last tag".
---

# Release notes

1. Find the last tag: `git describe --tags --abbrev=0`
2. Read the commits since then: `git log <tag>..HEAD --oneline`
3. Group them under Added / Fixed / Changed.
4. Write plain sentences a user can understand. Skip internal refactors.

• Learn about agent skills — make, install, SONUB skills

Skills are an open standard — but Claude Code works its own way

Skills were first made by Anthropic, the company behind Claude, and released for free. Today they are an open standard called Agent Skills, managed at agentskills.io. Codex, Cursor, Gemini CLI, GitHub Copilot and many other AI tools read the same SKILL.md folder.

Be careful, though: the standard only defines what goes inside a skill folder. Where to look for skills and which one wins when names clash are left to each tool, and Claude Code works differently from what agentskills.io recommends. So a skill that works in another tool can behave differently in Claude Code.

• Folder: agentskills.io recommends .agents/skills/, which many tools share, but Claude Code reads .claude/skills/ (in the project) and ~/.claude/skills/ (personal). It does not read .agents/skills/.
• Same name: the common rule in the standard is that a project skill beats a personal one. In Claude Code it is the other way round — enterprise beats personal, and personal (~/.claude/skills/) beats project.
• Parent and child folders: the standard does not say. Claude Code reads the folder you start in and every parent up to the git repository root, and a child folder only when it works there (next section).
• Frontmatter: the standard has six fields — name, description, license, compatibility, metadata and allowed-tools. Claude Code adds more, such as disable-model-invocation, context: fork and paths. Other tools ignore them, and claude.ai uploads and the Skills API stop with an error.

For a skill you share with other AI tools, write the frontmatter with only the six standard fields. Then it loads unchanged in Claude Code and in the other tools.

Where Claude Code finds skills — your folder and its parents together

If the folder you are in has a .claude/skills folder and a parent folder has one too, Claude Code uses the skills in both together. It only goes up as far as the git repository root.

• It reads .claude/skills/ in the folder where you start claude and in every parent folder up to the repository root. Start in apps/web/ and the root skills are there too.
• A .claude/skills/ above the repository root is not read. Put skills for all your projects in ~/.claude/skills/. In a git worktree it goes up only to the worktree root.
• Skills in a folder below where you started are not read at first. They load the first time Claude reads or edits a file in that folder and stay until the session ends — until then they are not in the / menu. To load them early, run /add-dir with that folder.
• If the root and apps/web/ both have a skill named deploy, both can be used: /deploy runs the root one and /apps/web:deploy runs the one in the child folder. Claude is told to use the skill of the folder that holds the files it is working on.
• Plugin skills are separate, called as /<plugin-name>:<skill-name>, so they never clash with yours.

~/projects/                    ← above the repository root
├── .claude/skills/            ← not loaded (put shared skills in ~/.claude/skills/)
└── repo/                      ← git repository root
    ├── .claude/skills/        ← loaded
    └── apps/web/              ← run claude here
        ├── .claude/skills/    ← loaded (used together with the root)
        └── src/
            └── .claude/skills/  ← not at start — loads when Claude first reads or edits a file in src/

repo/
├── .claude/skills/deploy/SKILL.md            → /deploy
└── apps/web/.claude/skills/deploy/SKILL.md   → /apps/web:deploy

Run /skills to see which skills are loaded now. With many skills in parent and child folders, the descriptions of the least-used ones get cut first, so check now and then with /skill-doctor.

Subagents — hand off parts of the work

A subagent is a helper with its own context window, instructions and tools. Give it a big search or review: however many files it reads, only the result comes back to the main conversation, which stays clean.

• .claude/agents/<name>.md is for the project (commit it to share with the team), ~/.claude/agents/ is just for you. Only name and description are required.
• Limiting the tools it may use with tools is safer — let a reviewer only read.
• Call it like "Review this change with the code-reviewer subagent", or Claude hands work to it on its own when the description fits.
• To make a new subagent, ask Claude to create one or write the file in the folder above yourself. Built-in ones such as Explore and Plan are there from the start.

---
name: code-reviewer
description: Reviews code changes for bugs, security problems and missing tests. Use after writing or changing code.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a careful senior reviewer.
Run `git diff` to see the changes, then report:
1. Bugs (with file and line)
2. Security problems
3. Missing tests
Do not edit files.

Hooks — commands that always run at set moments

CLAUDE.md is a request, so it can sometimes be forgotten, but a hook is a shell command Claude Code always runs at a set moment. Use hooks to run a formatter after a file edit, block dangerous commands or edits to secret files, and get a notification when work is done.

• PreToolUse — before a tool is used (can block it), PostToolUse — after a tool is used
• UserPromptSubmit — when you send a request, Stop — when Claude finishes its answer, SessionStart — when a session starts, Notification — when it needs your attention
• matcher chooses which tools the hook applies to (for example Edit|Write, Bash).
• If the hook command ends with exit code 2, the action is blocked and the reason written to stderr is passed to Claude.
• /hooks shows the hooks in place. The example above tidies every edited file with Prettier (it needs jq).

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Hooks run on your computer with your permissions. Add a hook from someone else only after you have read and understood its command.

MCP — connect outside tools

MCP (Model Context Protocol) is an open standard that lets AI tools use outside services (issue trackers, databases, browsers, document tools). Add an MCP server and Claude can use the tools that server provides.

• claude mcp add --transport http <name> <url> — add a remote server on the internet.
• claude mcp add <name> -- <command> — add a server that runs on your computer (stdio). Everything after -- goes to the server unchanged.
• Added with --scope project, it is saved in .mcp.json at the top of the repository and shared with the team (approval is asked on first use).
• /mcp shows the connection status and signs in (OAuth). claude mcp list shows the list.

# A remote server (HTTP)
claude mcp add --transport http notion https://mcp.notion.com/mcp

# A server that runs on your computer (stdio)
claude mcp add playwright -- npx @playwright/mcp@latest

# Share it with the team — saved in .mcp.json
claude mcp add --scope project playwright -- npx @playwright/mcp@latest

claude mcp list

Add only MCP servers you trust. A server that fetches outside text can bring in instructions hidden in that text (prompt injection).

Headless — scripts without the chat screen

claude -p "…" runs once without the chat screen, prints the result and exits. Use Claude as a building block in shell scripts, cron and CI.

• Pass input through a pipe (cat error.log | claude -p "…").
• --output-format json gives the result, session id and cost as JSON; stream-json sends progress line by line.
• --allowedTools sets the tools allowed for this run, and --max-turns the maximum number of turns.
• claude -p --continue continues the previous run, or --resume <session id> continues that session.

# One question, one answer
claude -p "Explain what src/auth.ts does in 5 lines"

# Pipe input in
cat build-error.log | claude -p "Find the cause and suggest a fix"

# JSON output for scripts (result, session_id, total_cost_usd)
claude -p "List the TODO comments in src/" --output-format json

# Limit what it may do and how long it runs
claude -p "Run the tests and fix failures" \
  --allowedTools "Read,Edit,Bash(npm test *)" --max-turns 10

In scripts, --bare starts fast without reading CLAUDE.md, hooks, plugins or MCP (the official docs say it will become the default for -p). Leave it out if you need the project instructions.

Advanced practice

1. Turn one job you do often (release notes, commit messages) into a skill in .claude/skills/ and call it with /skill-name.
2. Make a read-only code-reviewer subagent and have it review your current change.
3. Use a PostToolUse hook so a formatter or linter runs on every file edit.
4. Add one MCP server and check the connection with /mcp.
5. Write a one-line shell script that summarizes an error log with claude -p.

Done all five? Move on to the [Master] tab.

Official documentation

• Skills
• Subagents
• Hooks
• MCP
• Headless (-p)

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.

Git worktrees — several sessions at once

When two sessions edit the same files in one folder, they overwrite each other. git worktree checks out the same repository into another folder on another branch, so you can run one Claude per folder and move several jobs forward at the same time.

• claude --worktree <name> (-w) creates a worktree and branch in .claude/worktrees/<name>/ and starts there. If you finish with no changes, it is removed automatically.
• Add .claude/worktrees/ to .gitignore, and list files Git ignores, such as .env, in .worktreeinclude to copy them into new worktrees.
• Each worktree may need its own dependency install (npm install and so on).
• Split work into independent jobs that touch different files, and merge them through PRs when done.

# Claude Code makes the worktree for you (.claude/worktrees/<name>/)
claude --worktree feature-login
claude -w bugfix-cart

# Or with plain git
git worktree add ../myapp-search -b feature-search
cd ../myapp-search && claude

git worktree list
git worktree remove ../myapp-search

GitHub Actions — @claude in issues and PRs

Install Claude Code GitHub Actions and just writing @claude in an issue or PR comment makes Claude read the repository, fix things and open a PR or leave a review. It runs on GitHub's runners, so your computer can be off.

1. Run /install-github-app in Claude Code in the terminal. It guides you through installing the GitHub app and adding the secret (ANTHROPIC_API_KEY or a token made with claude setup-token) — it needs gh and admin rights on the repository.
2. A workflow file like the one above appears in .github/workflows/.
3. Comment on an issue or PR, for example "@claude fix this bug".
4. A person reviews and tests the PR Claude opened before merging it.

name: Claude
on:
  issue_comment:
    types: [created]
  pull_request_review_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
      issues: write
      id-token: write
    steps:
      - uses: actions/checkout@v4
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

Claude in Actions also reads the repository's instruction file (AGENTS.md, or CLAUDE.md). The easiest way to make it follow your rules is a well-written instruction file.

Plugins and marketplaces — bundle and share a setup

A plugin bundles skills, subagents, hooks and MCP servers into one. A marketplace is a repository with a list of plugins. A team installs the same toolbox with one command and updates it together.

• /plugin — find, install, turn on and turn off plugins.
• Add a marketplace with /plugin marketplace add <owner/repo> and install with /plugin install <plugin>@<marketplace>.
• Only plugin.json goes in the plugin folder's .claude-plugin/. skills/, agents/ and hooks/ sit at the top of the folder. Test it with claude --plugin-dir ./my-plugin.
• If you only share skills, npx skills add works too — that is how SONUB skills are shared.

my-plugin/
├── .claude-plugin/
│   └── plugin.json        ← name, description, version
├── skills/
│   └── release-notes/SKILL.md
├── agents/
│   └── code-reviewer.md
├── hooks/
│   └── hooks.json
└── .mcp.json

/plugin marketplace add my-team/claude-plugins
/plugin install my-plugin@claude-plugins
/plugin

• Install SONUB agent skills

Running a team setup — so rules stay clear as they pile up

When many people and many AIs work in one repository, settings pile up fast. Decide what is shared and what is personal, and what is a request and what is enforced.

• Shared (commit): AGENTS.md, .claude/settings.json, .claude/skills/, .claude/agents/, .mcp.json (and every folder's CLAUDE.md if you use CLAUDE.md)
• Personal (do not commit): .claude/settings.local.json, ~/.claude/ — keep personal instructions in ~/.claude/CLAUDE.md (do not put a CLAUDE.local.md in the project, because it stops AGENTS.md)
• Keep instruction files short. Add a rule only when the same mistake repeats, and delete rules that are wrong or no longer useful.
• Enforce what must be followed with permissions (deny) and hooks, not with instructions.
• Push company-wide rules down through managed settings — other settings cannot override them.

Long tasks — check its own work until it is done

A master gives Claude a "definition of done" and has it check that definition itself. With a test a machine can judge — tests, lint, a build — it can work for a long time without anyone watching.

• Give the definition of done as commands — "until npm test and npm run lint both pass".
• Have it write what is done and what is left in a file such as PROGRESS.md, so it can carry on even after the context is summarized or the session changes.
• Have it commit after each small step, so you can roll back at any time.
• Have it stop and write down why after three failed tries, to prevent loops that go nowhere.
• When it is all done, hand a cross-review to another AI (for example codex review) or a subagent.

• Goal and Ralph Loop: let an agent keep going until it is really done
• VPS and tmux: keep an agent working 24 hours a day

Master checklist

• Only AGENTS.md in the project — every AI works from the same instructions (if you use CLAUDE.md, put one in every folder with the one line @AGENTS.md)
• Permission rules let safe commands run without asking and block secret files with deny
• Repeated jobs go to skills, big searches and reviews to subagents
• What must be followed is enforced with hooks
• Parallel work runs in worktrees; repeated work is automated with claude -p and GitHub Actions
• You give the definition of done as commands and check the result yourself with the diff and tests

The tools change often. Keep up with new features through /claude-skill update in the claude-skill skill or the official change log (CHANGELOG).

Official documentation

• Worktrees
• GitHub Actions
• Plugins
• Settings

Checked against the official documentation on 2026-10-18. These tools change often — if a command fails, see the official docs.