Claude code getting started requires nothing more than a Node runtime and an Anthropic API key, but the productive setup involves a few deliberate choices. This tutorial takes you from an empty terminal to running autonomous coding sessions that edit files, run tests, and commit changes inside a git repo you control.
Prerequisites
Before you touch the CLI, confirm these are in place:
- Node.js 18 or newer (
node --versionshould print v18.x or higher) - npm 9+ or pnpm 8+
- An Anthropic API key with available credit (export as
ANTHROPIC_API_KEY) - A local git repository you can trash—use a scratch dir, not your prod codebase
- Familiarity with bash, git, and your editor of choice
If you plan to route through a proxy that speaks the Anthropic protocol, set ANTHROPIC_BASE_URL before launching. Most OpenAI-compatible gateways need a translation layer; the CLI sends Anthropic-formatted messages.
Install the CLI
Anthropic ships the tool as an npm package. Install globally:
npm install -g @anthropic-ai/claude-codeVerify the binary and version:
claude --version
# Expected: claude-code 0.2.14 (or newer)If you see a permission error on macOS or Linux, fix the npm prefix rather than using sudo blindly:
npm config set prefix ~/.local
export PATH="$HOME/.local/bin:$PATH"Re-run the install. The binary should now resolve.
Configure authentication
The CLI reads ANTHROPIC_API_KEY from the environment. Export it in your shell profile or per-session:
export ANTHROPIC_API_KEY="sk-ant-..."For persistent config, Claude Code stores settings in ~/.claude.json. Inspect with:
claude config listExpected output is a JSON blob with apiKey redacted and default model set to a Sonnet variant. You can override the model per command with --model.
Set up a scratch project
Create an isolated workspace so the agent’s edits never surprise you:
mkdir -p ~/scratch/claude-demo && cd ~/scratch/claude-demo
git init -q
echo "print('hello')" > main.py
git add . && git commit -qm "initial"Launch the interactive REPL to confirm connectivity:
claudeYou’ll see a banner:
╭──────────────────────────────────────────────╮
│ Claude Code — type /help for commands │
╰──────────────────────────────────────────────╯
>Type /exit to quit. Interactive mode is good for poking around but poor for reproducible runs.
Run your first non-interactive task
Print mode (-p) lets you pipe prompts from shell scripts. Ask Claude to add a function and a test:
claude -p "Add a Python function that reverses a string and write a unit test in test_main.py" \
--allowed-tools Bash,Write,Edit \
--model claude-3-5-sonnet-latestThe agent plans, edits files, and returns a summary. Trimmed output:
I added reverse_string() to main.py and created test_main.py.
Running pytest...
2 passed in 0.31sCheck the diff:
git diff --stat
# main.py | 5 +++++
# test_main.py | 8 ++++++++This loop—prompt, observe, verify with git and tests—is the essence of claude code getting started.
Restrict tools for safety
Claude Code can run arbitrary bash, edit files, and fetch URLs. In shared environments, lock it down. The --allowed-tools flag takes a comma-separated list. To forbid network and only permit file edits:
claude -p "Refactor reverse_string to handle Unicode" \
--allowed-tools Write,Edit \
--disallowed-tools Bash,WebFetchIf the task needs test execution, you must allow Bash. More autonomy equals larger blast radius; tune per task.
Automate a multi-step workflow
Wrap the CLI in a script to lint, format, and commit:
#!/usr/bin/env bash
set -euo pipefail
claude -p "Run ruff, fix all lint errors, then format with black" \
--allowed-tools Bash,Edit \
--model claude-3-5-sonnet-latest
git add -A
git commit -qm "style: automated fixes via Claude"Run it:
chmod +x autofix.sh
./autofix.sh
git log --oneline -1
# abc1234 style: automated fixes via ClaudeThe agent executed ruff and black because we permitted Bash. Without that, it would edit blindly.
Use JSON output for parsing
For pipeline integration, request structured output:
claude -p "List the public functions in main.py" \
--output-format json \
--allowed-tools ReadResponse shape:
{
"result": "reverse_string",
"tools_used": ["Read"],
"cost_usd": 0.0021
}Pipe through jq to drive next steps.
Interactive REPL essentials
Session management
Use /clear to wipe context between unrelated tasks. /history shows prior prompts in the session.
Code review
Type /review to diff against your base branch and get suggestions:
> /review
Diff against main: +45 -2
Suggested: extract helper, add edge-case testCommitting
/commit stages changes and writes a conventional commit message. Review the message before pushing.
Worktree isolation for parallel agents
Running two Claude sessions on the same checkout causes conflicts. Use git worktrees:
git worktree add ../claude-task-1 -b task-1
cd ../claude-task-1
claude -p "Implement feature X" --allowed-tools Bash,Write,EditEach agent works on an isolated branch. Merge after review. This pattern scales to many concurrent experiments.
Scripting in CI
A minimal GitHub Actions step that fails if the agent breaks lint:
- name: Claude autofix
run: |
claude -p "Fix lint errors" --allowed-tools Bash,Edit --disallowed-tools WebFetch
ruff check .If ruff fails, the job fails. Keep agents out of protected branches.
Common pitfalls
Token blowups: Long conversations accumulate context. Start a fresh process per task.
Hidden state: The CLI caches project memory in .claude/. Delete that dir if behavior feels stale.
Model mismatch: Sonnet is cheaper for mechanical edits; Opus reasons better for architecture. Pass --model explicitly.
Unverified edits: Always run git diff and your test suite. The agent is not CI.
Path traps: Relative paths in prompts resolve to the current working directory. Pass absolute paths when scripting.
Where to go next
Claude code getting started is the first hour. For real work, wrap the CLI in Makefiles, enforce tool allow-lists, and review every diff. If you need cross-model metering, a gateway that forwards provider cache-control hints and meters per token can sit in front, but the local loop here ships changes today.
Practice on a throwaway repo until prompts are trustworthy. Then delegate the boring refactors and keep your review sharp.