Guidechecked
Setting up Claude Code
From installation to working with CLAUDE.md, skills and hooks. This is how I use Claude Code every day.
What Claude Code is
Claude Code is an AI assistant for the terminal. It reads your project, edits files and runs commands, but only as far as you allow. The difference from a chat window: Claude sees the real code and can run the tests itself. This guide takes you from installation to a setup you can work with every day.
Requirements
You need a terminal (Bash, Zsh, PowerShell or CMD) and a recent system: macOS 13 or later, Windows 10 1809 or later, Ubuntu 20.04 or Debian 10. You also need an account with access to Claude Code. The free Claude plan is not enough.
- Subscription: Claude Pro or Max (also Team and Enterprise). You pay a fixed monthly fee with usage limits.
- Or a Claude Console account with API billing. Here you pay for what you use.
Installation
The native installer is recommended. It needs no Node.js and keeps Claude Code updated automatically in the background. Installing with npm still works, but requires Node.js 22 or later and must not be run with sudo. Afterwards, run claude --version to check that it worked.
# macOS, Linux, WSL
curl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShell
irm https://claude.ai/install.ps1 | iex
# Alternative via npm (Node.js 22+)
npm install -g @anthropic-ai/claude-code@latest
# Check and update manually
claude --version
claude doctor
claude updateTip:If the terminal says “command not found” after installing, open a new terminal window. If that does not help, claude doctor shows what is missing.
Sign in and first start
Always start Claude Code in the folder of the project you want to work on. Claude then sees exactly that folder and loads the matching settings. On first start, a browser window opens for sign-in. With a subscription you sign in with your Claude account, with the Console through your Console account.
- Type claude in the project folder and follow the sign-in in the browser.
- Use /status to check which account and which model are active.
- Sign out with /logout, sign in again with /login.
cd my-project
claudeCaution:If the ANTHROPIC_API_KEY environment variable is set and you approve it, Claude Code uses that key instead of your subscription. You are then billed per use. /status shows what is currently active.
Basic controls
You write tasks in plain language. Slash commands control the session itself. Type @ and a file name to point Claude to a specific file, so it does not have to search first. Esc interrupts Claude mid-task; the work done so far is kept. Shift + Tab switches the mode: Manual (asks before every change), acceptEdits (accepts file edits without asking) and Plan (reads and plans but changes nothing).
/help help and all commands
/init create a first CLAUDE.md
/clear new conversation with empty context
/compact summarise the conversation, free up context
/context show how full the context is
/model switch model
/permissions manage permission rules
/rewind go back to an earlier state
/usage show usage and limits
@src/app.ts mention a specific file
Esc interrupt Claude
Esc Esc (with empty input) open the rewind menuTip:Only approve a plan once it is right. If something should work differently, just say so and Claude adjusts the plan.
Permissions
Claude may read inside the project folder without asking. For shell commands and file edits it asks by default. So you do not have to confirm every npm command, you define rules: allow permits without asking, deny forbids. Shared rules go into .claude/settings.json and are committed to the repo, personal ones into .claude/settings.local.json, rules for all projects into ~/.claude/settings.json.
{
"permissions": {
"allow": ["Bash(npm run *)", "Bash(git commit *)"],
"deny": ["Bash(git push *)", "Read(./.env)", "Read(./secrets/**)"]
}
}Caution:A deny rule only checks the command text. git -C . push, for example, would not match Bash(git push *). So it is not a security boundary. Use bypassPermissions mode, which turns off all prompts, only in an isolated environment such as a container.
CLAUDE.md: rules for your project
Claude reads CLAUDE.md every time it starts. It describes the project, the available commands and the rules that apply. /init creates a first draft that you then refine. Keep the file short, under 200 lines. The more concise and specific it is, the more reliably Claude follows it.
- Type /init in the project and read the generated CLAUDE.md.
- Add hard rules, for example what must never go into the repo or how tests are run.
- Personal preferences go into ~/.claude/CLAUDE.md, which applies to all projects. Private notes for this project only go into CLAUDE.local.md, which you add to .gitignore.
# Project
Next.js with strict TypeScript. Details in @README.md
## Commands
- npm run dev: development server
- npm run test: tests, before every commit
## Rules
- No secrets in code, only via environment variables
- Small commits following Conventional CommitsTip:CLAUDE.md is context, not a lock. For anything that must never happen, add a deny rule or a hook as well.
Skills
A skill is a folder with a SKILL.md describing a recurring task, such as a release or a translation. Claude loads it on its own when the description matches your request, or you call it directly with /name. The benefit: the instructions live in the project once and are only loaded when needed. Project skills live in .claude/skills/, personal ones in ~/.claude/skills/.
# .claude/skills/release/SKILL.md
---
name: release
description: Prepares a release. Use when I ask for a release or a new version.
disable-model-invocation: true
---
1. Run npm run test and stop on failures.
2. Write the changelog from the commits since the last tag.
3. Suggest a version number following SemVer and wait for my OK.Tip:The description decides when Claude loads the skill. State what it does and when it fits. With disable-model-invocation: true only you can start it, which makes sense for anything with consequences, like deploys or releases.
Hooks
Hooks are shell commands that Claude Code runs on fixed events. Unlike a rule in CLAUDE.md, they always run, no matter what Claude decides. Important events are PreToolUse (before a tool, can block it), PostToolUse (after it), Stop (when Claude finishes) and SessionStart. Hooks live in the "hooks" block of a settings.json; /hooks shows all active ones.
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Edit|Write",
"hooks": [
{
"type": "command",
"command": "f=$(jq -r '.tool_input.file_path') && npx prettier --write --ignore-unknown \"$f\""
}
]
}
]
}
}Tip:The example needs the jq tool, which reads the file path from the data Claude Code passes to the hook. A PreToolUse hook that exits with code 2 blocks the action and returns the reason to Claude.
Subagents
A subagent is a specialised helper with its own context window. Claude hands it a subtask, such as a code review or a broad search, and only gets the summary back. That keeps your main conversation lean. You can restrict a subagent’s tools, for example to read-only. Project subagents live in .claude/agents/, personal ones in ~/.claude/agents/.
# .claude/agents/code-reviewer.md
---
name: code-reviewer
description: Reviews changes for bugs, readability and security. Use after every larger change.
tools: Read, Glob, Grep
model: sonnet
---
You review code. Name concrete problems with file and line
and suggest a fix. Do not change anything yourself.Tip:Only name and description are required. The text below the frontmatter is the instruction the subagent works with. Without tools it inherits all tools of the main session.
MCP: connecting external tools
With the Model Context Protocol (MCP) you connect Claude Code to further tools and data sources, such as a database, a ticket system or your own service. /mcp shows which servers are connected. How to set up a server and what to watch out for regarding security is covered in detail in my guide “Connecting MCP servers”.
How I work with it
For bigger tasks I let Claude plan first (Shift + Tab for plan mode), then implement. I review every change in the diff, and tests run before every commit. Claude is my sparring partner; understanding stays my job.
- Plan first: in plan mode I describe the goal and read the plan before any file changes.
- Small steps: several short tasks rather than one huge one. That keeps the context clean and the diff readable.
- Review the diff: I read every change before I accept it.
- Tests before the commit, then a small commit with a clear message.
- New task, new context: when a topic is done, I start fresh with /clear.
Common problems and fixes
Most problems come from too much context, tasks that are too big or missing rules. These are the cases you will run into most often:
- Answers get vague or Claude forgets agreements: the context is full. Check with /context, then use /compact (optionally with a hint on what the summary should focus on) or /clear for a new topic.
- Claude gets lost in a big task: interrupt with Esc, break the task into steps in plan mode and implement them one by one.
- A change was wrong: use /rewind or press Esc twice to go back to an earlier state.
- Constant permission prompts: add safe, recurring commands such as tests as an allow rule, or switch to acceptEdits mode for pure file work.
- Claude ignores a rule: CLAUDE.md is too long or too vague. Shorten it, phrase rules concretely and back up important ones with a hook or deny rule.
Checklist
Once these points are done, Claude Code is set up for everyday work:
- claude --version prints a version number, /status shows the right account.
- A short CLAUDE.md with commands and hard rules is in the project.
- .claude/settings.json allows the usual commands and blocks .env and secrets.
- A formatting hook runs after every change.
- Recurring workflows are set up as skills.
- You know plan mode, Esc, /compact and /clear.
More notes
- Guiden8n with AIBuilding n8n workflows that use AI to sort emails, read data from documents and suggest replies. Including installation, error handling, data protection and operations.
- GuideConnecting MCP serversHow to connect Claude to your own data and tools through the Model Context Protocol, safely and step by step.
- NoteConditional Access einführen, ohne sich auszusperrenConditional Access ist mächtig, und genau das macht es riskant. Eine einzige Richtlinie mit „Alle Benutzer, alle Ressourcen, Zugriff blockieren“ sperrt die ganze Organisation aus, die Admins eingeschlossen. Die meisten Probleme entstehen nicht durch exotische Einstellungen, sondern weil eine Richtlinie direkt scharf geschaltet wird, ohne sie vorher zu testen.