` to capture diagnostics.
>
> **Q: Do I need to reboot after editing PATH?**
>
> > **A: No reboot required, but you must open a new terminal window.**
Debug Quick Commands
_Check the output of `claude doctor` for log locations and environment checks._
> [!Note]
>
> ```bash
> claude # Open Claude UI (if on PATH)
> claude --version # Show the installed CLI version
> claude update # Native installer: check for and install an update
>
> claude doctor # Read-only install and settings diagnostics
> /doctor # Full checkup from an interactive session
>
> claude --debug # Launch with diagnostic logging
> claude --debug-file ./claude-debug.log
>
> Get-Command claude -All # Windows PowerShell: find conflicting installs
> where.exe claude # Windows CMD/PowerShell
> command -v -a claude # macOS/Linux (bash/zsh)
> ```
|
Path Temp Fix
**The native launcher normally lives in `.local/bin`. Add that directory for the current shell, then reinstall if the launcher is absent.**
> [!Note]
>
> #### Windows (CMD):
>
> ```bash
> set PATH=%USERPROFILE%\.local\bin;%PATH%
> where.exe claude
> claude --version
> ```
>
> #### Windows (PowerShell):
>
> ```powershell
> $env:Path = "$env:USERPROFILE\.local\bin;$env:Path"
> Get-Command claude -All
> claude --version
> ```
>
> #### Linux/MacOS (bash/zsh)
>
> ```bash
> export PATH="$HOME/.local/bin:$PATH"
> command -v -a claude
> claude doctor
> ```
For an npm installation only, the launcher is under the global npm prefix. Prefer migrating with `claude install stable`; otherwise inspect the prefix with `npm prefix -g` and add its executable directory to `PATH`.
|
Windows Path Perm Fix
**Replace `` with your own Windows username (without the angle brackets)**
- **Start → type: Environment Variables**
- **Open Edit the system environment variables → Environment Variables**
- **Under User variables for ``, select `Path` → `Edit` → `New`, then add:**
```path
C:\Users\\.local\bin
```
> **npm installation only:**
```path
C:\Users\\AppData\Roaming\npm
```
- **Remove duplicates, any entry containing `%PATH%`, and stray quotes (`"`). Click `OK`.**
- **Open a `new` Command Prompt/PowerShell and verify:**
```C
where.exe claude
claude doctor
```
> [!Tip]
>
> ### Optional Run directly (when PATH is broken)
>
> > **Windows (PowerShell/cmd)**
>
> ```powershell
> & "$env:USERPROFILE\.local\bin\claude.exe" --version
> & "$env:USERPROFILE\.local\bin\claude.exe" doctor
> ```
>
> > **npm installation:**
>
> ```powershell
> & "$env:APPDATA\npm\claude.cmd" doctor
> ```
|
Installation / Node.js Issues
**Native repair (recommended; no Node.js required)**
```bash
claude doctor
claude install stable
```
**Package-manager installs**
```bash
brew upgrade claude-code # or claude-code@latest
winget upgrade Anthropic.ClaudeCode
```
**npm install (Node.js 22+)**
```bash
node --version
npm install -g @anthropic-ai/claude-code@latest
```
Do not use `sudo npm install -g`. If two installations conflict, locate both before removing the one you no longer want.
|
Authentication Issues
> Subscription users should authenticate through the browser flow. API keys and third-party provider credentials are separate deployment paths.
```bash
claude auth status
claude auth login
claude auth login --console # Console/API billing instead of subscription login
```
If a subscription login unexpectedly behaves like API billing, check whether `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN`, `ANTHROPIC_BASE_URL`, or an `apiKeyHelper` is selecting provider authentication. Do not print secret values into logs. Persistent API/provider auth also disables subscription-only features such as Remote Control, cloud sessions, claude.ai connectors, and notification preferences.
Use `claude --debug-file ./claude-auth-debug.log` for a reproducible error report, then remove credentials from that log before sharing it.
|
|
**Inspect permissions**
```bash
/permissions
```
The UI shows each allow/ask/deny rule and its source. To reset a scope, edit the originating `settings.json` and remove the rules or set empty arrays:
```json
{
"permissions": {
"allow": [],
"ask": [],
"deny": []
}
}
```
|
MCP (Model Context Protocol) Issues
> **Debug MCP servers**
```bash
claude --debug='mcp'
claude --debug-file ./claude-mcp-debug.log
```
> **List & remove MCP servers**
```bash
claude mcp list
claude mcp get
claude mcp login
claude mcp remove
```
|
Repair or Reinstall (Windows / PowerShell)
Start with a non-destructive repair. This preserves settings, MCP configuration, credentials, sessions, and project history:
```powershell
claude doctor
claude install --force stable
Get-Command claude -All
claude --version
```
For WinGet, use `winget upgrade Anthropic.ClaudeCode` or reinstall that package. For npm, use Node.js 22+ and `npm install -g @anthropic-ai/claude-code@latest`.
> [!Caution]
> Do not delete `~/.claude`, `~/.claude.json`, project `.claude/`, or `.mcp.json` as a routine installation fix. Those paths contain settings, credentials, MCP configuration, trust decisions, session history, and data shared by the CLI, IDE integrations, and Desktop. Follow the [official uninstall instructions](https://code.claude.com/docs/en/setup#uninstall-claude-code) and back up anything you need before intentionally removing user data.
|
One‑Shot Health Check (copy/paste)
**Windows (PowerShell):**
```powershell
Get-Command claude -All
claude --version
claude doctor
claude auth status
```
**macOS/Linux (bash/zsh):**
```bash
command -v -a claude
claude --version
claude doctor
claude auth status
```
|
---
Appendix: Useful Paths
- **Native launcher:** Windows `%USERPROFILE%\.local\bin\claude.exe`; macOS/Linux/WSL `~/.local/bin/claude`
- **Native versions:** `%USERPROFILE%\.local\share\claude\` or `~/.local/share/claude/versions/`
- **User settings:** `~/.claude/settings.json`
- **Claude state, sessions, credentials, and caches:** `~/.claude/`
- **Global state and user/local MCP data:** `~/.claude.json` (not the user settings file)
- **Project settings:** `.claude/settings.json` and private `.claude/settings.local.json`
- **Shared project MCP:** `.mcp.json`
- **npm bin:** Windows `%APPDATA%\npm`; macOS/Linux `$(npm prefix -g)/bin`
|
Best Practices
> Curated guidance for safe, fast, and correct use of the Claude Code CLI and interactive REPL.
Effective Prompting
```bash
# Good: Specific and detailed
claude "Review UserAuth.js for security vulnerabilities, focusing on JWT handling"
# Bad: Vague
claude "check my code"
```
Tip: `claude "query"` starts the interactive REPL pre-seeded with your prompt; `claude -p "query"` runs **print mode** (non‑interactive) and exits.
---
Security Best Practices
1. **Start with minimal permissions**
- Prefer explicit allows and denies, either on the CLI or in settings files.
```bash
# Allow only what you need for this run
claude --allowed-tools "Read" "Edit" "Bash(npm run test *)"
```
Or commit a project policy at `.claude/settings.json`:
```json
{
"permissions": {
"allow": ["Read", "Edit", "Bash(npm run test *)"],
"deny": [
"WebFetch",
"Bash(curl *)",
"Read(./.env)",
"Read(./secrets/**)"
]
}
}
```
2. **Handle secrets correctly**
- Use a secret manager to inject environment variables for Agent SDK/automation flows; do not put literal keys in commands, settings, shell history, or repositories.
- In the interactive REPL, prefer `/login` instead of configuring an API key unless API/provider billing is intentional.
- Deny access to sensitive files in settings (replaces older `ignorePatterns`):
```json
{
"permissions": {
"deny": ["Read(./.env)", "Read(./.env.*)", "Read(./secrets/**)"]
}
}
```
3. **Audit permissions regularly**
```bash
/permissions
```
The browser shows merged allow/ask/deny rules and their user, project, local, plugin, or managed source.
4. **Avoid bypass modes in production**
- Do **not** use `--dangerously-skip-permissions` outside isolated/dev sandboxes.
- For unattended runs, combine narrow `--allowed-tools` with `--disallowed-tools`, project policy, and the sandbox where supported.
---
1. **Use machine‑readable output in automations**
```bash
claude -p "summarize this error log" --output-format json
# valid: text | json | stream-json
```
2. **Bound non‑interactive work**
```bash
claude -p "run type checks and summarize failures" --max-turns 3
# optionally also bound thinking:
export MAX_THINKING_TOKENS=20000
```
3. **Keep sessions tidy**
In `~/.claude/settings.json`:
```json
{
"cleanupPeriodDays": 20
}
```
4. **Limit context scope**
```bash
# Grant access only to relevant paths to reduce scanning/noise
claude --add-dir ./services/api ./packages/ui
```
5. **Pick the right model**
- CLI aliases: `--model sonnet` or `--model opus` (family alias selected by Claude Code).
- Use Opus 5 plus `/effort xhigh` or `max` for the hardest planning and review tasks when your account/provider supports it.
- For reproducibility in settings, pin a full model ID only when automatic family upgrades are undesirable.
6. **Use rendering and accessibility controls deliberately**
- Use `--ax-screen-reader` for flat screen-reader-friendly output and `/config` for theme, motion, and terminal behavior instead of copying undocumented environment toggles.
7. **Inspect usage by source**
```bash
/usage
```
Use `/usage` to break down plan usage by categories such as skills, subagents, plugins, and MCP servers.
---
Monitoring & Alerting
**1) Health checks**
Use the built‑in **doctor** command to verify installation and environment.
```bash
# Every 15 minutes
*/15 * * * * "$HOME/.local/bin/claude" doctor >/dev/null 2>&1 || \
mail -s "Claude Code doctor failed" admin@company.com /tmp/daily-analysis.json
```
**3) Telemetry (optional)**
Claude Code emits OpenTelemetry metrics/events. Set exporters in settings/env (e.g., OTLP) and ship to your observability stack (Datadog, Honeycomb, Prometheus/Grafana, etc.).
---
Collaboration Best Practices
Team Workflows
**1) Share versioned configuration**
`.claude/settings.json` (checked into the repository):
```json
{
"permissions": {
"allow": [
"Read",
"Edit",
"Bash(npm run lint)",
"Bash(npm run test *)"
],
"deny": [
"WebFetch",
"Read(./.env)",
"Read(./.env.*)",
"Read(./secrets/**)"
]
},
"model": "sonnet"
}
```
Use a family alias for automatic upgrades, or pin a full provider model ID only when reproducibility is more important.
**2) Documentation automation**
```bash
# Update docs with explicit tasks
claude "Update README.md to reflect the latest API endpoints and examples."
claude "Generate TypeScript types from schema.prisma and write to /types."
```
**3) Code review standards**
```bash
# Review a local diff with constrained tools
git fetch origin main
git diff origin/main...HEAD > /tmp/diff.patch
claude --allowed-tools "Read" "Grep" "Bash(git *)" \
"Review /tmp/diff.patch using team standards:
- Security best practices
- Performance considerations
- Code style compliance
- Test coverage adequacy"
```
Knowledge Sharing
**1) Project runbooks**
```bash
claude "Create a deployment runbook for this app: steps, checks, rollback."
claude "Document onboarding for new developers: setup, commands, conventions."
```
**2) Architecture docs**
```bash
claude "Update architecture docs to reflect new microservices."
claude "Create sequence diagrams for the authentication flow."
```
> Tip: Keep durable context in **CLAUDE.md** at the project root. In the REPL, use `/memory` to manage it and `@path` to import file content into prompts.
---
Common Pitfalls to Avoid
Security
**❌ Don’t**
- Use `--dangerously-skip-permissions` on production systems
- Hard‑code secrets in commands/config
- Grant overly broad permissions (e.g., `Bash(*)`)
- Run with elevated privileges unnecessarily
**✅ Do**
- Store secrets in env vars and credential helpers
- Start from minimal `permissions.allow` and expand gradually
- Audit with `/permissions` and review the originating settings files
- Isolate risky operations in containers/VMs
**❌ Don’t**
- Load an entire monorepo when you only need a package
- Max out thinking/turn budgets for simple tasks
- Ignore session cleanup
**✅ Do**
- Use `--add-dir` for focused context
- Right‑size with `--max-turns` and `MAX_THINKING_TOKENS`
- Set `cleanupPeriodDays` to prune old sessions
Workflow
**❌ Don’t**
- Skip project context (`CLAUDE.md`)
- Use vague prompts
- Ignore errors/logs
- Automate without testing
**✅ Do**
- Maintain and update `CLAUDE.md`
- Be specific and goal‑oriented in prompts
- Monitor via logs/OTel as appropriate
- Test automation in safe environments first
---
Third-Party Integrations
Provider Setup Examples
Use provider setup examples when connecting Claude Code to Anthropic-compatible gateways or third-party model providers. The pattern is usually:
1. Install Claude Code.
2. Set the provider base URL and authentication token.
3. Select the provider model names Claude Code should use.
4. Launch `claude` and verify the session starts with the expected provider.
DeepSeek Integration
1. ###### Install Claude Code with the native installer
```bash
curl -fsSL https://claude.ai/install.sh | bash
```
2. ###### Configure the current DeepSeek Anthropic-compatible endpoint
```bash
export ANTHROPIC_BASE_URL=https://api.deepseek.com/anthropic
export ANTHROPIC_AUTH_TOKEN="$DEEPSEEK_API_KEY"
export ANTHROPIC_MODEL='deepseek-v4-pro[1m]'
export ANTHROPIC_DEFAULT_OPUS_MODEL='deepseek-v4-pro[1m]'
export ANTHROPIC_DEFAULT_SONNET_MODEL='deepseek-v4-pro[1m]'
export ANTHROPIC_DEFAULT_HAIKU_MODEL=deepseek-v4-flash
export CLAUDE_CODE_SUBAGENT_MODEL=deepseek-v4-flash
export CLAUDE_CODE_EFFORT_LEVEL=max
```
3. ###### Launch `claude`
The provider credentials and base URL select DeepSeek billing and disable Claude.ai subscription-only features for that process. `deepseek-chat` and `deepseek-reasoner` were retired in July 2026; use the current names above and re-check the [official DeepSeek Claude Code integration guide](https://api-docs.deepseek.com/quick_start/agent_integrations/claude_code/) before pinning them.