Claude Code — Anthropic’s agentic coding tool in your terminal
You have installed it and done a first task — now build the habits you will use every day. Learn project instructions (), that many AIs read together, and modes, keeping the tidy and asking well, then finish with practice. The first thing to do is connect the — let open and check the page it changed.
Basics — install it and do your first task
New to it? Start here. Learn what is, install it and follow the first five steps. When you have done them all, move on to the [Intermediate] tab above.
What it is
is an tool made by : you describe a task in plain words, and it reads your files, edits and runs commands, asking for first. It runs in the , and you can also use it in code editors such as and , in the and on the web.
What you need
- An account: a Pro, Max, Team or Enterprise plan, or a Console () account. The free claude.ai plan does not include Claude Code.
- A computer: 13 or later, 10 (1809) or later, 20.04 or 10 or later, at least 4 of , and an internet connection.
- A project folder to work in — ideally a , so every change can be reviewed and undone.
Install
On macOS, and run the first line; on Windows run the line. Installed this way, it updates itself in the background. and WinGet installs do not update by themselves.
- macOS · Linux · WSL
curl -fsSL https://claude.ai/install.sh | bash- Windows PowerShell
irm https://claude.ai/install.ps1 | iex- Homebrew
brew install --cask claude-code- WinGet
winget install Anthropic.ClaudeCode- ( 22+)
npm install -g @anthropic-ai/claude-code
Check the installation
Open a new terminal window. claude --version should print a number, and shows the state of the installation. If you see “”, open the terminal again and check your .
claude --version
claude doctor
First run — five steps
- Open a terminal and go to your work folder: an existing project with
cd <folder>, or a new empty folder with the commands below. Then typeclaudeand press Enter (this starts the command-line tool, not the desktop app). The first time, a opens so you can log in. - Existing project: ask “What is in this project?” so it reads the project. Empty folder: say what you want to make, for example “I want a one-page website that shows today’s date. How should we start?”
- Existing project: run
to create , then add your test command and the to follow. Empty folder: skip this step for now, because/initneeds code to read. Run it once the project has files. - Type
/plan(or press until shows) and ask for a change; in an empty folder, ask for the first files. Before you approve, check which files it will change and which commands it will run. Approve only what belongs to the job you asked for. If anything else is there, correct the plan first. - See what changed with
git status(new files) andgit diff(edited files), check the result yourself, for example by running the tests, then .
Existing project
cd my-project
claude
New project (empty folder)
mkdir my-project && cd my-project
git init
claude
For work on web pages, connect a browser — Claude in Chrome (browser connected)
If your work touches a web page, connect a browser so Claude can check its own changes. With the connected, after Claude changes the code it opens the page in your own , clicks, types and reads the to check the result itself. With no browser tool, it cannot open the page, and all the checking is left to you. If your work has no web page, skip this box: your CLAUDE.md, test command and permissions matter more.
Claude in Chrome is one choice, and it suits sites you are signed in to because it uses your own Chrome. browser tools such as Playwright MCP and Chrome MCP also let Claude open and check pages. They can run with no window (headless), so they also work where the extension does not, such as WSL or an login.
- Install the Claude in Chrome extension (1.0.36 or later) from the Chrome Web Store and sign in with the same claude.ai account as Claude Code. It works in Chrome, and browsers such as and Arc.
- Start Claude Code with
claude --chromein the terminal. The first time, an introduction appears — press Enter. - Open
/chrome, check that it shows Status: Enabled and Extension: Installed, and turn on Enabled by default. After that every connects without--chrome(the and VS Code share this setting). - In the VS Code extension, type
@browserin the box to connect — or, with Enabled by default on, each session is connected from the start.
claude --chrome # start with the browser connected
# inside Claude Code
/chrome # Status: Enabled · Extension: Installed
# → turn on "Enabled by default" once
@browser open localhost:3000 and check the console for errors
It works only when you sign in with /login on a Pro, Max, Team or Enterprise plan — not with an API key or a third-party provider such as , and not in WSL. When Claude meets a login page or a , it pauses and hands it to you.
Features you will use often
-
CLAUDE.md — project instructions read in every session (start with
/init) - Permissions and plan mode — what it may do without asking, and a plan before changes
- — teach repeated work with folders in
- — hand off parts of a task
- — run commands at set moments
- MCP — connect outside tools
-
claude -p "…"— run once without the chat screen, for and -
to start fresh, to stop,claude updateto update right away
Use it safely
- Never approve a command you do not understand. Start strict and loosen only what you trust.
- Trust the output, not the summary — even when it says “tests pass”, run them yourself.
- Many small loops beat one huge request: commit or undo after each one.
Basic practice — try it once from the start
If you get stuck: if claude does not start, check the install with claude doctor; if the sign-in page does not open, close the terminal, open a new one and run claude again. Done all five? Move on to the [Intermediate] tab.
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
- Claude Code — Use Claude Code with Chrome
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.
Intermediate — instruction files, permissions, context
Browser connection — let Claude open and check the page it changed
)For web work, does its best work with the connected. It changes the , opens , follows the flow by clicking and typing, reads the and the , and fixes what is wrong — the whole loop, without you. Checking the real page instead of trusting "the tests pass" is why you should always use the browser connection.
works in (grouped into one tab group per ) and uses your browser's login state. So it can work in admin , Google Docs, Gmail and other you are already signed into, with no connection. Which sites it may click and type on is set by the site of the .
- Live — read the console errors and the DOM state directly, then fix the code that caused them.
- Checking the design — open the page to see that it matches the and does not break on wide and narrow screens.
- a web app — follow user flows such as form checks, sign-in and checkout to the end.
- Working on signed-in sites — change dashboard settings, fill in forms, upload files from your computer, extract from a page and save it to a file.
- Recording — record what it did as a or save as files to attach to a report.
claude --chrome
# inside Claude Code
/chrome # Status: Enabled · Extension: Installed · "Enabled by default"
/mcp # claude-in-chrome → View tools
I changed the login form validation. Open localhost:3000/login,
submit it with an empty email, and check that the error message
appears and the console has no errors. Fix anything that is wrong.
@browser go to localhost:3000 and check the console for errors
If the tools stop working, choose Reconnect extension in /chrome. If the extension and Claude Code are signed in to a different account or organization, you get "Browser extension is not connected" (check the organization with /status). An blocks browser commands — close it yourself and tell Claude to continue. The browser tools are always loaded, so they use a little more , but for web work keeping them on is far better.
Models and effort — which to use (recommended: Opus 5.5, High)
)As of November 2026, use Opus 5.5 at High effort for development. Its default effort is medium, so set it as below or run / opus and /effort high. Every model and , and when to go lower or higher, is in Recommended use on Tool Master.
{
"model": "opus",
"effortLevel": "high"
}
claude --model opus --effort high
# inside Claude Code
/model opus
/effort high
CLAUDE.md — project instructions read every session
)is a file that Claude Code reads every time a session starts. Write down what you are tired of repeating: build and test commands, code , things it must not do. Run 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 ( it to )
- ./CLAUDE.local.md — instructions only you use in this project (add it to )
- CLAUDE.md in a — also read when Claude reads or edits files in that folder. Rule files in .claude/rules/ can apply to certain files only, with
- Note: if a CLAUDE.md, .claude/CLAUDE.md or exists in the working folder or any folder above it, Claude Code does not read . Your personal ~/.claude/CLAUDE.md does not count — see the next section.
# 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 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 , or alongside Claude Code, separate instruction files for each tool soon drift apart. AGENTS.md is an open format that many read. Write the rules once in AGENTS.md and every 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).
- Claude reads a subfolder's AGENTS.md when it opens an existing file in that folder with the Read tool and that folder has no CLAUDE.md of its own. If Claude creates a new file there before reading an existing file, it may not have loaded the folder's instructions yet. A subfolder's CLAUDE.md is loaded when Claude reads, creates or edits files there.
- AGENTS.local.md, and files under a ./ 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 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 , a 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 that pulls a file's contents in at that spot, and the official docs say this import never makes Claude read AGENTS.md twice.
- 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.
- 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).
- Keep your personal instructions for every project in ~/.claude/CLAUDE.md — it is always loaded together with AGENTS.md.
- If a subfolder has its own rules (for example api/), put an AGENTS.md there as well.
- 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. ① 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 (ln -s AGENTS.md CLAUDE.md) also works, but with in the mix the one line @AGENTS.md is safer.
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.
- — switch modes: default (ask every time) → (file edits without asking) → plan ( and show a plan). If you started in , the first press switches to default.
- /permissions — see and edit the allow, ask and deny rules and which file each one comes from.
- 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 files such as with deny.
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test *)",
"Bash(git diff *)"
],
"deny": [
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
}
}
(--dangerously-skip-permissions) turns every check off. Use it only where damage does not matter, such as a or with no internet access.
Managing context — when the conversation gets long
)How much Claude can see at once (the ) 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 fix).
- — start a new conversation with empty context when you begin unrelated work. The earlier conversation is not deleted: brings it back.
- claude -c continues the last conversation in this folder, and claude -r or /resume lets you pick an earlier one to continue.
- twice (or /rewind) — pick an earlier point from the list and the conversation and code. Files deleted or moved with 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.
Save context — set Claude Code to auto compact at 444k (SONUB setting)
)Asking well — where, what and how to check
)- Vague request: "Fix the login"
- Clear request: "In @app//Controllers/LoginController.php a wrong password gives a 500 error. Make it return 422 with an , 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, enter first with /plan (or Shift+Tab). Claude looks through the code and writes a plan, and edits no files until you approve it.
- For a hard problem, raise the model and effort level in /model, or put in your request so it thinks harder on that only.
- <> — Claude keeps taking turns without a new request until the finish line is met (e.g. /goal all tests in tests/ pass, or stop after 20 turns). /goal alone shows the status; /goal clear removes it.
Best practices — how Anthropic recommends using Claude Code
)In short: give Claude a way to check its work, plan hard work first, be specific, keep CLAUDE.md short, and use /clear when you switch to a new, unrelated task — keep the current context for related follow-up work. The six good habits from both official guides, with commands for Claude Code and Codex, are in Recommended use.
Common mistakes — and how to fix them
)The official guide warns about five failure patterns — the kitchen-sink session, correcting over and over, an over-long CLAUDE.md, trusting without checking and endless exploration. All ten mistakes from both guides, each with its fix, are in Recommended use.
Intermediate practice — try it in your own project
)- Create an AGENTS.md file in your project's root with the test command and three rules, and check that there is no CLAUDE.md in the project.
- Open /memory and check that AGENTS.md and ~/.claude/CLAUDE.md were loaded.
- In .claude/settings.json allow one test command and deny .env, then check with /permissions.
- Ask for one small feature in plan mode, read and adjust the plan, then approve it.
- Look at how much is used with /context, shrink it with /compact and look again.
Done all five? Finally, use /clear if you are ready to move on to a new, unrelated task — then go to the [Advanced] tab.
Official documentation
- Use Claude Code with Chrome
- Memory — CLAUDE.md · AGENTS.md
- Permissions
- Settings
- Checkpointing
- Model configuration — auto-compact window
- Best practices
- Best practices — common failure patterns
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.
Advanced — skills, subagents, hooks, MCP, headless
Agent skills — teach it jobs you repeat
)A is a folder with a in it. Normally 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>. Before you make a new skill, run /skills to see the names already in use: if the new skill has the same name as one in another place, only one of them runs as /<name> (the name are in the next two sections).
- Keep 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.
Skills are an open standard — but Claude Code works its own way
)were first made by , the company behind Claude, and released for free. Today they are an called , managed at agentskills.io. , , , and many other 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 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 (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 , and a child folder only when it works there (next section).
- : the standard has six fields — name, description, , compatibility, and . Claude Code adds more, such as disable-model-invocation, : fork and . Other tools ignore them, and claude.ai uploads and the Skills 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
)Claude Code reads .claude/skills/ in the folder where you start claude and in every up to the git repository root, and uses them all together — start in apps/web/ and the root skills are there too (in a it goes up only to the worktree root). A .claude/skills/ above the repository root is not read, so put skills for all your projects in ~/.claude/skills/.
- 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 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 , both stay available: /deploy runs the root one and /apps/web:deploy runs the one in apps/web/. Claude Code also lists both for Claude with an instruction to use the one whose folder holds the files it is working on, so the apps/web/ skill still applies to work there (official docs: Skills — skills that share a name).
- 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 is a helper with its own , instructions and tools. Hand it a side job that would otherwise fill your conversation with search results, or file contents you will not need again — a big search, a , a test run. However many files it reads, only its summary comes back, so the main conversation stays short and focused on your task. It also gives you control: a subagent can be limited to certain tools (a reviewer that only reads), run on a faster, cheaper and follow the same instructions every time. Make one when you keep asking for the same kind of helper.
- .claude/agents/<name>.md is for the project ( 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.
- There are two ways it starts. ① You ask in your : name it ("Review this change with the code-reviewer subagent"), or type @ and pick it to make sure that one runs. ② Claude hands work to it on its own: it compares your request with the description in the subagent's file, so write there what it does and when to use it — adding "use proactively" makes Claude delegate more readily.
- 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
)is a request, so it can sometimes be forgotten, but a is a command Claude Code always runs at a set moment. Use hooks to run a after a file edit, block dangerous commands or edits to files, and get a notification when work is done.
- — before a tool is used (can block it), — after a tool is used
- — when you send a request, Stop — when Claude finishes its answer, SessionStart — when a session starts, Notification — when it needs your attention
- chooses which the hook applies to (for example Edit|Write, ).
- What 2 does depends on the event. On PreToolUse the action is blocked and the reason written to is passed to Claude. On PostToolUse the tool has already run, so Claude only gets that reason as feedback.
- /hooks shows the hooks in place. The example below runs on every file Claude edits or writes: reads the file path from the hook input and npx prettier --write formats that file, so it needs jq and ().
{
"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 . Add a hook from someone else only after you have read and understood its command.
MCP — connect outside tools
)is an open standard that lets AI tools use outside services (issue trackers, , , document tools). Add an and Claude can use the tools that provides.
- claude mcp add --transport http <name> <> — add a remote server on the internet.
- <name> -- <command> — add a server that runs on your computer (stdio). Everything goes to the server unchanged.
- Added with --scope project, it is saved in at the top of the and shared with the team (approval is asked on first use).
- /mcp shows the connection status and signs in (). 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
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, and .
- Pass input through a pipe (cat error.log | claude -p "…").
- 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 .
- claude -p --continue continues the previous run, or <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, 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
)- Turn one job you do often (, commit messages) into a skill in .claude/skills/ and call it with /skill-name.
- Make a code-reviewer subagent and have it review your current change.
- Use a PostToolUse hook so a formatter or runs on every file edit.
- Add one MCP server and check the connection with /mcp.
- Write a one-line shell script that summarizes an with claude -p.
Done all five? Move on to the [Master] tab.
Official documentation
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.
Master — parallel work, GitHub, plugins, long tasks
Git worktrees — several sessions at once
)When two edit the same files in one folder, they overwrite each other. checks out the same into another folder on another , so you can run one 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 , and list files ignores, such as , in .worktreeinclude to copy them into new worktrees.
- Each worktree may need its own dependency install ( install and so on).
- Split work into independent jobs that touch different files, and merge them through 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 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 's , so your computer can be off.
- Run /install-github-app in Claude Code in the terminal. It guides you through installing the GitHub app and adding the (ANTHROPIC_API_KEY or a made with claude ) — it needs and admin rights on the repository.
- A like the one above appears in .github/workflows/.
- Comment on an issue or PR, for example "@claude fix this ".
- 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 (, or ). The easiest way to make it follow your is a well-written instruction file.
Plugins and marketplaces — bundle and share a setup
)A bundles , , and into one. A 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, 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
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 (): AGENTS.md, , , , (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 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 (deny) and hooks, not with instructions.
- Push company-wide rules down through — 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, , a build — it can work for a long time without anyone watching.
- Give the definition of done as commands — "until npm test and 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 is summarized or the session changes.
- Have it commit after each complete, working step that can stand on its own, so you can that step independently. Do not split one unfinished change across several commits that must be undone together.
- If three attempts to solve the same problem fail, have Claude stop and write down what it tried, why those attempts failed and what is blocking progress, before it tries again. This stops loops that go nowhere.
- When it is all done, hand a to another (for example codex review) or a subagent.
Master practice — several sessions and automation
)- Make a second working folder with git worktree add ../my-project-b -b try-b, run claude in each folder and give each a different small job. If git status changes separately in the two folders, it worked.
- Make a one-line review command: git | claude -p "List bugs in this diff". Put in a bug on purpose and check that it finds it.
- Write one team rule (for example, run the tests before committing) in AGENTS.md and also enforce it with a hook. Break the rule on purpose and check that the hook stops it.
- Bundle one of your skills and one subagent into a plugin as in the plugins section above, install it, and check that it loads in another project too.
- Give a long task with a written as a command (for example, npm test passes). When it says it is done, check the diff and the test result yourself.
If you get stuck: list worktrees with git worktree list and remove one with git worktree remove. If a hook blocks too much, take it out of settings.json for a moment and check with /hooks. Done all five? Check yourself with the checklist below.
Master checklist — the whole path from Basics to Master
)- Basics — you run claude in a Git project folder, plan first with /plan, approve only what belongs to the job and check git status and git diff before you commit
- Intermediate — for web work the connection is on, so Claude opens and checks the page it changed
-
Intermediate — only AGENTS.md in the project, so every AI works from the same instructions. If you use CLAUDE.md, every folder that has an AGENTS.md also has a CLAUDE.md that references it with the line
@AGENTS.mdon its own - Intermediate — let safe commands run without asking and block secret files with deny
- Intermediate — you watch the context with /context, shrink it with /compact and use when you switch to a new, unrelated task; each request says where, what and how to check
- Advanced — repeated jobs go to skills (check the names in use with /skills first), big searches and reviews to subagents
- Advanced — what must be followed is enforced with hooks and permissions, outside come in through MCP servers you trust, and one-off jobs run in with claude -p
- Master — runs in worktrees, and @claude in GitHub Actions takes on issues and PRs
- Master — the team's skills, subagents, hooks and MCP servers are shared as one plugin, and shared and personal settings are kept apart
- Master — you give the definition of done as commands, commit each complete working step 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 ().
Official documentation
Checked against the official documentation on 2026-10-19. These tools change often — if a command fails, see the official docs.