Built-in Tools

Claude Code ships with over 40 built-in tools organized into distinct categories. Each tool is implemented as a directory under src/tools/, containing the tool definition, UI components, and prompt text. This chapter catalogs every tool and explains the design rationale behind each category.

Tool Directory Structure

Each tool follows a consistent file layout:

src/tools/
├── BashTool/
│   ├── BashTool.tsx          # Tool definition (call, schema, permissions)
│   ├── UI.tsx                # Rendering components
│   ├── prompt.ts             # System prompt for the tool
│   ├── toolName.ts           # Exported name constant
│   ├── bashPermissions.ts    # Permission logic
│   ├── bashSecurity.ts       # Security checks
│   └── commandSemantics.ts   # Command classification
├── FileReadTool/
│   ├── FileReadTool.ts
│   ├── UI.tsx
│   ├── prompt.ts
│   └── limits.ts
└── ...

Category Overview

mindmap
  root((Tools))
    File Operations
      FileRead
      FileWrite
      FileEdit
      NotebookEdit
    Search & Discovery
      Glob
      Grep
      ToolSearch
      LSP
    Execution
      Bash
      PowerShell
      REPL
    Agent & Task
      Agent
      TaskCreate
      TaskGet
      TaskList
      TaskOutput
      TaskStop
      TaskUpdate
    Communication
      AskUserQuestion
      SendMessage
      Brief
    Web
      WebSearch
      WebFetch
    Meta & Config
      TodoWrite
      Config
      Skill
    Plan & Workflow
      EnterPlanMode
      ExitPlanMode
      EnterWorktree
      ExitWorktree
    MCP
      MCPTool
      McpAuth
      ListMcpResources
      ReadMcpResource
    Team
      TeamCreate
      TeamDelete
    Background
      Sleep
      ScheduleCron
      RemoteTrigger
      SyntheticOutput

File Operations

FileRead

Path: src/tools/FileReadTool/FileReadTool.ts

Reads files from the local filesystem. Supports:

Text files with line numbers (cat -n format)
Images (PNG, JPG) — returned as base64 for multimodal processing
PDFs — page-by-page text + visual extraction
Jupyter notebooks (.ipynb) — all cells with outputs
Offset/limit parameters for reading large files in chunks

inputSchema: z.object({
  file_path: z.string(),
  offset: z.number().optional(),
  limit: z.number().optional(),
})

Design: maxResultSizeChars: Infinity — results are never persisted because the tool already self-bounds via limits.ts. This avoids circular Read→file→Read loops.

FileWrite

Path: src/tools/FileWriteTool/FileWriteTool.ts

Writes complete file contents. Creates parent directories if needed. Tracks lines added/removed for the cost display.

Design: Requires permission check. Non-concurrent (side-effecting). Shows a diff preview in the TUI.

FileEdit

Path: src/tools/FileEditTool/FileEditTool.ts

Performs exact string replacements in files. The old_string → new_string pattern ensures precise edits without requiring line numbers (which can drift).

inputSchema: z.object({
  file_path: z.string(),
  old_string: z.string(),
  new_string: z.string(),
  replace_all: z.boolean().default(false),
})

Design: The edit will fail if old_string is not unique in the file (unless replace_all is true). This constraint prevents accidental edits to the wrong location.

NotebookEdit

Path: src/tools/NotebookEditTool/NotebookEditTool.ts

Edits Jupyter notebook cells by index. Supports replace, insert, and delete operations.

Design: Deferred by default (shouldDefer: true) — only loaded when the model uses ToolSearch to find it. The searchHint: 'jupyter' helps discovery.

Search & Discovery

Glob

Path: src/tools/GlobTool/GlobTool.ts

Fast file pattern matching using glob patterns (e.g., **/*.ts). Returns matching file paths sorted by modification time.

Design: Concurrent-safe (read-only). Results capped at globLimits.maxResults.

Grep

Path: src/tools/GrepTool/GrepTool.ts

Content search built on ripgrep. Supports regex, file type filtering, context lines, and multiple output modes (content, files_with_matches, count).

Design: Concurrent-safe. The ripgrep binary is bundled with Claude Code for consistent behavior across platforms.

ToolSearch

Path: src/tools/ToolSearchTool/

Searches the available tool list by keyword. Enables the deferred loading pattern — tools with shouldDefer: true are only fully loaded when discovered via this tool.

LSP

Path: src/tools/LSPTool/LSPTool.ts

Language Server Protocol integration. Provides semantic code intelligence (go-to-definition, find-references, diagnostics). Only enabled when LSP servers are connected (IDE integrations).

Execution

Bash

Path: src/tools/BashTool/BashTool.tsx

The most complex built-in tool. Executes shell commands in a persistent session with:

Timeout management
Sandbox mode (macOS Seatbelt, Linux Landlock)
Command classification for security (destructive detection)
Output truncation for large results
sed validation to prevent accidental file corruption

inputSchema: z.object({
  command: z.string(),
  timeout: z.number().optional(),
  description: z.string().optional(),
})

Design: Non-concurrent. Only Bash errors trigger sibling cancellation in StreamingToolExecutor — the rationale is that Bash commands often form implicit dependency chains.

PowerShell

Path: src/tools/PowerShellTool/

Windows-specific command execution via PowerShell. Alternative to Bash on Windows platforms.

REPL

Path: src/tools/REPLTool/

A “transparent wrapper” that delegates to other tools. Used internally for the interactive REPL loop where the model can chain multiple tool calls.

Agent & Task System

Agent (SubAgent)

Path: src/tools/AgentTool/AgentTool.tsx

Spawns a sub-agent with its own conversation context. The sub-agent runs a nested query() loop and returns a summary.

Design: Supports several built-in agent types:

generalPurposeAgent — general task handling
exploreAgent — code exploration
planAgent — planning
verificationAgent — verification
claudeCodeGuideAgent — help/documentation

Task Management (TaskCreate, TaskGet, TaskList, TaskOutput, TaskStop, TaskUpdate)

Path: src/tools/Task*Tool/

A family of tools for managing background tasks. Tasks run as independent processes and can be monitored, updated, or stopped.

Tool	Purpose
`TaskCreate`	Start a new background task
`TaskGet`	Check task status
`TaskList`	List all tasks
`TaskOutput`	Read task output
`TaskStop`	Terminate a task
`TaskUpdate`	Send update to a running task

Communication

AskUserQuestion

Path: src/tools/AskUserQuestionTool/AskUserQuestionTool.tsx

Prompts the user for input. Returns their response as the tool result.

Design: requiresUserInteraction: () => true — hooks can satisfy this interaction by providing updatedInput in a PreToolUse hook response.

SendMessage

Path: src/tools/SendMessageTool/

Sends messages to other agents in multi-agent setups.

Brief

Path: src/tools/BriefTool/BriefTool.ts

Creates a brief/report with optional file attachments and uploads.

Web

WebSearch

Path: src/tools/WebSearchTool/

Performs web searches using the Anthropic server-side web search tool. Returns search results with snippets and links.

WebFetch

Path: src/tools/WebFetchTool/

Fetches content from a URL, converts HTML to markdown, and processes it with a small model for summarization.

Meta & Configuration

TodoWrite

Path: src/tools/TodoWriteTool/TodoWriteTool.ts

Creates and manages a structured task list displayed in the TUI sidebar. Used for tracking multi-step tasks.

Design: renderToolResultMessage returns null — the result is shown in the todo panel, not the transcript.

Config

Path: src/tools/ConfigTool/ConfigTool.ts

Views and modifies Claude Code settings. Supports a curated list of settings defined in supportedSettings.ts.

Skill

Path: src/tools/SkillTool/

Invokes registered skills (specialized capabilities). Skills are discovered via ToolSearch or direct reference.

Plan & Workflow

EnterPlanMode / ExitPlanMode

Paths: src/tools/EnterPlanModeTool/, src/tools/ExitPlanModeTool/

Switches between plan mode (read-only, no writes) and normal mode. Plan mode restricts available tools to read-only operations.

Design: Uses contextModifier to change ToolPermissionContext.mode — this is why context modifiers exist on the ToolResult type.

EnterWorktree / ExitWorktree

Paths: src/tools/EnterWorktreeTool/, src/tools/ExitWorktreeTool/

Git worktree management. Creates and switches between worktrees for parallel development workflows.

MCP Tools

MCPTool

Path: src/tools/MCPTool/MCPTool.ts

A generic wrapper that adapts MCP server tools to the Claude Code Tool interface. Dynamically created when MCP servers connect.

McpAuth, ListMcpResources, ReadMcpResource

MCP infrastructure tools for authentication, resource discovery, and resource reading.

Naming Conventions

Convention	Example	Purpose
`PascalCase` directory	`BashTool/`	Tool directory name
`PascalCase` class	`BashTool`	Exported tool name
`camelCase` file	`toolName.ts`	Supporting modules
`mcp__server__tool`	`mcp__github__create_issue`	MCP tool naming

Key Implementation Patterns

Prompt Separation

Every tool separates its system prompt into a dedicated prompt.ts file:

export async function getBashPrompt(options: {...}): Promise<string> {
  return `You have access to a Bash tool for terminal operations...`;
}

This pattern allows prompts to be:

Loaded lazily (only when the tool is used)
Tested independently
Dynamic based on context

Progress Reporting

Tools can report progress during execution via the onProgress callback:

async call(args, context, canUseTool, parentMessage, onProgress) {
  onProgress?.({
    toolUseID: context.toolUseId!,
    data: { type: 'bash_progress', output: 'Running tests...' },
  });
  // ... execute ...
}

Progress messages are yielded immediately to the UI (not buffered), enabling real-time status updates.

Grouped Rendering

Tools that commonly run in parallel (like Grep, Glob) can implement renderGroupedToolUse to show a condensed view:

Searched 5 files with Grep  [3 results, 2 no match]

Instead of showing 5 separate tool use/result blocks.