How to Run Claude Code Locally
A tutorial by Alvaro Cintas. Featured in the OTF curated resource library.
Prerequisites
Before installing Claude Code, ensure your system meets these requirements:
- Operating System: macOS 12+, Ubuntu 20.04+, or Windows 11 with WSL2
- Node.js: Version 18 or later (Claude Code uses Node.js for its runtime)
- Git: Installed and configured (Claude Code uses git for change tracking)
- Terminal: Any modern terminal — iTerm2, Warp, Windows Terminal, or your default
You'll also need an Anthropic API key or a Claude Code subscription. Both provide access to the same agent capabilities. The subscription is simpler (no API key management); the API key offers more flexibility for team setups.
Installation
Three steps to a working Claude Code installation.
Install via npm
Claude Code is distributed as an npm package. Install it globally so you can use it from any directory.
npm install -g @anthropic-ai/claude-code
Authenticate
Run the authentication command. This opens a browser window where you sign in with your Anthropic account. The token is stored securely on your machine.
claude-code auth
Verify the installation
Run a simple test to confirm everything works. Navigate to any project directory and start a conversation.
cd your-project claude-code # Type: 'What files are in this project?' to verify it can read your codebase
Your First Project
Set up your first project for optimal Claude Code interaction.
Create an AGENTS.md file
At your project root, create an AGENTS.md file describing your project's tech stack, conventions, and current focus. Claude Code reads this automatically and uses it to align output with your preferences.
# AGENTS.md ## Project My App — a React + TypeScript web application. ## Stack - React 18 + Vite - Tailwind CSS - React Query for data fetching ## Conventions - Functional components with named exports - Custom hooks in src/hooks/ - Keep files under 150 lines
Start with a simple task
Begin with something small to build confidence: 'Read the project structure and describe the architecture.' This verifies Claude Code can read your files and understand the codebase.
Attempt a real change
Try a real task: 'Add a loading spinner component to src/components/ui/. Follow the same pattern as existing components in that directory.' Review the output, accept or reject, and iterate.
Essential Commands
/help — See all commands
Shows a complete list of available slash commands and their descriptions. Your first stop when you forget a command.
/compact — Compress context
Summarizes the conversation so far to free up context window space. Use after 15-20 turns or when output quality starts degrading.
/clear — Fresh start
Clears the conversation and starts fresh. Use when switching to an unrelated task within the same project.
/review — Code review
Asks Claude Code to review recent changes (staged or unstaged git changes). Great for a pre-commit quality check.
Troubleshooting
Permission denied errors
If npm global install fails with permission errors, either fix npm permissions (recommended) or use `sudo npm install -g`. On macOS, consider using nvm to manage Node.js without sudo.
Authentication issues
If `claude-code auth` fails, check your internet connection and ensure your Anthropic account is active. Try `claude-code auth --reset` to clear cached credentials and start fresh.
Slow responses
Large codebases take longer for initial indexing. The first query in a new project may be slower. Subsequent queries are faster as Claude Code caches project understanding.
