The Claude Handbook

Claude is an AI assistant made by Anthropic. You type or speak a request in plain English. Claude writes, explains, plans, summarises, reads your files, and writes code.

Where you can use it

The Claude models

A model is the brain that writes the answer. Bigger models think harder. Smaller models answer faster.

You pick the model from a menu near the message box. If you're not sure, keep the default.

Claude has a free plan and several paid ones. Paid plans add Claude Code, Cowork, Research and much more usage. Prices below were checked on 23 Oct 2026; confirm them on claude.com/pricing before you buy.

How usage limits work

• A session limit that resets every five hours, and a weekly limit that resets once a week.
• What you use depends on the length of the chat, the files you attach, the features (Research uses more), the model and the effort level.
• To make your usage go further: start a new chat for a new topic, attach only the files you need, and use a lighter model for simple jobs.

Check your computer first: macOS 13 or newer, or Windows 10 (version 1809) or newer. A Linux version is in beta.

The Claude app is free to download on every plan. Your chats, projects, memory and settings sync between your phone, the desktop app and the web.

Or open claude.ai/mobile on your phone.

Worth trying on a phone

• Voice mode. Talk to Claude hands-free and hear it answer. Switch between voice and text in the same chat.
• Photos. Take a photo of a sign, a form or a whiteboard and ask about it.
• Dictation. Speak instead of typing a long prompt.
• Widgets and shortcuts. Start a chat from your home screen, or from iOS Shortcuts.

A good prompt has three parts. Say what you need, give the background, and say what the answer should look like. The weak prompt below has only the first part. The better prompt has all three.

Prompts to try today

• "Summarise this PDF in 5 bullets." (attach the file)
• "Make a weekly meal plan for two, as a table."
• "Explain this error message in simple words."
• "Ask me 5 questions, then write my cover letter."

Anthropic's own advice comes down to one idea: treat Claude like a brilliant new colleague who knows nothing about your situation. If a colleague would be confused by your request, Claude will be too.

Two more tricks

• Label the parts of a long prompt with tags such as <instructions>, <context> and <document>, so Claude knows which text is which.
• Steps in order: when the order matters, write the steps as a numbered list.

A project is a workspace for one piece of ongoing work, such as a course, a client or a book. It keeps its own chats, its own files and its own instructions, so you don't have to explain the background every time.

1. In the sidebar, open Projects and click New project. Give it a name.
2. Add project knowledge: upload the documents Claude should know, such as a style guide or a syllabus. Each file can be up to 30 MB.
3. Write project instructions, for example "Answer as a tutor for first-year students. Short answers, one example each."
4. Start chats inside the project. Every chat sees the files and follows the instructions.

An artifact is something Claude makes for you to use or show someone: a document, a slide deck, a chart, a diagram, a web page or a small working app. It opens in a panel beside the chat, where you can view it, change it and share it.

• Private first. An artifact is visible only to you until you share it. Sharing gives it its own link.
• AI-powered artifacts can use Claude themselves, so the people using them can ask questions or get feedback.
• Turn it on. Artifacts need Settings → Capabilities → Code execution and file creation.

Attach files

Drag files into the chat, or click +. Claude reads them and answers about them.

Web search

Claude can look things up and show its sources. Click + and turn on Web search. On Team and Enterprise, an owner must first allow it for the organisation.

Research

Research goes further: Claude runs many searches, each building on the last, decides what to look into next, and writes a report with sources. It can also search your connected tools, such as Google Drive. Turn it on with + → Research. It is on paid plans and uses your limits faster.

With memory on, Claude remembers useful things about you and your work from past chats, such as your job or how you like answers written. You can also tell it directly: "Remember that I teach year-9 science."

Incognito chats

For a chat you don't want kept, start a new chat and click the ghost icon. An incognito chat isn't saved to your history and isn't used for memory. Every plan has it.

On Free, Pro and Max, you choose whether your chats help train Claude. Team and Enterprise work differently.

Claude comes in three products, and each fits a different kind of work. Pick by what you want at the end, not by habit.

1. Claude app (chat). Web, desktop or phone. You steer every reply. Claude works only inside the chat unless you add connectors.
2. Claude Code. Reads your code, edits files and runs commands. Runs in a terminal, the desktop app's Code tab, VS Code, JetBrains or the web. The terminal is a hurdle if you've never used one. Paid plans only.
3. Cowork. A tab in the Claude desktop app (Mac and Windows), plus cloud sessions. You describe the outcome and review at the end, so give clear instructions and only the folders it needs. Paid plans only.

A frontier is the far edge of explored land. In AI, the frontier is the edge of what AI can do today. Frontier models are the newest, most capable models that sit at that edge, and each new release pushes the edge further out. Claude is one of several.

This table was checked on 14 Oct 2026, and these models change almost every month.

Open weights means anyone can download the model and run it on their own machines. Closed models run only through the company's app or API.

Claude Code is Claude for building software. Claude Code reads the files in a folder, edits them, and runs commands. Before risky steps, Claude Code asks you first.

You need: a Pro, Max, Team or Enterprise plan, 4 GB of memory or more, and an internet connection. The Free plan does not include Claude Code.

Open a terminal

Install

curl -fsSL https://claude.ai/install.sh | bash

irm https://claude.ai/install.ps1 | iex

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

Homebrew and WinGet work too: brew install --cask claude-code or winget install Anthropic.ClaudeCode.

Start and sign in

1. Go to a project folder: cd Documents/my-project
2. Type claude and press Enter.
3. A browser window opens. Sign in with your Claude account.
4. Back in the terminal, ask: "What does this project do?"

Commands worth knowing

Update and uninstall

The standard install updates itself. For Homebrew or WinGet, run brew upgrade claude-code or winget upgrade Anthropic.ClaudeCode. To uninstall on Mac or Linux:

rm -f ~/.local/bin/claude
rm -rf ~/.local/share/claude

The terminal is one way in. The same Claude Code also runs inside your code editor, in the desktop app, and in the browser. Pick the one that fits how you work.

All four need a paid plan. From a terminal, claude --cloud "fix the flaky login test" hands a task to a cloud session.

Claude Code works in a loop. Claude Code reads, plans, acts, and checks, and repeats until the task is done. You stay in charge of every risky step.

Three controls decide how Claude Code works on a task: effort (how hard Claude thinks), permission mode (how much it may do without asking) and the context window (how much it can hold in mind at once).

Effort levels

Effort sets how much Claude thinks on each step. More effort means deeper reasoning, but slower answers and more tokens used, so more of your plan's usage or a higher bill. Drag the slider to compare the levels.

The bars show the direction of each change. They are not measurements.

The default is medium on Opus 5.5, Sonnet 5.5 and Haiku 5.5, and high on most other models, including Fable 5.1. On these newer models thinking can't be switched off. Effort decides how much of it happens.

Permission modes

Press Shift+Tab to move through the modes. The current mode shows at the bottom of the screen.

The context window

The context window is Claude's working memory for one conversation. It holds your messages, the files Claude has read, command output, your CLAUDE.md and the one-line descriptions of your skills. When it fills up, older detail gets squeezed out.

Most good sessions follow the same shape: understand, plan, change, check, save. The diagram shows the loop. The table gives the prompts that start each common job.

1. Explore. Ask Claude to read the relevant code and explain it. No edits yet.
2. Plan. Switch to plan mode (Shift+Tab or /plan). Claude proposes the change. You read it and approve, or ask for changes.
3. Change. Claude edits the files. In default mode you approve each edit.
4. Check. Claude runs the tests or the app. If something fails, it goes back to step 3.
5. Save. Claude commits, and can open a pull request for review.

Claude Code works with git the way you would. Ask in plain words and it runs the commands, so you don't need to remember them.

Later, claude --from-pr 1234 finds the sessions that worked on pull request 1234.

Before each prompt you send, Claude Code takes a snapshot of the files it is about to change. If a change goes wrong, you can step back to any of those points.

1. Press Esc twice on an empty prompt, or type /rewind.
2. Pick the point in the conversation you want to go back to.
3. Choose what to restore: code and conversation, conversation only (keep the code), or code only (keep the chat).

You can run several Claude Code sessions at once, for example one building a feature while another fixes a bug. Each needs its own copy of the files, or they will edit over each other. A git worktree gives each session that copy.

claude --worktree feature-auth

claude -w fix-login

Three commands help you check Claude's work before anyone else sees it.

Claude Code's features stack in five layers. Each layer fixes a problem that a better prompt can't. The lower layers are the foundation, and each layer up gives you more control. Click a box to see its file, when it loads, and an example.

1. CLAUDE.md, the memory layer. Standing project rules and conventions. Loaded in full at the start of every session.
2. Skills, the knowledge layer. Steps, checklists and templates for a repeat job. Only the one-line description loads at the start. The full steps load when the task matches or you type /name.
3. Hooks, the guardrail layer. Your own script, run every time a set event happens, such as before or after a tool. A rule in CLAUDE.md is advice Claude may miss. A hook always runs.
4. Subagents, the delegation layer. A helper with its own context window and tool list. It does a side job and returns a summary. Subagents can start their own, up to three levels deep.
5. Plugins, the distribution layer. A bundle of skills, subagents, hooks and MCP servers. One install gives the whole team the same setup.
6. MCP servers. Not a layer of behaviour but the connection to the real world: issue trackers, web APIs, databases, files. Any layer can use the tools they add.

Claude Code reads its files from two places: ~/.claude/ in your home folder, and your project folder. Each file has a scope, meaning who it affects. Most people only ever edit CLAUDE.md and settings.json. The rest is optional.

When two settings files disagree

The same setting can appear in several settings.json files. Claude Code uses the value from the highest level that sets it.

1. Managed settings. Set by your organisation. Nothing you set can override them.
2. Command line. claude --settings '{...}' applies to that one session only.
3. Project local (.claude/settings.local.json). Your personal changes for this project.
4. Shared project (.claude/settings.json). The team's settings, committed to git.
5. User (~/.claude/settings.json). Your settings for every project.

CLAUDE.md is the briefing Claude reads at the start of every session. A good one is short, specific, and full of things Claude can't guess from the code.

# shop-api
Node 22, Express, Postgres. API handlers live in src/routes/.

## Commands
- Install: pnpm install
- Test: pnpm test (run before saying a task is done)
- Type check: pnpm tsc --noEmit

## Rules
- Use pnpm, never npm.
- Every new endpoint gets a test in tests/routes/.
- Never edit files in src/generated/.

@docs/architecture.md

Think of a skill as a recipe card. Without one, you explain the same job to Claude every time: which file to read, what headings to use, how long to make it. With a skill, you write those steps once, and Claude follows them whenever that job comes up.

A skill is a folder with one file in it, SKILL.md. The top of the file holds a name and a one-line description. The rest holds the steps.

---
name: weekly-report
description: Write my weekly status report. Use when I ask for a weekly update.
---
1. Read the notes in reports/notes.md.
2. Group the items under Done, In progress and Blocked.
3. Keep it under 200 words, in plain English.

Useful frontmatter

A skill can carry helper files, such as a script or a template, in its folder. Skills in ~/.claude/skills/ work in every project; skills in a project's .claude/skills/ work for everyone who opens it.

A subagent is a helper Claude hands a side job to. It works in its own context window with its own instructions and tools, then reports back a short summary. Your main conversation stays clean.

---
name: code-reviewer
description: Reviews changed code for bugs. Use proactively after any code change.
tools: Read, Grep, Glob
model: inherit
---
You are a careful reviewer. List real bugs only, each with its file and line.
Ignore style unless it hides a bug.

A hook is your own script that Claude Code runs at a set moment, every time, whatever Claude decides. Use hooks for rules that must never be skipped.

1. SessionStart. The session begins or resumes. Good for loading context, such as today's tickets.
2. UserPromptSubmit. You send a prompt, before Claude sees it. Can add context or block it.
3. PreToolUse. Claude is about to use a tool. Your script can block it, for example any edit to .env.
4. The tool runs. The edit, command or search happens.
5. PostToolUse. The tool finished. Good for running the formatter or the linter.
6. Stop. Claude has finished its answer. Good for a final check or a notification.

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

#!/bin/sh
# Claude Code sends details of the tool call as JSON on stdin
path=$(jq -r '.tool_input.file_path')
case "$path" in
  *.env|*.env.*) echo "Editing $path is not allowed" >&2; exit 2 ;;
esac
exit 0

Type /hooks to see the hooks that are set up.

Permission rules decide what Claude Code may do without asking. They live in settings.json under permissions, as three lists: allow, ask and deny.

{
  "permissions": {
    "allow": ["Bash(npm run test *)", "WebFetch(domain:docs.python.org)"],
    "ask":   ["Bash(git push *)"],
    "deny":  ["Read(./.env)", "Read(./secrets/**)", "Bash(curl *)"]
  }
}

Order: deny is checked first, then ask, then allow. A deny rule always wins, and an allow rule can't make an exception to it. Type /permissions to see and edit the rules.

Stay safe

• Treat what Claude reads as untrusted. A web page, issue or file can hide instructions aimed at the model. This is called prompt injection.
• Deny reads of secrets, such as .env files and key folders.
• Keep asking on for risky commands: pushes, deletes, deploys, anything that spends money.
• Use the sandbox. /sandbox limits which files and network addresses shell commands can reach (macOS, Linux and WSL2).
• Install only plugins and MCP servers you trust.

Out of the box, Claude only sees what you type or attach. A connector (in the apps) or an MCP server (in Claude Code) lets Claude read and act on a real tool, such as your Drive, GitHub or a database. Both use the same standard, called MCP. The Advanced section explains how MCP works inside.

In the Claude app

1. Open Settings → Connectors. Newer versions may label the menu Customize → Connectors.
2. Click Discover and pick a tool, such as Google Drive.
3. Click Connect and sign in to that tool in the browser window.
4. Ask: "Find last week's meeting notes in my Drive."

Tools not in the list can be added as a custom connector by pasting the MCP server's URL. Every paid plan can add custom connectors. On Team and Enterprise, the owners add connectors for the whole organisation.

In Claude Code

claude mcp add --transport http notion https://mcp.notion.com/mcp

claude mcp add db -- npx -y @bytebase/dbhub --dsn "postgresql://..."

Then type /mcp inside Claude Code to check the connection and sign in. claude mcp list shows every server you added.

{
  "mcpServers": {
    "notion": { "type": "http", "url": "https://mcp.notion.com/mcp" }
  }
}

A plugin's own description lives in .claude-plugin/plugin.json, with its name, version and description.

MCP (Model Context Protocol) is an open standard for connecting AI apps to tools and data. MCP has three roles.

What a server can offer

How the messages travel

Every message is JSON-RPC 2.0, a simple JSON format for requests and replies. Two transports carry the messages:

The current spec is dated 2026-07-28: modelcontextprotocol.io/specification.

A tool is a small JSON description. The server writes the description, and the model reads it to decide when and how to use the tool. A clear description matters as much as the code behind it.

{
  "name": "weather_current",
  "title": "Weather Information",
  "description": "Get current weather for any location worldwide",
  "inputSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string", "description": "City name or coordinates" },
      "units": { "type": "string", "enum": ["metric", "imperial"], "default": "metric" }
    },
    "required": ["location"]
  }
}

The two calls

{ "jsonrpc": "2.0", "id": 7, "method": "tools/call",
  "params": { "name": "weather_current", "arguments": { "location": "Pune" } } }

{ "jsonrpc": "2.0", "id": 7,
  "result": { "content": [ { "type": "text", "text": "24°C, cloudy" } ], "isError": false } }

tools/list asks a server for all its tool definitions. tools/call runs one tool. If the tool fails, the result carries "isError": true and a message the model can read.

Follow the numbers down the left. Solid arrows are requests. Dashed arrows are replies.

Where the server itself runs depends on how you connect. The three common setups:

Custom connectors sign in with OAuth. Claude supports dynamic client registration and token refresh, and redirects to https://claude.ai/api/mcp/auth_callback after sign-in.

An API is one service's own set of URLs and rules. MCP is one shared plug shape that any AI app can use for any tool. An MCP server usually calls a service's API underneath. So MCP does not replace APIs. MCP wraps APIs in a form AI apps can discover and use.

Tools in the Claude API, without MCP

The Claude API has its own tools parameter. The flow is the same as MCP: Claude replies with a tool_use block, your code runs the tool, and you send back a tool_result block. The only difference is that your code holds the tools, with no MCP server involved. The schema field is spelled input_schema in the API and inputSchema in MCP.

The Claude API lets your own code send messages to Claude. You need an API key from the Claude Console. API use is billed per token, separately from Claude app plans.

The models

Checked on 23 Oct 2026 against Anthropic's models page. Prices are US dollars per million tokens (MTok).

All four have a 1M-token context window and up to 128K tokens of output.

The call

curl https://api.anthropic.com/v1/messages \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model": "claude-opus-5-5", "max_tokens": 1024,
       "messages": [{"role": "user", "content": "Hello, Claude"}]}'

import anthropic

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY
msg = client.messages.create(
    model="claude-opus-5-5",
    max_tokens=1024,
    system="You answer in one short paragraph.",
    messages=[{"role": "user", "content": "What is a context window?"}],
)
print(msg.content[0].text)

Three API features cut cost or make answers easier to use in code.

Prompt caching

If every request starts with the same long text, such as a manual or a big system prompt, mark it for caching. Later requests read it from the cache at a fraction of the price.

"system": [{
  "type": "text",
  "text": "...a long product manual...",
  "cache_control": {"type": "ephemeral"}
}]

Message Batches

For work that doesn't need an answer right now, send up to 100,000 requests in one batch. Batches cost 50% less. Most finish within an hour, and every batch finishes within 24 hours. Good for evaluations, tagging and bulk summaries.

Structured outputs

When your code needs JSON, give the API a JSON Schema. The answer is guaranteed to match it, so you don't have to check and retry.

from pydantic import BaseModel

class Contact(BaseModel):
    name: str
    email: str

result = client.messages.parse(
    model="claude-opus-5-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Extract the contact: Asha Rao, asha@example.com"}],
    output_format=Contact,
)
print(result.parsed_output.email)

"Connecting your app to MCP" means one of two things. Pick the path that matches your goal.

Path 1. Let Claude use your app: build an MCP server

1. Write a server that wraps your app's actions as tools. The Python SDK keeps a small server very short:

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("weather")

@mcp.tool()
def weather_current(location: str) -> str:
    """Get current weather for a city."""
    # call your real API or database here
    return f"24°C, cloudy in {location}"

if __name__ == "__main__":
    mcp.run()  # stdio

The SDK turns the function name, the docstring and the type hints into the tool's name, description and inputSchema. A TypeScript SDK also exists: @modelcontextprotocol/sdk.

2. Test the server with the MCP Inspector, which lists your tools and lets you call them by hand.
3. Add the server to Claude Code: claude mcp add weather -- uv run server.py
4. To use the server in claude.ai, run it over Streamable HTTP on a public URL, add OAuth, and add the URL as a custom connector.

Path 2. Use Claude inside your app: call the API with tools

import anthropic
client = anthropic.Anthropic()

tools = [{
    "name": "weather_current",
    "description": "Get current weather for a city",
    "input_schema": {"type": "object",
                     "properties": {"location": {"type": "string"}},
                     "required": ["location"]}
}]

msg = client.messages.create(
    model="claude-sonnet-5-5", max_tokens=1024, tools=tools,
    messages=[{"role": "user", "content": "Weather in Pune?"}])

# msg.content holds a tool_use block. Run the tool yourself,
# or forward it to an MCP server with tools/call, then send
# the output back as a tool_result block in the next request.

To use existing MCP servers here, make your app an MCP client with the MCP SDK. Call tools/list, pass those tools to Claude, and turn each tool_use into a tools/call.

Claude Code can run without a chat window, inside scripts and CI jobs. On GitHub, you can mention @claude in an issue or pull request and it does the work there.

In a script

claude -p "Summarise what changed in the last 5 commits" --output-format json
cat build.log | claude -p "Why did this build fail?"

On GitHub

1. In Claude Code, run /install-github-app. It installs the GitHub app and adds the secret. It needs the GitHub CLI signed in.
2. A workflow file using anthropics/claude-code-action@v1 is added to .github/workflows/.
3. Comment "@claude fix the failing test" on a pull request. Claude works in the action and pushes its changes.

on:
  issue_comment:
    types: [created]
jobs:
  claude:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions: { contents: write, pull-requests: write, issues: write, id-token: write }
    steps:
      - uses: actions/checkout@v6
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}

The Claude Agent SDK gives your program the same engine Claude Code runs on: the agent loop, the built-in tools (read, edit, run commands, search), permissions, hooks, subagents and MCP. You write the program; the SDK does the agent work.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions

async def main():
    async for message in query(
        prompt="Find the bugs in utils.py and fix them",
        options=ClaudeAgentOptions(
            allowed_tools=["Read", "Edit", "Glob"],
            permission_mode="acceptEdits",
        ),
    ):
        print(message)

asyncio.run(main())

Security checklist for tools

• Give each server the smallest access that works, such as read-only tokens.
• Treat tool results as untrusted text. A web page or file can contain instructions aimed at the model.
• Keep approval on for tools that write, delete, send or pay.
• Install servers and plugins only from sources you trust.

CSCheat sheet

The essentials on one page, checked against the Claude Code docs on 23 Oct 2026. Print or save as PDF