Claude Code

AI-powered coding agent in the terminal, built by Anthropic. Runs directly in your shell with full access to your codebase.

Official docs · GitHub

Install

1

$ npm install -g @anthropic-ai/claude-code

1
2
3
4
5

# macOS & Linux
$ curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
$ irm https://claude.ai/install.ps1 | iex

1

$ brew install --cask claude-code

Launch & authenticate

1

$ claude

On first launch, Claude Code opens a browser to authenticate via your claude.ai account (Pro or Max plan). Manage the session later with /login and /logout.

Alternatively, set ANTHROPIC_API_KEY to use the API directly (pay-as-you-go):

1
2

$ export ANTHROPIC_API_KEY="sk-ant-..."
$ claude

For CI or scripts that can't open a browser, generate a long-lived token:

1

$ claude setup-token

Keyboard shortcuts

Slash commands

Session & context

Model & workflow

Config & extend

Utilities

Extended thinking

Ask Claude to reason harder before acting by including a thinking keyword in your prompt. This allocates a larger reasoning budget — useful for architecture decisions, tricky debugging or multi-step planning.

1
2
3

Think about how to make this service resilient to a Postgres failover, then propose a design.

ultrathink about the race condition in the worker pool before touching anything.

Roughly ascending budget: think → think hard → think harder → ultrathink. Keep it off for routine edits — it costs tokens and time.

Non-interactive mode

Run a single prompt from the command line (useful for scripts and CI):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

# Print mode — output goes to stdout
$ claude -p "Explain the use of context in Go"

# Pipe input
$ cat error.log | claude -p "What does this error mean?"

# With a specific model
$ claude -p "Summarize this file" --model claude-opus-4-8 @src/main.py

# Machine-readable output (useful in CI)
$ claude -p "List the exported functions" --output-format json

# Continue the most recent conversation non-interactively
$ claude -p --continue "Now add tests for that function"

Useful flags

CLI subcommands

1
2
3
4
5
6

$ claude update                # Update to the latest version
$ claude doctor                # Diagnose the installation
$ claude config               # Read / write settings from the shell
$ claude mcp list              # Manage MCP servers (see below)
$ claude migrate-installer     # Move from the npm install to the native binary
$ claude --version             # Print the version

File references

Use @ to include file contents directly in your prompt:

1
2
3

What does this function do? @src/auth/login.py

Refactor @src/api/routes.ts to use async/await

Supports glob patterns, and — when MCP servers expose resources — @server:resource mentions:

1

Review all test files @tests/**/*.test.ts

Custom instructions (CLAUDE.md)

Claude Code reads instructions from CLAUDE.md files, loaded from your home directory down to the working directory (later files take precedence):

1. Enterprise policy — a system-managed file (IT-deployed)
2. User — ~/.claude/CLAUDE.md (applies to every project)
3. Parent directories — walking up from the project
4. Project — ./CLAUDE.md at the repo root (commit it to share)
5. Local — ./CLAUDE.local.md (personal, gitignore it)

Generate the project file with /init, or let Claude add entries on the fly with #.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16

# Project conventions

- Format Python with ruff; never leave unused imports
- Run pytest before every commit
- Prefer explicit error handling over bare except

# Commands

- Build: `make build`
- Test: `poetry run pytest`
- Lint: `ruff check .`

# Imports

@docs/architecture.md
@~/.claude/my-personal-style.md

@path imports pull another file's contents into the instructions (up to 5 levels deep) — handy for sharing a common style file across repos.

Custom commands

Drop a Markdown file in .claude/commands/ (project) or ~/.claude/commands/ (global) to create a reusable slash command. The filename becomes the command name.

1
2
3
4
5
6
7
8
9

<!-- .claude/commands/fix-issue.md -->
---
argument-hint: <issue-number>
description: Reproduce, fix and test a GitHub issue
allowed-tools: Bash(git*), Edit, Read
---

Find and fix issue #$1. Write a test that reproduces it,
then implement the fix and run the test suite.

1

/fix-issue 1234

Inside a command you can use $ARGUMENTS (everything passed), positional $1 / $2, embed shell output with !`command`, and reference files with @path.

Skills

Skills package a repeatable workflow, checklist or reference so Claude can pull it in exactly when it's relevant. A skill is a folder with a SKILL.md describing when and how to use it, plus any supporting scripts or files.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!-- .claude/skills/pytest-fix/SKILL.md -->
---
name: pytest-fix
description: Run the test suite and fix failures one by one. Use when tests are red.
allowed-tools: Bash, Read, Edit
---

1. Run `poetry run pytest -x` to stop at the first failure.
2. Read the traceback, locate the cause, apply a minimal fix.
3. Re-run until green. Never delete a test to make it pass.

Skills live in .claude/skills/ (project) or ~/.claude/skills/ (global). Claude invokes a skill automatically when your request matches its description, or you can trigger it explicitly with /skill-name.

Subagents

Subagents are specialised assistants with their own prompt, tools, and context window — useful for delegating focused tasks (code review, debugging, research) without polluting the main conversation. Manage them with /agents, or define one as Markdown with YAML frontmatter:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

<!-- .claude/agents/reviewer.md -->
---
name: reviewer
description: Reviews code for bugs and style issues
tools: Read, Grep, Glob
model: haiku
---

You are a meticulous code reviewer. Focus on correctness,
edge cases, and adherence to the project's conventions.

The optional model field lets a subagent run on a cheaper/faster model than the main session. Claude delegates to a subagent automatically when the task fits its description, or you can ask for it by name.

Output styles

Change how Claude formats its responses without touching the underlying behaviour:

Switch with /output-style, or set a default in settings: "outputStyle": "explanatory".

Plugins

Plugins bundle skills, subagents, commands, hooks and MCP servers into one installable package, distributed through marketplaces (a Git repo or URL).

1
2
3

# Add a marketplace, then install from it
$ claude plugin marketplace add anthropics/claude-code
$ claude plugin install <name>@<marketplace>

Manage everything interactively with /plugin. Enabled plugins are recorded in settings under enabledPlugins, so a project can ship a curated toolset to the whole team.

Permissions

Claude Code asks before writing files or running commands. You can adjust this per session:

Persist rules in settings under permissions, using tool-specific matchers:

1
2
3
4
5
6
7

{
  "permissions": {
    "allow": ["Bash(poetry run pytest:*)", "Read(~/.config/**)"],
    "ask":   ["Bash(git push:*)"],
    "deny":  ["Read(.env)", "Bash(rm -rf:*)"]
  }
}

Permission modes

Press Shift+Tab to cycle between modes during a session:

Plan mode is ideal for "explore → plan → implement" workflows on anything non-trivial. Start a session straight in a mode with claude --permission-mode plan.

Hooks

Hooks are shell commands that run automatically at key points in the Claude Code lifecycle. Define them in ~/.claude/settings.json (global) or .claude/settings.json (project).

Each hook receives a JSON payload on stdin (containing the tool name, tool input, etc.) — parse it with jq. The environment variable $CLAUDE_PROJECT_DIR points at the project root.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '\"Claude is about to run: \" + .tool_input.command'"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs -r ruff format 2>/dev/null || true"
          }
        ]
      }
    ]
  }
}

A hook can also influence the flow by returning JSON on stdout (e.g. {"decision": "block", "reason": "..."} to stop a tool call and feed a message back to Claude) or via its exit code — exit 2 blocks and surfaces stderr to Claude; any other non-zero exit is a non-blocking error.

Hook events

Hook matchers

The matcher field is a regex matched against the tool name:

MCP servers

Claude Code supports Model Context Protocol servers for extending available tools (and exposing resources you can @-mention).

The quickest way to add one is the claude mcp add command, which writes the config for you:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

# Local stdio server (scoped to you, on this machine)
$ claude mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem /projects

# Project-scoped server, shared with the team via .mcp.json
$ claude mcp add --scope project github \
    --env GITHUB_PERSONAL_ACCESS_TOKEN=<token> \
    -- npx -y @modelcontextprotocol/server-github

# A remote HTTP/SSE server
$ claude mcp add --transport http linear https://mcp.linear.app/mcp

$ claude mcp list      # list configured servers

Project-scoped servers are stored in a .mcp.json file at the repo root (commit it to share with the team):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "<token>"
      }
    }
  }
}

Manage and inspect servers at runtime with the /mcp slash command.

Configuration

Settings are stored in ~/.claude/settings.json (global) or .claude/settings.json (project-level). A settings.local.json holds personal, gitignored overrides.

1
2
3
4
5
6

{
  "model": "claude-sonnet-4-6",
  "theme": "dark",
  "includeCoAuthoredBy": true,
  "cleanupPeriodDays": 30
}

Key settings

Background tasks

Long-running commands (dev servers, test watchers, builds) can run in the background so the session stays interactive. Press Ctrl+B while a command runs to detach it; Claude keeps a handle on its output and can check on it, read logs, or kill it later. Useful when you want Claude to start poetry run uvicorn and then keep working against the running server.

Workflow: explore → plan → implement

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

# 1. Read the codebase without writing anything
Read the authentication module and tell me how sessions are managed.
Don't make any changes yet.

# 2. Plan
How would you add OAuth2 with Google? What files would need to change?

# 3. Implement
Go ahead and implement the plan.

# 4. Verify
Run the tests and fix any failures.

# 5. Commit
Commit these changes with a descriptive message.

Multi-agent with git worktrees

Run multiple independent Claude Code sessions in parallel using git worktrees:

1
2
3
4
5
6
7

# Create worktrees for parallel tasks
$ git worktree add ../feature-auth -b feature/auth
$ git worktree add ../feature-api -b feature/api

# Launch agents in each
$ cd ../feature-auth && claude
$ cd ../feature-api && claude    # in another terminal

Tips & recommended patterns

A few habits that pay off, especially on a Python/backend + CI workflow:

• Give it a CLAUDE.md early. Pin the package manager (Poetry), the test command, the linter (ruff), and any project quirks. It stops Claude from guessing on every session. Run /init to bootstrap it.
• Auto-format on write. A PostToolUse hook running ruff format / ruff check --fix on Write|Edit keeps the diff clean without you asking.
• Plan mode for anything multi-file. Migrations, refactors touching many modules, a new endpoint across schema + service + tests — let it lay out the approach first (Shift+Tab), review, then let it build.
• Package repeatable reviews as skills. You already lean on skills (SonarQube review, schema building). Anything you re-explain more than twice — a review checklist, a project scaffold, a release procedure — belongs in a SKILL.md.
• Use the built-in review commands before pushing. /code-review for bugs, /security-review for vulnerabilities, /verify to actually run the change end-to-end (not just the tests).
• Restrict a review subagent to read-only tools (Read, Grep, Glob) and put it on haiku — cheap, fast, and it can't accidentally edit anything.
• Wire it into CI / git hooks. claude -p "..." --output-format json in a pipeline, or a pre-commit hook that asks Claude to sanity-check the staged diff.
• Add the GitHub MCP server so Claude can read issues and PRs directly instead of you pasting them.
• Manage context deliberately. /clear between unrelated tasks, /compact when a long session gets sluggish, /context to see what's eating the window.
• Reach for ultrathink on genuinely hard design or debugging problems — and skip it for routine edits, since it costs tokens and time.

Update

1
2
3

$ claude update
# or, if installed via npm
$ npm update -g @anthropic-ai/claude-code