# Installing Claude Code (Native Version)

**Goal:** Install the official native version of Claude Code and verify it's working correctly.

**Time Required:** 5-10 minutes

---

## Why Native Version?

The native version is the official, auto-updating installation method recommended by Anthropic. Avoid installing via package managers (npm, volta, brew) as they often install outdated versions and don't auto-update.

✅ **Native version**: Auto-updates, official support, latest features
❌ **Package manager versions**: Outdated, no auto-updates, conflicts

---

## Installation by Platform

### macOS

**Step 1: Install**

Open Terminal and run:

```bash
curl -fsSL https://desktop-releases.anthropic.com/install.sh | sh
```

This installs to: `~/.local/bin/claude`

**Step 2: Add to PATH (if needed)**

Check if already in PATH:
```bash
which claude
```

If it returns `/Users/yourusername/.local/bin/claude`, you're good!

If not, add to your shell config:

```bash
# For zsh (default on macOS)
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bash_profile
source ~/.bash_profile
```

**Step 3: Verify**

```bash
claude --version
# Should show: 2.0.58 or newer

which claude
# Should show: /Users/yourusername/.local/bin/claude
```

---

### Linux

**Step 1: Install**

Open terminal and run:

```bash
curl -fsSL https://desktop-releases.anthropic.com/install.sh | sh
```

This installs to: `~/.local/bin/claude`

**Step 2: Add to PATH (if needed)**

Check if already in PATH:
```bash
which claude
```

If it returns `/home/yourusername/.local/bin/claude`, you're good!

If not, add to your shell config:

```bash
# For bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# For zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

**Step 3: Verify**

```bash
claude --version
# Should show: 2.0.58 or newer

which claude
# Should show: /home/yourusername/.local/bin/claude
```

---

### Windows

**Step 1: Install**

Open PowerShell and run:

```powershell
irm https://desktop-releases.anthropic.com/install.ps1 | iex
```

This installs to: `%LOCALAPPDATA%\Programs\Claude Code\`

**Step 2: Verify**

Close and reopen PowerShell, then:

```powershell
claude --version
# Should show: 2.0.58 or newer

where.exe claude
# Should show path in %LOCALAPPDATA%\Programs\Claude Code\
```

---

## Post-Installation: Run Doctor

After installation, verify everything is set up correctly:

```bash
claude doctor
```

**What to look for:**

✅ **Good output:**
```
Diagnostics
└ Currently running: native (2.0.58 or newer)
└ Path: /Users/you/.local/bin/claude (or similar)
└ Config install method: native
└ Auto-updates: default (true)
└ Search: OK (bundled or vendor)
```

❌ **Problem indicators:**
- Version shows `unknown` or old version like `2.0.51`
- Install method shows anything other than `native`
- Path shows volta, npm, or node_modules
- Any errors in "Invalid Settings" section

---

## Common Issues & Solutions

### Issue 1: Multiple Claude Installations Detected

**Symptom:** `which -a claude` shows multiple paths

```bash
$ which -a claude
/Users/you/.volta/bin/claude         # ❌ Old volta version
/Users/you/.local/bin/claude         # ✅ Correct native version
```

**Solution:** Remove the conflicting installation

**If installed via volta:**
```bash
volta uninstall @anthropic-ai/claude-code
# Or manually remove symlink
rm ~/.volta/bin/claude
```

**If installed via npm/npx:**
```bash
npm uninstall -g @anthropic-ai/claude-code
```

**If installed via homebrew:**
```bash
brew uninstall claude-code
```

**Verify fix:**
```bash
which claude
# Should show only: /Users/you/.local/bin/claude
```

---

### Issue 2: PATH Order Wrong

**Symptom:** `which claude` shows wrong version even though native is installed

**Solution:** Ensure `~/.local/bin` is early in PATH

Edit your shell config (`~/.zshrc`, `~/.bashrc`, or `~/.bash_profile`):

```bash
# Add this near the TOP of the file
export PATH="$HOME/.local/bin:$PATH"
```

Reload:
```bash
source ~/.zshrc  # or ~/.bashrc
```

---

### Issue 3: Auto-Updates Not Working

**Symptom:** `claude doctor` shows `Auto-updates: false` or version is old

**Solution:**

1. Uninstall any non-native versions (see Issue 1)
2. Reinstall using native method (see Installation by Platform)
3. Verify: `claude doctor` should show `Auto-updates: default (true)`

---

### Issue 4: Command Not Found

**Symptom:** `bash: claude: command not found`

**Solution:**

1. Verify installation completed:
   ```bash
   ls -la ~/.local/bin/claude
   ```
   Should show the file exists.

2. If file exists, add to PATH (see Step 2 under your platform)

3. If file doesn't exist, reinstall using native method

---

## Verifying Your Installation

Run these commands to confirm everything is correct:

```bash
# 1. Check version (should be 2.0.58+)
claude --version

# 2. Check path (should be ~/.local/bin/claude or similar)
which claude

# 3. Run doctor (should show "native" install method)
claude doctor

# 4. Verify only one installation
which -a claude
# Should show only ONE path
```

**Expected output:**
- ✅ Version: 2.0.58 or newer
- ✅ Path: `~/.local/bin/claude`
- ✅ Install method: `native`
- ✅ Auto-updates: `true`
- ✅ Only ONE installation found

---

## Next Steps

Once installation is verified:

1. **Authenticate:** Run `claude` and follow prompts to log in
2. **Configure permissions:** See [`.claude/README.md`](../.claude/README.md) for permission setup
3. **Start using:** Navigate to a project and run `claude`

---

## Getting Help

**Official Documentation:**
- [Claude Code Docs](https://code.anthropic.com/)
- [Installation Guide](https://docs.anthropic.com/claude-code/installation)

**If still having issues:**
1. Run `claude doctor` and capture output
2. Check for conflicting installations: `which -a claude`
3. Verify PATH: `echo $PATH | tr ':' '\n' | grep -E '(local|volta|npm)'`
4. Open an issue with output from above commands

---

## Why This Matters

Using the correct installation method ensures:
- ✅ Latest features and bug fixes (auto-updates)
- ✅ Best performance (native binary)
- ✅ Official support from Anthropic
- ✅ Compatibility with `.claude/` configurations in this repo
- ✅ Consistent behavior across your team

**Bottom line:** Take 5 minutes now to install correctly, save hours of debugging later.
