Claude Code turns your terminal into a live AI pair-programmer. This guide is for developers who've heard the buzz but haven't yet typed that first command — by the end you'll have Claude Code installed, authenticated, and running its first real task inside a project directory.
The Problem: "Where Do I Even Start?"
Most AI coding tools drop you into a web UI. Claude Code is different — it lives in your terminal, reads your actual files, and can execute commands on your machine. That power comes with a slightly steeper first-run experience than clicking "Sign Up."
The documentation is sparse for beginners. The npm package installs fine, but then you stare at a blinking cursor and wonder whether you did anything right. I hit three separate confusion points before things clicked, so here's the path I wish I'd had.
Section 1: Prerequisites
You need Node.js 18+ and npm. Check what you have:
node --version # need 18.0.0 or higher
npm --version # need 8+ recommended
If you're behind, the fastest fix on macOS is:
brew install node
On Ubuntu/Debian:
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt-get install -y nodejs
On Windows, grab the LTS installer from nodejs.org — WSL2 is strongly recommended over native PowerShell for Claude Code.
One gotcha: if you're using nvm, make sure you've run nvm use to activate the right version before the global install. I once installed Claude Code into nvm's Node 16 slot and spent 20 minutes wondering why the binary wasn't updating.
Section 2: Installation
Create a clean working directory first. It matters — Claude Code reads your current directory's file tree on startup, so starting inside a sprawling monorepo on your first run will confuse both you and the agent.
mkdir my-claude-project && cd my-claude-project
Now install the package globally:
npm install -g @anthropic-ai/claude-code
Verify it landed:
claude --version
Expected output (version will vary):
claude-code/1.x.x linux-x64 node-v20.x.x
If you get command not found, your npm global bin directory isn't in PATH. Fix:
# find where npm puts global binaries
npm config get prefix
# then add <prefix>/bin to your PATH in ~/.bashrc or ~/.zshrc
export PATH="$(npm config get prefix)/bin:$PATH"
source ~/.bashrc
Section 3: First Launch and Authentication
Inside your project directory, just run:
claude
On first launch it'll prompt for an Anthropic API key. If you don't have one yet, head to console.anthropic.com, create an account, and generate a key under API Keys.
? Enter your Anthropic API key: sk-ant-...
✓ API key saved to ~/.claude/config.json
What happens next is the part that surprised me: Claude Code doesn't just sit there waiting. It immediately scans the directory tree and builds a mental model of your project. In an empty folder this takes a second. In a real codebase it might take a few seconds longer — that's normal.
Section 4: The Permission System (Don't Panic)
This is where new users freeze up. Claude Code can read files, write files, and execute shell commands. When it tries to do any of these for the first time, it stops and asks:
Claude wants to run: npm install express
Allow? [y/n/always]
This is not an error. It's the trust model working correctly. Think of it as sudo for AI actions — you stay in control of what it actually touches.
Your options at each prompt:
| Response | What it does |
|---|---|
y |
Allow this one command |
n |
Deny, Claude tries another approach |
always |
Allow this command type for the session |
For a scratch project you're exploring, hitting always on common operations (file read, npm commands) saves interruptions. For production code, stay with y and review each action.
Section 5: Your First Real Command
Once the prompt is live, try something concrete rather than "hello":
> Create a simple Express server in index.js that responds with "Hello Claude" on GET /
Claude Code will:
1. Write index.js with the server code
2. Check whether express is in package.json
3. Ask permission to run npm install express if needed
4. Optionally offer to run the server to verify it works
Watch the file actually appear in your directory:
ls -la
# index.js package.json node_modules/
Then verify it runs:
node index.js
# Server running on port 3000
curl http://localhost:3000
# Hello Claude
That feedback loop — ask, watch files change, verify with a real command — is the core workflow. Everything else is just scaling it up.
Section 6: Variations and Gotchas
macOS with System Integrity Protection
If npm install -g fails with permission errors, don't use sudo. Instead, change your npm prefix:
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc
Then re-run the install.
Docker / devcontainer users
Claude Code works fine inside a container. Mount your project directory and install Node inside the image. The API key prompt still appears on first run — pass it via environment variable to skip the interactive prompt:
export ANTHROPIC_API_KEY=sk-ant-...
claude
WSL2 on Windows
Works well. Avoid running from the Windows filesystem (/mnt/c/...) — put your project under ~/ in the Linux filesystem for much better performance.
Rate limits on first day
Free-tier Anthropic accounts have low rate limits. If Claude suddenly stops mid-task with a 429 error, you've hit the ceiling. Wait a minute or upgrade to a paid tier. The task state isn't lost — just re-enter the prompt and Claude picks up where it left off.
Closing
The install itself takes two minutes. The real investment is learning the permission model and getting comfortable watching AI write files in real time — that mental shift takes one or two sessions.
From here, the natural next step is pointing Claude Code at an existing project and asking it to explain the codebase structure. That single session will show you more about what the tool can do than any amount of reading.
🐦 Faster updates on X: @baegseungh7061
📚 More in this series: Code Intro
💌 Subscribe: Follow on X or grab the RSS
댓글
댓글 쓰기