Getting started with Claude Code requires thoughtful setup to maximize its capabilities. These 15 tips will help you configure Claude Code for optimal performance, whether you’re working solo or as part of a team.
The Claude Code extension works with VS Code, Cursor, and Windsurf. While it’s essentially just a launcher, it provides critical benefits:
# Install from VS Code marketplacecode --install-extension anthropic.claude-code# Works automatically with Cursor# Extension available in Cursor marketplace# Search for "Claude Code" in:# Settings → Plugins → MarketplaceThe native installer is the recommended way to install Claude Code — it self-updates in the background, so you stay on the latest version automatically:
# macOS, Linux, WSLcurl -fsSL https://claude.ai/install.sh | bash
# Windows PowerShellirm https://claude.ai/install.ps1 | iexAlternative installation methods:
brew install --cask claude-codeHomebrew installs do not auto-update — run brew upgrade claude-code periodically.
npm install -g @anthropic-ai/claude-codeThe global npm install is the legacy method and is now deprecated — prefer the native installer above. If you’re already on an npm install, migrate with claude install. Avoid sudo npm install -g, which causes permission issues.
# Run Claude Code inside the official reference dev container# See: https://code.claude.com/docs/en/devcontainerThere is no standalone Docker image. For an isolated, reproducible environment, use the documented devcontainer, which also pairs well with --dangerously-skip-permissions for sandboxed automation.
One of the most impactful configuration changes is bypassing constant permission requests:
claude --dangerously-skip-permissionsThis eliminates interruptions for:
Security Consideration
This is similar to Cursor’s “yolo mode” and it genuinely can run destructive commands without asking. Only use it inside a trusted, sandboxed context — a devcontainer, a throwaway VM, or CI on a branch. Never enable it on untrusted code, a shared machine, or anywhere a bad rm/git push --force would hurt. For a middle ground, combine --permission-mode plan with --allow-dangerously-skip-permissions so bypassing is available but not active by default.
The GitHub CLI (gh) enables powerful Claude Code integrations:
# macOSbrew install gh
# Linux/WSLcurl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo gpg --dearmor -o /usr/share/keyrings/githubcli-archive-keyring.gpgecho "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/nullsudo apt update && sudo apt install gh
# Windowswinget install GitHub.cliAfter installation, authenticate:
gh auth loginThis enables:
Set up proper IDE integration for seamless workflow:
Configure keyboard shortcuts
// VS Code settings.json{ "keybindings": [ { "key": "cmd+shift+c", "command": "claude-code.open", "when": "editorTextFocus" } ]}Set up file associations
{ "files.associations": { "CLAUDE.md": "markdown", "*.claude": "markdown" }}Configure terminal integration
# Add to ~/.zshrc or ~/.bashrcalias cc="claude"alias ccc="claude --dangerously-skip-permissions"Run the terminal setup command to configure proper key bindings:
claude# Then run:/terminal-setupThis enables:
For large-scale refactoring and architectural work, lean on Claude Code’s real planning mechanisms rather than diving straight into edits:
Shift+Tab to cycle into plan mode (or launch with claude --permission-mode plan). Claude investigates and proposes a plan without touching files until you approve it.opusplan model alias — Set --model opusplan so Opus does the reasoning during plan mode, then execution drops to Sonnet to save cost. See Tip 8.--add-dir — Bring sibling repositories into scope for cross-repo refactors. See Tip 9.When to Reach for Plan Mode
Understand the model selection strategy for optimal results:
{ "model": "opusplan"}The model field takes a single alias (opus, sonnet, haiku, opusplan, sonnet[1m]) or a full model id. There is no per-task modelPreferences map — instead you pick a default here and switch on the fly with /model <alias> mid-session, or override at startup with claude --model <alias>.
Model selection guidelines:
fable): The highest-capability tier — complex multi-file refactorings, building from scratch, long-running tasks where quality matters more than cost. Switch with /model fable. See model comparison for plan inclusion details.opus): Complex architecture, system design, difficult debugging; raise effort for the hardest cases. The Claude Code default model.sonnet / sonnet[1m]): Routine development, standard features, refactoring, 1M context when neededhaiku): Simple tasks, formatting, basic code generationopusplan: Best of both — Opus during plan mode, Sonnet during execution; for maximum quality use fable during planning and Opus or Sonnet for implementationFor projects spanning multiple repositories:
# Start Claude Code with multiple directoriesclaude --add-dir ../backend --add-dir ../frontend --add-dir ../shared
# Or add during session/add-dir ../backend/add-dir ../frontendAdditional directories are scoped to the session: pass --add-dir at launch or use the /add-dir slash command mid-session. To make extra directories stick across sessions, set permissions.additionalDirectories in .claude/settings.json — it persists the same access without retyping flags:
{ "permissions": { "additionalDirectories": ["../docs/"] }}If you’d rather not commit it to project settings, wrapping the launch command in a shell alias (see Tip 5) is still a fine quick hack.
Ensure Claude Code inherits your development environment:
export PATH="$HOME/.local/bin:$PATH"export NODE_OPTIONS="--max-old-space-size=8192"source ~/.nvm/nvm.sh
# Custom aliases Claude should know aboutalias build="npm run build:all"alias test="npm run test:coverage"alias deploy="./scripts/deploy.sh"Document custom tools in CLAUDE.md:
# Custom Tools and Commands
- `build`: Runs full build pipeline with type checking- `test`: Runs tests with coverage reporting- `deploy`: Deploys to staging (requires VPN connection)Set up your project with appropriate permissions:
# Fix common permission issuesfind . -type f -name "*.sh" -exec chmod +x {} \;chmod -R u+rw .claude/
# Create .claude directory with proper permissionsmkdir -p .claude/{commands,hooks,settings}chmod 755 .claudeModel Context Protocol (MCP) servers extend Claude Code’s capabilities:
// .mcp.json (project-level){ "mcpServers": { "github": { "type": "http", "url": "https://api.githubcopilot.com/mcp/" }, "git": { "command": "uvx", "args": ["mcp-server-git"] }, "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "."] }, "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp"] } }}Essential MCP servers for development:
https://api.githubcopilot.com/mcp/): PRs, issues, code reviewuvx mcp-server-git): local git operations@modelcontextprotocol/server-filesystem): scoped file operations@playwright/mcp): browser automation and end-to-end testingserver-postgres package is archived)When MCP servers aren’t working correctly:
claude --debug "mcp"This provides:
Common troubleshooting steps:
List configured servers and their status
claude mcp listclaude mcp get githubConfirm the launchers are on your PATH
which npx # for npm-based serverswhich uvx # for Python-based servers like mcp-server-gitInspect connection logs in detail
claude --debug "mcp"Create a comprehensive project configuration:
{ "allowedTools": [ "Read", "Edit", "Write", "Bash(git:*)", "Bash(npm:*)", "Bash(yarn:*)", "Bash(pnpm:*)", "mcp__git__*", "mcp__github__*" ], "hooks": { "PostToolUse": [ { "matcher": "Edit|Write", "hooks": [ { "type": "command", "command": "jq -r '.tool_input.file_path' | xargs -r prettier --write" } ] } ] }}Share with your team by committing to version control:
git add .claude/settings.jsongit commit -m "Add Claude Code project configuration"Balance security with productivity by customizing tool permissions:
{ "allowedTools": [ "Read", "Edit", "Write", "Glob", "Grep", "Bash(*)", "mcp__*" ]}{ "allowedTools": [ "Read", "Edit", "Write", "Bash(git:*)", "Bash(npm:test)", "mcp__github__*" ]}{ "allowedTools": [ "Read", "Bash(git:log)", "Bash(git:status)" ]}Use the /permissions command to modify during a session:
/permissions# Select tools to allow/deny interactivelyThese are the prompts that turn a fresh checkout into a well-configured project. Run them inside Claude Code from your repo root.
Setup rarely fails loudly — it fails by being silently ignored. Here are the usual culprits and the fast fixes.
claude --debug "mcp" to see the actual error, then confirm the launcher is installed (which npx, which uvx). Python-only servers like mcp-server-git need uvx on PATH — npx will not work for them..claude/settings.json seems ignored. Check the scope and path: project settings live at .claude/settings.json in the repo root; user settings at ~/.claude/settings.json. A typo in a key (for example servers instead of mcpServers in .mcp.json, or hooks as an array instead of an object) makes Claude Code skip the block entirely with no error.allowedTools pattern probably doesn’t match. Tool names are case-sensitive (Read, not View) and Bash scoping uses the Bash(cmd:*) form. Use /permissions mid-session to add the exact rule, then copy it into settings.With Claude Code properly configured, you’re ready to optimize your project context. Continue to CLAUDE.md Optimization to learn how to create effective persistent memory for your projects.