Claude Code by Anthropic

Relevant source files

• Anthropic/Claude Code/Tools.json

Claude Code is Anthropic's tool-based AI coding assistant that orchestrates complex development tasks through specialized sub-agents and a comprehensive tool ecosystem. This system emphasizes task delegation via the Task tool for multi-step operations, structured file editing workflows, and plan mode for complex implementations. Claude Code integrates with the local filesystem and shell environment to provide IDE-integrated development assistance.

For other IDE-integrated systems, see VSCode Agent, Windsurf Cascade, and Amp. For web-based platforms, see Web-Based Development Platforms.

Sources: Anthropic/Claude Code/Tools.json1-509

Tool Architecture and Categories

Claude Code provides 16 distinct tools organized into four functional categories: file system interaction, orchestration and execution, specialized content, and workflow management. The architecture prioritizes read-before-write operations, exact string matching for edits, and sub-agent delegation for complex tasks.

Tool Ecosystem Overview

Tool Category Mapping

Category	Tools	Primary Use Case
File System Interaction	Read, Edit, MultiEdit, Write, NotebookEdit, LS	Reading and modifying local files
Orchestration & Execution	Task, Bash, BashOutput, KillBash, ExitPlanMode	Delegating complex tasks and running commands
Search & Discovery	Grep, Glob	Finding files and code patterns
External Resources	WebFetch, WebSearch, TodoWrite	Web access and task tracking

Sources: Anthropic/Claude Code/Tools.json1-509

Tool Selection Strategy

Claude Code follows a hierarchical tool selection pattern where the appropriate tool depends on task complexity and search precision requirements:

Sources: Anthropic/Claude Code/Tools.json3-29 Anthropic/Claude Code/Tools.json62-81 Anthropic/Claude Code/Tools.json83-148

Task Tool and Sub-agent Specialization

The Task tool is Claude Code's primary orchestration mechanism for delegating complex, multi-step operations to specialized sub-agents. Each sub-agent type has restricted tool access and operates autonomously to complete its assigned task.

Sub-agent Architecture

Task Tool Parameters

The Task tool requires three parameters for sub-agent invocation:

Parameter	Type	Description
description	string	Short 3-5 word task description
prompt	string	Detailed autonomous task instructions
subagent_type	string	Agent specialization: general-purpose, statusline-setup, or output-style-setup

Sources: Anthropic/Claude Code/Tools.json3-29

When to Use Task Tool

The Task tool should be used for:

1. Complex, multi-step tasks requiring autonomous execution
2. Searching for keywords/files when confident matches won't be found in first few tries
3. Research tasks combining file searches, reads, and web fetches
4. Tasks requiring multiple tool combinations that would take several turns

When NOT to Use Task Tool

Avoid using Task tool when:

1. Specific file path is known - use Read or Glob directly
2. Searching for specific class definition like "class Foo" - use Glob instead
3. Searching within specific file or 2-3 files - use Read tool directly
4. Simple, direct actions that can be completed with a single tool

Usage Pattern:

Sources: Anthropic/Claude Code/Tools.json3-29

Sub-agent Communication Model

Sub-agents are stateless and single-use:

• Each invocation returns exactly one final message
• Cannot send additional messages after initial report
• Prompt must contain complete autonomous instructions
• Must specify exactly what information to return
• Outputs should generally be trusted
• Prompt must clarify whether agent should write code or just research

Sources: Anthropic/Claude Code/Tools.json3-29

File Editing Operations

Claude Code enforces strict file editing workflows with mandatory read-before-write requirements and exact string matching. The system provides three editing tools for different use cases: Edit for single replacements, MultiEdit for sequential operations, and Write for new files or complete overwrites.

File Editing Workflow

Sources: Anthropic/Claude Code/Tools.json193-217 Anthropic/Claude Code/Tools.json219-250 Anthropic/Claude Code/Tools.json252-297 Anthropic/Claude Code/Tools.json299-321

Edit Tool - Single Exact String Replacement

The Edit tool performs exact string replacement in files with mandatory uniqueness checking.

Parameters:

Parameter	Type	Required	Description
file_path	string	Yes	Absolute path to file
old_string	string	Yes	Text to replace (must be unique)
new_string	string	Yes	Replacement text (must differ from old_string)
replace_all	boolean	No	Replace all occurrences (default: false)

Critical Requirements:

• Must use Read tool before editing (enforced with error)
• old_string must be unique in file unless replace_all=true
• Must preserve exact indentation from Read output (after line number prefix)
• Line number prefix format: spaces + line number + tab (exclude from match strings)
• No emojis unless user explicitly requests
• Prefer editing existing files over writing new ones

Sources: Anthropic/Claude Code/Tools.json219-250

MultiEdit Tool - Sequential Find-Replace Operations

The MultiEdit tool enables multiple edits to a single file in one atomic operation, with each edit operating on the result of the previous edit.

Parameters:

Parameter	Type	Required	Description
file_path	string	Yes	Absolute path to file
edits	array	Yes	Array of edit operations (min 1)

Edit Object Schema:

Field	Type	Required	Description
old_string	string	Yes	Text to replace
new_string	string	Yes	Replacement text
replace_all	boolean	No	Replace all occurrences (default: false)

Key Characteristics:

• Edits applied sequentially in array order
• Each edit operates on result of previous edit
• Atomic operation: all edits succeed or none applied
• All edits follow same requirements as Edit tool
• Preferred over multiple Edit calls for same file
• Can create new files: first edit with empty old_string, subsequent edits modify created content

Sources: Anthropic/Claude Code/Tools.json252-297

Write Tool - File Overwrite

The Write tool completely overwrites file contents or creates new files.

Parameters:

Parameter	Type	Required	Description
file_path	string	Yes	Absolute path to file
content	string	Yes	Complete file content

Constraints:

• For existing files, must Read first (enforced with error)
• ALWAYS prefer editing existing files over writing new ones
• NEVER proactively create documentation files (*.md, README) unless user explicitly requests
• No emojis unless user explicitly requests

Sources: Anthropic/Claude Code/Tools.json299-321

NotebookEdit Tool - Jupyter Notebook Cell Editing

The NotebookEdit tool modifies Jupyter notebook (.ipynb) cells with support for replace, insert, and delete operations.

Parameters:

Parameter	Type	Required	Description
notebook_path	string	Yes	Absolute path to .ipynb file
cell_id	string	Yes	Cell ID to edit/reference
new_source	string	Yes	New cell source content
cell_type	string	No	"code" or "markdown" (required for insert mode)
edit_mode	string	No	"replace" (default), "insert", or "delete"

Edit Modes:

• replace: Replaces cell content at cell_id
• insert: Inserts new cell after cell_id (or at beginning if cell_id not specified)
• delete: Deletes cell at cell_id

Sources: Anthropic/Claude Code/Tools.json322-365

Shell Command Execution

Claude Code provides persistent shell session management through the Bash tool with support for background execution, output monitoring, and shell lifecycle control. The system enforces specific patterns for git operations and GitHub interactions.

Shell Execution Architecture

Sources: Anthropic/Claude Code/Tools.json31-60 Anthropic/Claude Code/Tools.json467-488 Anthropic/Claude Code/Tools.json489-506

Bash Tool Parameters

Parameter	Type	Required	Description
command	string	Yes	Shell command to execute
timeout	number	No	Timeout in ms (default: 120000, max: 600000)
description	string	No	5-10 word description of command purpose
run_in_background	boolean	No	Execute in background (default: false)

Critical Requirements:

• Quote file paths with spaces: cd "path with spaces/file.txt"
• Use ; or && to separate commands (NO newlines except in quoted strings)
• Avoid cd - use absolute paths instead for better session maintenance
• MUST avoid search commands like find and grep - use Grep and Glob tools instead
• MUST avoid read tools like cat, head, tail, ls - use Read and LS tools instead
• If using grep, STOP and use rg (ripgrep) which is pre-installed
• Never use & at end when using run_in_background parameter

Sources: Anthropic/Claude Code/Tools.json31-60

Git Commit Workflow

When creating git commits, Claude Code follows a strict parallel execution pattern:

Commit Message Format (using HEREDOC):

Git Operation Constraints:

• NEVER update git config
• NEVER run additional commands beyond git commands
• NEVER use TodoWrite or Task tools during commits
• DO NOT push unless user explicitly requests
• NEVER use -i flag (interactive mode not supported)
• Do not create empty commits if no changes exist
• If pre-commit hook fails twice, it's preventing commit (do not retry further)

Sources: Anthropic/Claude Code/Tools.json31-60

GitHub Pull Request Workflow

Claude Code uses the gh CLI tool for all GitHub operations:

PR Body Format (using HEREDOC):

PR Constraints:

• NEVER update git config
• DO NOT use TodoWrite or Task tools
• Return PR URL when complete
• Use gh command for ALL GitHub operations (issues, PRs, checks, releases)

Other GitHub Operations:

Sources: Anthropic/Claude Code/Tools.json31-60

Background Shell Management

BashOutput Tool - Monitor background shell output:

Parameter	Type	Required	Description
bash_id	string	Yes	Background shell ID to monitor
filter	string	No	Regex to filter output lines

Returns only new output since last check. Filtered-out lines are permanently discarded.

KillBash Tool - Terminate background shell:

Parameter	Type	Required	Description
shell_id	string	Yes	Shell ID to terminate

Shell IDs can be found using the /bashes command.

Sources: Anthropic/Claude Code/Tools.json467-488 Anthropic/Claude Code/Tools.json489-506

TodoWrite Task Management System

The TodoWrite tool provides structured task tracking for coding sessions, enabling progress monitoring and demonstrating thoroughness. Tasks progress through three states: pending, in_progress, and completed.

Task State Machine

Sources: Anthropic/Claude Code/Tools.json390-433

TodoWrite Parameters

The tool takes a single parameter:

Parameter	Type	Required	Description
todos	array	Yes	Updated todo list with content, status, and id fields

Todo Object Schema:

Field	Type	Values	Description
content	string	-	Task description (min 1 character)
status	string	pending, in_progress, completed	Current task state
id	string	-	Unique task identifier

Sources: Anthropic/Claude Code/Tools.json390-433

When to Use TodoWrite

Use TodoWrite proactively in these scenarios:

1. Complex multi-step tasks - 3 or more distinct steps/actions required
2. Non-trivial and complex tasks - Require careful planning or multiple operations
3. User explicitly requests todo list - Direct user request
4. User provides multiple tasks - Numbered or comma-separated list
5. After receiving new instructions - Immediately capture requirements
6. When starting work on task - Mark in_progress BEFORE beginning
7. After completing task - Mark completed and add follow-up tasks

When NOT to Use TodoWrite

Skip TodoWrite when:

1. Single straightforward task - Only one simple action
2. Trivial task - No organizational benefit from tracking
3. Less than 3 trivial steps - Can complete without tracking
4. Purely conversational/informational - No coding action required

Sources: Anthropic/Claude Code/Tools.json390-433

Task Management Principles

Task Completion Requirements:

ONLY mark task as completed when:

• Task is fully accomplished
• Tests are passing (if applicable)
• Implementation is complete (not partial)
• No unresolved errors remain
• All necessary files/dependencies found

Keep task as in_progress when:

• Tests are failing
• Implementation is partial
• Encountered unresolved errors
• Cannot find necessary files
• Blocked on external dependency

Task State Management Rules:

• Update status in real-time as you work
• Mark tasks completed IMMEDIATELY after finishing (no batching)
• Only ONE task in_progress at any time
• Complete current tasks before starting new ones
• Remove irrelevant tasks entirely from list

Sources: Anthropic/Claude Code/Tools.json390-433

TodoWrite Usage Examples

Example 1: Multi-step Feature Implementation

User: "Add dark mode toggle to settings. Run tests and build when done."

Assistant creates TodoWrite:
1. Create dark mode toggle component in Settings page (pending)
2. Add dark mode state management (context/store) (pending)
3. Implement CSS-in-JS styles for dark theme (pending)
4. Update existing components to support theme switching (pending)
5. Run tests and build process, addressing any failures (pending)

Example 2: Codebase-wide Refactor

User: "Rename getCwd to getCurrentWorkingDirectory across project"

Assistant first searches, finds 15 instances across 8 files, then creates TodoWrite:
1. Update src/utils/filesystem.ts (pending)
2. Update src/commands/init.ts (pending)
3. Update src/lib/paths.ts (pending)
[... one task per file requiring changes ...]

Example 3: Counter-example - NO TodoWrite

User: "Add a comment to the calculateTotal function"

Assistant uses Edit tool directly without TodoWrite.
Reason: Single, straightforward task with no tracking benefit.

Sources: Anthropic/Claude Code/Tools.json390-433

Search and Discovery Tools

Claude Code provides three complementary search tools optimized for different discovery patterns: Grep for content search, Glob for file pattern matching, and LS for directory structure exploration.

Search Tool Selection Matrix

Sources: Anthropic/Claude Code/Tools.json62-81 Anthropic/Claude Code/Tools.json83-148 Anthropic/Claude Code/Tools.json150-173

Grep Tool - Ripgrep-Based Content Search

The Grep tool leverages ripgrep for powerful content searching with regex support, file filtering, and multiple output modes.

Parameters:

Parameter	Type	Description
pattern	string	Regex pattern (ripgrep syntax, not standard grep)
path	string	File or directory to search (default: current directory)
glob	string	File filter pattern (e.g., ".js", ".{ts,tsx}")
output_mode	enum	"content", "files_with_matches" (default), "count"
-B	number	Lines before match (content mode only)
-A	number	Lines after match (content mode only)
-C	number	Lines before and after match (content mode only)
-n	boolean	Show line numbers (content mode only)
-i	boolean	Case insensitive search
type	string	File type filter (js, py, rust, go, java, etc.)
head_limit	number	Limit output to first N lines/entries
multiline	boolean	Enable multiline mode where . matches newlines

Critical Requirements:

• ALWAYS use Grep tool for search - NEVER invoke grep or rg as Bash command
• Pattern uses ripgrep syntax (literal braces need escaping: interface\{\})
• Default behavior matches within single lines only
• Use multiline: true for cross-line patterns like struct \{[\s\S]*?field

Output Modes:

Mode	Description	Supports Context (-A/-B/-C)	Supports head_limit
content	Shows matching lines with context	Yes	Yes (limits output lines)
files_with_matches	Shows only file paths	No	Yes (limits file paths)
count	Shows match counts per file	No	Yes (limits count entries)

Sources: Anthropic/Claude Code/Tools.json83-148

Glob Tool - Fast File Pattern Matching

The Glob tool provides fast file pattern matching using glob syntax, sorted by modification time.

Parameters:

Parameter	Type	Required	Description
pattern	string	Yes	Glob pattern (e.g., "/*.js", "src//*.ts")
path	string	No	Directory to search (default: current directory)

Key Characteristics:

• Fast performance regardless of codebase size
• Returns file paths sorted by modification time (most recent first)
• Use for finding files by name patterns
• Speculate with multiple searches in parallel when exploring
• For open-ended searches requiring multiple rounds, use Task tool instead

Common Patterns:

• **/*.js - All JavaScript files recursively
• src/**/*.ts - All TypeScript files under src/
• **/test/*.py - All Python files in any test/ directory
• config/*.json - All JSON files directly under config/

Sources: Anthropic/Claude Code/Tools.json62-81

LS Tool - Directory Listing

The LS tool lists files and directories at a specific path with optional glob pattern filtering.

Parameters:

Parameter	Type	Required	Description
path	string	Yes	Absolute path to directory (must be absolute, not relative)
ignore	array	No	Array of glob patterns to ignore

Usage Guidelines:

• Path MUST be absolute (not relative)
• Generally prefer Glob and Grep tools if you know which directories to search
• Use LS when you need to explore directory structure without specific patterns
• Ignore parameter useful for excluding common patterns (e.g., ["node_modules", ".git"])

Sources: Anthropic/Claude Code/Tools.json150-173

Search Strategy Decision Tree

Sources: Anthropic/Claude Code/Tools.json62-81 Anthropic/Claude Code/Tools.json83-148 Anthropic/Claude Code/Tools.json150-173

Web Interaction Capabilities

Claude Code provides two tools for web interaction: WebFetch for retrieving and analyzing specific URLs, and WebSearch for discovering information across the web.

WebFetch Tool - URL Content Retrieval

The WebFetch tool fetches web content, converts HTML to markdown, and processes it with an AI model to extract specific information.

Parameters:

Parameter	Type	Required	Description
url	string (URI)	Yes	Fully-formed valid URL to fetch
prompt	string	Yes	Extraction prompt for AI model

Characteristics:

• HTTP URLs automatically upgraded to HTTPS
• HTML content converted to markdown for processing
• Processed by small, fast AI model
• Results may be summarized if content is very large
• 15-minute self-cleaning cache for repeated access to same URL
• Read-only (does not modify files)
• Handles redirects with special format notification

Usage Pattern:

• Prefer MCP-provided web fetch tools (prefixed with mcp__) if available (fewer restrictions)
• Provide clear extraction prompt describing desired information
• Handle redirect notifications by making new request with redirect URL

Sources: Anthropic/Claude Code/Tools.json366-389

WebSearch Tool - Web Search

The WebSearch tool performs web searches and returns formatted search results.

Parameters:

Parameter	Type	Required	Description
query	string	Yes	Search query (min 2 characters)
allowed_domains	array	No	Only include results from these domains
blocked_domains	array	No	Never include results from these domains

Characteristics:

• Only available in the US
• Returns search result blocks within single API call
• Provides up-to-date information beyond Claude's knowledge cutoff
• Supports domain filtering for focused searches
• Account for current date when forming queries (check <env> for "Today's date")

Usage Note: When user wants latest docs and <env> shows "Today's date: 2025-07-01", do NOT use 2024 in search query - use current year 2025.

Sources: Anthropic/Claude Code/Tools.json434-466

Plan Mode Workflow

Claude Code includes a plan mode for complex implementation tasks, exited via the ExitPlanMode tool after presenting a concise plan for user approval.

ExitPlanMode Tool

Parameters:

Parameter	Type	Required	Description
plan	string	Yes	Concise plan in markdown format

Usage Guidelines:

When to use ExitPlanMode:

• Task requires planning implementation steps
• Task involves writing code
• After finishing plan presentation and ready to code

When NOT to use ExitPlanMode:

• Research tasks (gathering information, searching files, understanding codebase)
• Read-only exploration tasks
• Information retrieval without implementation

Examples:

Task Type	Use ExitPlanMode?	Reason
"Search for and understand vim mode implementation"	NO	Research task, no coding
"Help me implement yank mode for vim"	YES	Implementation task requiring code
"Find all usages of DatabaseConnection"	NO	Search/discovery task
"Refactor authentication to use JWT tokens"	YES	Implementation task requiring code

Plan Characteristics:

• Should be concise (not exhaustive)
• Supports markdown formatting
• Presents implementation steps for user approval
• Prompts user to exit plan mode after tool use

Sources: Anthropic/Claude Code/Tools.json175-192

---

Summary

Claude Code's architecture centers on three core mechanisms:

1. Task-based orchestration via specialized sub-agents (general-purpose, statusline-setup, output-style-setup) with restricted tool access for autonomous multi-step operations
2. Strict file editing workflows requiring read-before-write with exact string matching through Edit, MultiEdit, Write, and NotebookEdit tools
3. Comprehensive task management through TodoWrite with three-state tracking (pending, in_progress, completed) for complex multi-step work

The system enforces critical operational constraints: mandatory file reading before editing, atomic MultiEdit operations, single in_progress task limits, parallel tool execution for independent operations, absolute path requirements, and preference for specialized tools (Grep, Glob) over Bash alternatives. Git workflows require HEREDOC message formatting and parallel information gathering, while search operations prioritize ripgrep-based Grep for content, Glob for file patterns, and LS for directory exploration.

Sources: Anthropic/Claude Code/Tools.json1-509