Claude Code setup — install, permissions, hooks, MCP in the first hour

Claude Code is Anthropic's official agentic CLI. It's powerful once set up, but skipping the permission model, CLAUDE.md, hooks, and MCP at install time means you'll repeat the same manual work daily. This guide walks through macOS / Linux / Windows (Git Bash or WSL2) install → auth → project guidance → permissions → hooks → MCP, in order.

It's targeted at developers who already use git/Node comfortably but are either new to Claude Code, or using it without a tidied setup.

TL;DR

1. Node.js 20+ → npm install -g @anthropic-ai/claude-code → claude → browser auth
2. Drop CLAUDE.md (1–2 screens) + .claude/settings.json (permissions/env/hooks) at the project root
3. Three slash commands to start: /help, /config, /init
4. When a command keeps getting denied, add a pattern to permissions.allow
5. Add MCP servers only when you need one — prefer local stdio, keep tokens in env

Prerequisites

• Node.js 20+ — node -v. Older? Upgrade via mise or nvm
• Anthropic account — console.anthropic.com or a Claude.ai Pro/Max subscription
• Git — used by the CLI to inspect the project. On macOS see /mac/initial-setup
• OS: macOS / Linux / Windows (Git Bash or WSL2 recommended; raw PowerShell works but reduces sh-based hook compatibility)

1. Install — 5 minutes

1.1 npm global install

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

Permission error? Instead of sudo, move the npm prefix to your home:

mkdir -p ~/.npm-global
npm config set prefix ~/.npm-global
echo 'export PATH=$HOME/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
npm install -g @anthropic-ai/claude-code

1.2 First run + auth

cd into the project you want to work in and run:

cd ~/projects/my-repo
claude

On first run a browser tab opens for Anthropic auth. After signing in, the CLI starts a chat. The token is stored in the OS keychain so you won't re-auth every time.

1.3 Verify

claude --version
# prints something like 0.x.x

2. Three slash commands to know first

Inside the CLI, commands starting with / are slash commands. Three are enough to start:

Run /init once per new project — it inspects folder structure, language, and build tools to produce a plausible starting draft you can then refine.

3. CLAUDE.md — project guidance (most important)

CLAUDE.md is a markdown file at the project root that is auto-loaded at the start of every session. Rules written here become top priority for the entire session.

A good CLAUDE.md

# Project — Claude guidance
 
## Persona
(optional) Role hint, e.g. "Act as a senior engineer who reviews diffs critically."
 
## Stack
- Framework: Next.js 16 (App Router)
- Language: TypeScript strict
- DB: Supabase
 
## Commands
- Dev server: `pnpm dev`
- Build: `pnpm build`
- Tests: `pnpm test`
 
## Conventions
- No `any` (TS strict)
- File names: kebab-case (routes), camelCase (utils)
- Never hardcode secrets
 
## Git
- Commits: `[Project] {type}: {desc}` — feat/fix/refactor/...
- Direct push to main: OK (solo) / PR required (team)
 
## Working principles
1. Plan first when changes touch 5+ files / new module / architecture
2. After code changes, do not declare "done" until lint+build+tests pass
3. Secrets · DB migrations · external pushes require explicit approval

Tips

• Keep it short — 1–2 screens. Anything longer goes into memory/rules/{topic}.md and is linked from CLAUDE.md.
• Use a per-project file; put cross-project guidance in ~/.claude/CLAUDE.md.
• Commit CLAUDE.md to git so teammates and other machines pick it up.

4. .claude/settings.json — permissions, env, hooks

The file that controls runtime behavior. The block you'll edit most is permissions.

4.1 Skeleton

{
  "permissions": {
    "allow": [
      "Bash(git status:*)",
      "Bash(git diff:*)",
      "Bash(pnpm test:*)",
      "Read(/Users/me/projects/**)"
    ],
    "deny": [
      "Bash(rm -rf /:*)",
      "Bash(sudo *)"
    ]
  },
  "env": {
    "EDITOR": "code --wait"
  },
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          { "type": "command", "command": "echo '[Session start] $(date)'" }
        ]
      }
    ]
  }
}

4.2 Permission rules (permissions.allow / deny)

• When a Bash(...) keeps getting denied, add it to allow as a pattern
• Patterns prefix-match — Bash(pnpm:*) allows anything starting with pnpm
• Pin dangerous patterns (rm -rf, sudo, curl … | bash) into deny for safety

💡 To bulk-add common read-only commands, run the built-in skill /fewer-permission-prompts inside the CLI — it scans your transcripts and suggests an allowlist.

4.3 Downloadable template

The same configuration as a ready file (verify before using):

# 1. Download
curl -fsSL https://devalice.jaceclub.com/assets/ai-agents/claude-code/settings.example.json -o .claude/settings.example.json
 
# 2. Verify SHA-256
shasum -a 256 .claude/settings.example.json
# expected: 22898a20ade2b3497f8299a8ca6139112c476e0a0a4075e1a05123a02c8266ac
 
# 3. Inspect, then copy into place
less .claude/settings.example.json
cp .claude/settings.example.json .claude/settings.json

Don't paste secrets (API keys, etc.) into settings.json. Read them from OS env or a gitignored .env.

4.4 Global vs project vs local

5. Hooks — automatic triggers

Hooks run shell commands on specific events. The main ones:

Example 1: print environment at session start

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "startup",
        "hooks": [
          {
            "type": "command",
            "command": "printf '[Session start] %s\\nBranch: %s\\n' \"$(date '+%F %T')\" \"$(git branch --show-current 2>/dev/null || echo none)\""
          }
        ]
      }
    ]
  }
}

Example 2: block writes to secret files

PreToolUse can block via exit code. (1 = warn, 2 = block.)

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '\\.env$|secrets/|private_key' && { echo 'BLOCKED: secret file'; exit 2; } || exit 0"
          }
        ]
      }
    ]
  }
}

Spec details: /help → docs link, or the official docs. When debugging, start with a one-line echo hook to confirm it fires at all.

6. MCP servers — only when you need one

MCP (Model Context Protocol) is the standard for exposing external tools to Claude Code. Integrations exist for GitHub, Slack, Linear, Figma, and you can write your own.

Registration

Add to mcpServers in .claude/settings.json:

{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstash/context7-mcp"],
      "env": {}
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

${GITHUB_TOKEN} expands from your shell env — put export GITHUB_TOKEN=... in .zshrc or .envrc (direnv) to keep the secret out of settings.json.

Safety

• Prefer local stdio servers (command: "npx" or a local binary) — smaller attack surface than networked RPC servers
• Only verified packages — @modelcontextprotocol/*, @upstash/*, etc. Inspect unknown packages first
• Secrets via env — settings.json is often committed to git; never put tokens inline

7. IDE integration — VS Code · Cursor

Claude Code is a CLI but lives well inside IDEs:

• VS Code / Cursor integrated terminal — just run claude. Edit files in the IDE, chat in the terminal. Simplest.
• VS Code extension — search "Claude Code" in the marketplace to open it in a side panel.
• JetBrains (IntelliJ/PyCharm/…) — plugin available in the JetBrains marketplace.

If you already use an AI-native editor (Cursor, Windsurf), keep Claude Code for the "many-file / shell / git" tasks and let the in-editor AI do inline coding.

8. Verify — is setup complete?

# 1. Install
claude --version
 
# 2. Project setup files
ls -la CLAUDE.md .claude/settings.json
 
# 3. Global setup (optional)
ls -la ~/.claude/settings.json 2>/dev/null && echo "global OK" || echo "no global"
 
# 4. Auth — run `claude` and look for the welcome banner
#    > claude
#    │ Welcome to Claude Code!

If all four are green, you're done. First real task: claude in your project directory, then ask something like "Describe this repo's structure in one paragraph."

9. Troubleshooting

command not found: claude

• npm global bin not on PATH. npm config get prefix to find it → add <prefix>/bin to ~/.zshrc / ~/.bashrc
• Windows Git Bash: npm config get prefix should be C:\Users\<you>\AppData\Roaming\npm and that path must be on PATH

Browser auth doesn't open on first run

• Headless environment (SSH, WSL2): copy the URL from the CLI into a browser manually
• If auth still fails afterwards, delete the token cache under ~/.claude/ and try again

"Permission?" prompt on every Bash command

• Add common read-only commands to permissions.allow in .claude/settings.json
• Or /config → set permission mode to acceptEdits (auto-approve edits, still ask for shell)

Hooks don't fire

# 1. JSON valid?
cat .claude/settings.json | jq .
 
# 2. Simplify the command and check
# command: "echo HOOK_FIRED >> /tmp/claude-hook.log"

Broken JSON silently disables the hook section.

MCP server doesn't show up

• /mcp inside the CLI — see registered servers and status
• Confirm command is on PATH (which npx)
• Logs at ~/.claude/logs/ or stderr

10. What's next

This guide ended at "Claude Code is daily-usable". After that:

• Workflow patterns — multi-agent, plan mode, subagents (coming)
• Cursor comparison — /ai-agents/cursor-setup
• Advanced hooks — SessionStart for memory sync, PreToolUse for security gates
• Writing your own MCP server — exposing internal tools (coming)

References

• Claude Code official docs
• MCP official
• Anthropic Console — API keys / usage
• Claude Code GitHub Issues — bug reports

Changelog

• 2026-05-12 — Initial English translation (devAlice M2 i18n seed)