Claude Code Tutorial: Install, Login, CLAUDE.md, Permission Modes and Common Commands

Step 1

Choosing an install route

Every route installs the same native binary. They differ in auto-update, whether Node.js is needed, and which interface you work in.

Older tutorials tell you to install Node.js first. Today only the npm route needs Node.js 22 or later; on an older Node, npm prints an EBADENGINE warning and the install still completes.

On shared home directories (NFS, common on HPC clusters), a running session keeps reading the executable. An in-place npm upgrade on another node deletes the old binary, and the running session exits with Bus error. On clusters, install the binary on local disk, or set DISABLE_UPDATES and let the admin upgrade centrally. An older bug where Claude Code exited immediately on SLURM compute nodes was fixed in 2.1.76 (GitHub #12507).

# macOS / Linux / WSL: native install (recommended, updates in the background)
curl -fsSL https://claude.ai/install.sh | bash
# Stable channel: about one week behind latest, skips releases with major regressions
curl -fsSL https://claude.ai/install.sh | bash -s stable

# Windows PowerShell (prompt starts with PS)
irm https://claude.ai/install.ps1 | iex
# Windows CMD (prompt without PS)
curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

# Package managers (no auto-update)
brew install --cask claude-code          # stable channel; claude-code@latest follows latest
winget install Anthropic.ClaudeCode

# npm (requires Node.js 22+; do not use sudo)
npm install -g @anthropic-ai/claude-code
npm install -g @anthropic-ai/claude-code@latest   # use this to upgrade, not npm update -g

# Verify
claude --version     # tested on this page: 2.1.296 (Claude Code)
claude doctor        # read-only diagnostics: install method, auto-update, settings validation

Windows

Windows: native or WSL

Use native Windows when your projects and tools live on Windows. Use WSL 2 when you depend on a Linux toolchain (conda, gcc, HPC scripts) or need the sandbox.

Step 2

Login: subscription, API key and third-party platforms

The first run of claude opens a browser login. When several credentials exist, Claude Code picks one in a fixed order; /status shows which one is active.

Credential precedence from high to low: cloud provider variables (CLAUDE_CODE_USE_BEDROCK and others), ANTHROPIC_AUTH_TOKEN, ANTHROPIC_API_KEY, an apiKeyHelper script, CLAUDE_CODE_OAUTH_TOKEN, browser login. A subscriber with a stale ANTHROPIC_API_KEY left in the shell sees a successful login followed by authentication errors on requests; unset ANTHROPIC_API_KEY and confirm with /status that the subscription is active again.

Login credentials are stored in the macOS Keychain, and in ~/.claude/.credentials.json on Linux and Windows. To use two accounts on one machine, separate them with CLAUDE_CONFIG_DIR, for example alias claude-lab='CLAUDE_CONFIG_DIR=~/.claude-lab claude'.

After upgrading your plan on claude.ai, the token in an existing session still reflects the old plan, and choosing Opus reports not available with the Claude Pro plan; run /logout and then /login.

Use in China

ANTHROPIC_BASE_URL and other variables in settings.json

For choosing an approach in mainland China (official subscription, relay, domestic models, cloud environment), see the comparison page How to use Codex and Claude Code in China. This section covers operations only: where the variables go, how to verify them and how to debug errors.

The model set in ANTHROPIC_DEFAULT_HAIKU_MODEL also runs background tasks such as session titles and summaries. Many relay tutorials point it at the retired claude-3-5 series, and background requests then fail repeatedly; point it at a model the gateway currently serves.

When the same variable is set both in the shell and in the env block of settings.json, settings.json wins. CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1 also turns off auto-updates, so run claude update manually from time to time.

# Export the two variables in your shell, then verify the URL and credential with a 1-token request
export ANTHROPIC_BASE_URL=https://gateway.example.com
export ANTHROPIC_AUTH_TOKEN=sk-xxxx
curl -sS -w '\n%{http_code}\n' -X POST "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "Authorization: Bearer $ANTHROPIC_AUTH_TOKEN" \
  -H "anthropic-version: 2023-06-01" -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-4-6","max_tokens":1,"messages":[{"role":"user","content":"."}]}'
# {"id":"msg_... means it works; an "unknown model" error also proves the URL and credential are valid;
# 401 means switch to the x-api-key header and ANTHROPIC_API_KEY
# Inside claude, run /status and confirm the Anthropic base URL and Auth token lines

{
  "env": {
    "ANTHROPIC_BASE_URL": "https://gateway.example.com",
    "ANTHROPIC_AUTH_TOKEN": "sk-xxxx",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "model-name-from-your-gateway",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "small-model-name-from-your-gateway",
    "CLAUDE_CODE_MAX_CONTEXT_TOKENS": "128000",
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1",
    "API_TIMEOUT_MS": "600000"
  }
}

Pricing

Pricing and usage: subscription or API

Choose a subscription if you use it several hours a day. Choose the API for occasional use, scripts and CI, or when you need exact accounting. Prices below are the official public prices on 2026-10-10 (USD, before tax).

Step 3

CLAUDE.md: levels, loading rules and a research project example

CLAUDE.md is an instruction file read at the start of each session. It shapes how Claude works; it does not limit what Claude can do. Limits that must hold go in permission rules or hooks.

# Project: differential expression analysis of single-cell data

## Directory conventions
- data/raw/: raw data, read-only. Do not modify, move or delete, and do not unpack or sort in place.
- data/processed/: generated from raw by scripts in scripts/; can be deleted and rebuilt at any time.
- scripts/: every analysis step, numbered 01_, 02_, each runnable on its own.
- results/: figures and tables, file names prefixed with the script number, e.g. 03_volcano.pdf.
- logs/: one log per run, file names with a timestamp.

## Environment
- Use the conda environment scrna-2026 (versions pinned in environment.yml). Ask me before installing packages.
- Run scripts as: python scripts/<name>.py 2>&1 | tee logs/$(date +%Y%m%d-%H%M%S)-<name>.log

## Reproducibility
- Fix seed=20261010 for every random process and record it in the result table metadata.
- Every number in the results must be regenerable by a script in scripts/; no hand calculation in chat.
- When an analysis parameter changes, update the parameter table and the reason in docs/params.md.

## Statistics
- Differential expression: Wilcoxon test, BH correction, padj < 0.05 and |log2FC| > 1.
- Sample information comes from data/raw/metadata.csv; keep group names as they are.

## Long jobs
- Commands expected to run longer than 5 minutes run in the background with nohup and write a log; report progress by reading the log.

<!-- Maintainer note: this HTML comment does not enter Claude's context -->
See @docs/params.md for current parameters.

Step 4

Permission modes and allow / deny rules

The permission mode decides which actions run without asking you; rules in settings.json allow or block specific actions on top of the mode. Deny rules apply in every mode, including bypassPermissions.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(python scripts/*)",
      "Bash(Rscript scripts/*)",
      "Bash(git diff *)",
      "Bash(git status)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(pip install *)",
      "Bash(conda install *)"
    ],
    "deny": [
      "Edit(data/raw/**)",
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  },
  "env": { "BASH_DEFAULT_TIMEOUT_MS": "600000" },
  "cleanupPeriodDays": 365
}

# Make raw data read-only at the OS level (tested on this page: Python appends then raise
# PermissionError and rm -f returns Permission denied)
chmod -R a-w data/raw
# Lift it yourself when raw data must be updated
chmod -R u+w data/raw

Commands

Common slash commands and shortcuts

Commands from older tutorials that no longer work: claude config set was deprecated in 1.0.7 and removed in 2.0.0; edit settings.json or use /config instead (tested on this page: 2.1.296 lists no config subcommand). The # prefix for quick memory entries was removed in 2.0.70. /vim was removed in 2.1.92; set Editor mode in /config. npm update -g may stay on an old version; upgrade with npm install -g @anthropic-ai/claude-code@latest.

Extensions

Subagents, hooks, skills and MCP

Each has a different job: a subagent completes one kind of task in its own context; a hook runs a shell command at a fixed point, independent of the model's judgment; a skill is a procedure loaded on demand; MCP connects external tools and data.

---
name: stats-reviewer
description: Reviews analysis scripts and result tables for statistical errors. Use after an analysis script changes or before results go into a figure or manuscript.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You are a statistical methods reviewer. Check that sample sizes and groups match data/raw/metadata.csv,
that multiple comparisons are corrected, that random seeds are fixed, and that every number in the result
tables can be regenerated by a script in scripts/. Report problems with evidence only; do not modify files.

#!/bin/bash
# .claude/hooks/protect-raw.sh: block Edit/Write calls that target data/raw/
# Exit code 2 blocks the call; stderr is sent back to Claude as the reason
INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"
if [[ "$FILE_PATH" == *"/data/raw/"* ]]; then
  echo "Blocked: $FILE_PATH is raw data (read-only). Write to data/processed/ or results/." >&2
  exit 2
fi
exit 0

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-raw.sh" }
        ]
      }
    ]
  }
}

---
name: run-analysis
description: Run one analysis script reproducibly and log the environment. Use when the user asks to run or rerun an analysis.
disable-model-invocation: true
---

1. Record `git rev-parse --short HEAD`, `python --version` and `conda env export --no-builds` in logs/.
2. Run `python scripts/$ARGUMENTS 2>&1 | tee logs/$(date +%Y%m%d-%H%M%S)-run.log`.
3. Report output file paths and key numbers. Do not modify data/raw/.

# Add an MCP server (local scope by default: only you, only this project; stored in ~/.claude.json)
claude mcp add --transport http sentry https://mcp.sentry.dev/mcp
claude mcp add my-db -e DB_URL=postgres://... -- npx -y some-db-mcp
# Share with your group: written to .mcp.json at the project root (teammates approve it on first run)
claude mcp add --scope project zotero -- npx -y zotero-mcp
claude mcp list            # unapproved .mcp.json servers show as Pending approval
# Check agent and skill file format (tested on this page: a missing description only gives a warning,
# but the agent is skipped at runtime)
claude plugin validate .claude/agents

Scripts and sessions

Non-interactive claude -p and resuming sessions

# One run, result as JSON so a script can read result, session_id and total_cost_usd
claude -p "Read results/03_de_genes.csv and list the 20 genes with the smallest padj and their log2FC" \
  --output-format json --permission-mode dontAsk --allowedTools "Read" \
  --max-turns 5 --max-budget-usd 0.50 < /dev/null > logs/summary.json
jq -r '.result' logs/summary.json

# Batch: one independent run per sample; a non-zero exit code marks failure
for s in S01 S02 S03; do
  claude -p "Check cell count, gene count and mitochondrial fraction in data/processed/$s.h5ad and write a QC summary" \
    --permission-mode dontAsk --allowedTools "Read" "Bash(python scripts/qc_summary.py *)" \
    < /dev/null > logs/qc-$s.md || echo "$s failed" >> logs/failed.txt
done

# Resume sessions
claude --continue                 # most recent interactive session in this directory
claude --resume                   # open the session picker (Ctrl+A shows every project on this machine)
claude --resume de-analysis       # resume by name (name it in-session with /rename de-analysis)
claude -p --resume <session-id> "Summarize which parameters changed" --output-format json | jq -r '.result'

Context

Managing context: /context, /compact and large files

1. 01

   Check usage first

   /context shows how much the system prompt, Memory files, MCP tools and the conversation each take. If a large share is used at startup, trim CLAUDE.md, skills or MCP servers.

2. 02

   /clear when you switch tasks

   Old conversation unrelated to the current task is billed again on every request. Before switching, name the session with /rename, then /clear. /clear costs nothing; /compact reads the whole conversation, so on a large context it is itself a large request.

3. 03

   Say what to keep when compacting

   For example, /compact keep the parameter table, the last error and the unfinished steps. You can also add a # Compact instructions section to CLAUDE.md. /autocompact 300000 makes automatic compaction trigger earlier.

4. 04

   Do not read whole data files

   Have Claude inspect structure with head, wc -l, pandas nrows or df.info() instead of reading a whole CSV. A very large output can trigger Autocompact is thrashing: context refills right after compaction and Claude Code stops retrying. Read in chunks, or hand large-file processing to a subagent so it happens in a separate context.

5. 05

   Command output limits

   By default only about 30,000 characters of Bash output enter context inline; the rest is saved to a file that Claude reads on demand. Failed commands keep a head-and-tail excerpt of about 10,000 characters. grep or tail long logs before handing them to Claude.

Research practice

Research code and data analysis: long jobs, records and cost

Research work runs long, raw data cannot be regenerated, and results must be reproducible. The practices below address these three points.

# Have Claude start long jobs this way: the job is independent of Claude's process and logs to disk
nohup python scripts/05_train.py --config configs/run3.yaml \
  > logs/run3-$(date +%Y%m%d-%H%M).log 2>&1 &
echo $! > logs/run3.pid
# On HPC, submit to the scheduler instead of running on the login node
sbatch scripts/05_train.slurm
# Then have Claude read tail -n 50 logs/run3-*.log to report progress instead of waiting in the foreground

1. 01

   Confirm the approach in plan mode

   Before changing an analysis pipeline, press Shift+Tab into plan mode or prefix the prompt with /plan. Claude only reads files and writes a plan; edit the plan in your editor with Ctrl+G and approve it before execution. The plan file is re-injected from disk after compaction, so it works as the outline of a long task.

2. 02

   Keep long jobs outside Claude's process

   Foreground Bash commands time out after 2 minutes by default, 10 minutes at most, and then move to the background. Background commands in a local interactive session have no time limit, but in claude -p they stop after 10 minutes by default and 2 hours at most. Start model training or molecular simulations with nohup or sbatch, write logs to files, and have Claude read the logs to report progress.

3. 03

   Activate the environment before starting claude

   Each Bash command runs in a separate process and variables set with export do not carry over to the next command, so a conda activate that Claude runs mid-session only lasts for that one command. Run conda activate first, then claude; for extra variables, point CLAUDE_ENV_FILE at a setup script.

4. 04

   Keep a record of the work

   Transcripts are stored as JSONL under ~/.claude/projects/<directory name>/ and deleted silently after 30 days by default. For projects that need an archive, raise cleanupPeriodDays in settings.json (for example 365), export key sessions with /export, and commit them with the run logs in logs/.

5. 05

   Make results reproducible

   In CLAUDE.md, require that every number comes from a script, that random seeds are fixed, and that parameter changes go into a parameter table. Fix the run procedure in a skill (record the git commit and conda env export). Before delivery, have a subagent such as stats-reviewer review the work separately.

6. 06

   Control cost

   Configure the status line to show context usage and cost (/statusline). Use Sonnet day to day and switch to Opus for complex planning; give simple subagents model: haiku. Start a new session for each independent question, since a long session bills even a one-line question against the whole context. Add --max-budget-usd to batches.

Chinese community

Experience from the Chinese community, and what to correct

These items come from hands-on posts on CSDN and the Alibaba Cloud developer community. Each was checked against the official docs or tests on this page, with its conditions and corrections noted.

Errors

Common errors and fixes

Debug order: claude --version to confirm the version; claude doctor to check the install and settings files; /status in a session to confirm the account, gateway and loaded settings files; if still unclear, start with claude --debug and read the log under ~/.claude/debug/; if you suspect your own configuration, compare with claude --safe-mode.

Hand it to an agent

Hand this workflow to an agent

Example instruction: "This is my analysis repository. First browse the code and data/README.md read-only, write a CLAUDE.md and .claude/settings.json following the directory conventions on this page, and make data/raw read-only. Then rerun the differential expression analysis from raw counts using the pipeline in scripts/, run long steps in the background with logs, and deliver the result tables, figures and a record of parameters and environment."

Steps the agent takes: clones the repository in an isolated cloud computer and builds the environment from environment.yml; writes a plan first, then generates CLAUDE.md and the permission configuration; rents a GPU automatically when a step needs one, runs long steps in the background and reports from the logs; reviews the results adversarially, checking sample groups, multiple-comparison correction and random seeds.

Output files: CLAUDE.md, .claude/settings.json, a run log for each step, tables and figures in results/, and a reproduction note recording the git commit and conda environment. The task continues after you close your machine.

What you still need to check: whether the statistical method fits your experimental design, whether groups and covariates match the sample information, and whether thresholds and parameters match your group's earlier analyses.

Checklist

Checklist before starting a research project

• claude --version meets the version required by the features you rely on; on clusters the binary is on local disk
• /status shows the account or gateway you expect, with no stale ANTHROPIC_API_KEY
• The project root has a CLAUDE.md under 200 lines with directory conventions, run commands, random seeds and statistics conventions
• data/raw is chmod -R a-w, and settings.json has an Edit(data/raw/**) deny rule
• Actions that need confirmation (git push, installing dependencies) are ask rules; bypassPermissions is not used
• cleanupPeriodDays is raised, a logs/ directory exists, and key sessions are saved with /export
• Batch scripts use --permission-mode dontAsk, an --allowedTools allowlist, < /dev/null and --max-budget-usd, and claude has been run interactively once in that directory
• Long jobs start with nohup or sbatch, and Claude only reads their logs