Setting Up Claude Code for Success

The thirty minutes you spend on setup decide whether Claude Code feels sharp or frustrating for the next year. Defaults are sensible. Tuned settings remove most of the friction that makes engineers give up in week two.

Installation

Use the native installer. It updates itself and avoids Node version conflicts.

# Native binary (recommended)
curl -fsSL https://claude.ai/install.sh | bash

# macOS alternative
brew install --cask claude-code

# Verify
claude --version

A global npm package also exists and needs Node.js 22 or later, but the native installer is the recommended path. Homebrew installs do not auto-update; run brew upgrade claude-code periodically.

Then authenticate and start your first session from the root of a repository:

cd your-project
claude

Where configuration lives

Claude Code reads settings from a hierarchy. More specific files override broader ones, and enterprise-managed settings override everything.

File	Scope	Commit it?
Managed settings (set by IT)	Whole organization	Not applicable
~/.claude/settings.json	You, every project	No
.claude/settings.json	Project, whole team	Yes
.claude/settings.local.json	You, this project	No (gitignore it)
~/.claude/CLAUDE.md	Your personal instructions, every project	No
CLAUDE.md in the repo	Team instructions for this project	Yes

The rule of thumb: team conventions go in committed project files, personal taste goes in your home directory, and secrets go nowhere near either.

The .claude/ directory

A mature project ends up with a layout like this:

.claude/
├── settings.json        # permissions, hooks, env (committed)
├── settings.local.json  # personal overrides (gitignored)
├── skills/              # project skills, one folder each
├── agents/              # project subagents
└── commands/            # legacy slash commands (still supported)

Your home directory has the same structure under ~/.claude/ for personal versions of each.

Permissions that do not interrupt you

The first annoyance most people hit is permission prompts. Claude Code asks before running commands or editing files, which is correct for safety and painful for flow. Fix it with an allowlist rather than by turning safety off.

{
  "permissions": {
    "allow": [
      "Read",
      "Edit",
      "Bash(npm run test *)",
      "Bash(npm run lint *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Bash(git log *)",
      "WebFetch(domain:docs.python.org)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

Allow the read-only and test commands you run constantly. Deny destructive commands and secret files explicitly. The trailing * is a wildcard; older configs write the same rule as Bash(git diff:*), which still works. Manage rules interactively with /permissions, or run /fewer-permission-prompts, which scans your past sessions for common read-only commands and proposes an allowlist.

Permission modes and plan mode

Press Shift+Tab to cycle permission modes during a session: the default mode that asks before actions, acceptEdits for file edits without prompts, and plan mode, where Claude researches and proposes a plan but makes no edits. Where available, auto mode lets a classifier review actions instead of you. Plan mode is the one that matters most, and you will use it constantly from Chapter 8 onward. You can also enter it directly with /plan.

Model selection

Use /model to switch models mid-session. A practical default: the most capable model for planning, architecture, debugging, and security review; a faster model for mechanical work like renames, formatting fixes, and boilerplate. Subagents can each specify their own model (Chapter 6), which is how teams keep costs sane.

Shortcuts worth memorizing

Key or syntax	What it does
Esc	Interrupt Claude mid-action without losing context
Esc, Esc	Open rewind to jump back to an earlier point
Shift+Tab	Cycle permission modes, including plan mode
@path/to/file	Pull a specific file into context
!command	Run a shell command directly and share its output
/	List built-in and custom commands
claude --continue	Resume the most recent session
claude --resume	Pick an earlier session to resume

Interrupting with Esc is underused. If Claude heads the wrong way, stop it immediately instead of waiting for it to finish a bad approach.

IDE integration

Claude Code runs in the terminal but integrates with VS Code and JetBrains IDEs, where it can see your open file and selection and show diffs in the editor. Many engineers run it in the IDE's integrated terminal for that reason. Neovim users typically run it in a split.

The first-day checklist

• Install the native binary and confirm claude --version
• Run /init in your main repository
• Commit a .claude/settings.json with a starter allowlist and denylist
• Add .claude/settings.local.json and CLAUDE.local.md to .gitignore
• Deny reads of .env and secret directories
• Allowlist your five most-used documentation domains for WebFetch
• Create ~/.claude/CLAUDE.md with your personal preferences (tone, verbosity, languages)
• Install the IDE extension for your editor
• Try plan mode on one small task
• Add shell aliases, for example alias cc='claude' ccc='claude --continue'

Key takeaways

• Install with the native installer and commit a project .claude/settings.json.
• Fix permission fatigue with an allowlist of safe commands, never by skipping permissions on a real machine.
• Deny reads of .env and secret directories explicitly.
• Learn Shift+Tab for plan mode and Esc to interrupt early.