Claude Code's Tool System: Read, Write, Bash, Glob, Grep Explained

The Building Blocks of Agentic Coding

Claude Code's power comes from six core tools that give it the ability to interact with your filesystem, run commands, and search your codebase. Every action Claude Code takes — from reading a configuration file to deploying a feature — is composed of calls to these tools.

Understanding how each tool works, when Claude Code selects it, and how they combine helps you write better prompts and understand Claude Code's behavior.

Tool 1: Read

Purpose: Read the contents of any file.

How It Works

The Read tool takes a file path and returns the file contents with line numbers. It supports text files of any size (with pagination for very large files), images (displayed visually), PDFs (with page selection), and Jupyter notebooks.

[Read] /home/user/project/src/api/users.ts
Returns: Numbered lines of the file content

When Claude Code Uses Read

• At the start of a task, to understand existing code
• Before editing a file, to see its current state
• To examine configuration files (package.json, tsconfig.json)
• To read test output or log files
• To understand import chains and dependencies

Key Behaviors

• Claude Code must read a file before editing it (the Edit tool enforces this)
• Binary files are detected and handled appropriately
• Image files are rendered visually — Claude Code can analyze screenshots, diagrams, and UI mockups
• Large files can be read in segments using offset and limit parameters

Tool 2: Write

Purpose: Create a new file or completely overwrite an existing file.

How It Works

The Write tool takes a file path and content, then creates or overwrites the file:

[Write] /home/user/project/src/utils/helpers.ts
Content: [complete file contents]

When Claude Code Uses Write

• Creating new files (new modules, test files, configuration)
• Complete file rewrites when most of the content changes
• Generating starter templates

Key Behaviors

• Write completely replaces file contents — there is no merge
• Claude Code prefers Edit over Write for existing files because Edit only sends the diff
• Parent directories must exist (Claude Code will create them with Bash if needed)

Tool 3: Edit

Purpose: Make targeted string replacements in existing files.

How It Works

The Edit tool finds an exact string in a file and replaces it with new content:

[Edit] /home/user/project/src/api/users.ts
old_string: "const limit = 10;"
new_string: "const limit = parseInt(req.query.limit as string) || 20;"

When Claude Code Uses Edit

• Fixing bugs (changing specific lines)
• Adding new code to existing files (replacing a closing brace with new code + closing brace)
• Renaming variables or functions (with replace_all flag)
• Updating import statements
• Modifying configuration values

Key Behaviors

• The old_string must be unique in the file. If it appears multiple times, the edit fails unless replace_all is set to true
• Claude Code must Read the file before using Edit — this ensures it has accurate, up-to-date content
• Indentation and whitespace must match exactly
• Edit is preferred over Write for existing files because it shows a clear diff

Why Edit Exists Alongside Write

Edit is the most important tool for code quality because:

1. Precision — It changes exactly what needs to change, nothing more
2. Reviewability — The old/new string pair shows a clear diff
3. Safety — It fails if the target string is not found, preventing edits to the wrong file or wrong location
4. Efficiency — For a one-line fix in a 500-line file, Edit sends ~2 lines of data versus Write sending all 500

Tool 4: Bash

Purpose: Execute shell commands.

How It Works

Bash runs a command in your terminal and returns the output:

[Bash] npm test -- --testPathPattern="users"
Returns: Test output (pass/fail, assertions, coverage)

When Claude Code Uses Bash

• Running tests: pytest, npm test, go test
• Installing dependencies: npm install, pip install
• Build commands: npm run build, cargo build
• Git operations: git status, git diff, git commit
• Database commands: npx prisma migrate dev, alembic upgrade head
• Checking system state: docker ps, kubectl get pods
• Running linters: npx eslint, ruff check

Key Behaviors

• Bash commands require permission approval unless auto-approved in settings
• Commands have a configurable timeout (default 2 minutes, max 10 minutes)
• The working directory resets between calls — use absolute paths
• Environment variables from your shell profile are available
• Both stdout and stderr are captured and returned

Permission Auto-Approval

{
  "permissions": {
    "allow": [
      "Bash(npm test*)",
      "Bash(npx tsc*)",
      "Bash(pytest*)",
      "Bash(git status)",
      "Bash(git diff*)",
      "Bash(git log*)"
    ]
  }
}

Tool 5: Glob

Purpose: Fast file pattern matching.

How It Works

Glob finds files matching a pattern:

[Glob] pattern: "**/*.test.ts" path: "/home/user/project/src"
Returns: List of matching file paths, sorted by modification time

When Claude Code Uses Glob

• Finding all files of a specific type: **/*.py
• Locating test files: **/*.test.ts, **/test_*.py
• Finding configuration files: **/tsconfig.json, **/Dockerfile
• Exploring project structure: src/**/*

Key Behaviors

• Results are sorted by modification time (most recent first)
• Works with any codebase size — optimized for performance
• Supports standard glob patterns: *, **, ?, [abc]
• Returns file paths only, not contents

Glob vs. Bash(find)

Claude Code uses Glob instead of find because:

• Glob is faster for pattern matching
• Glob handles permissions correctly
• Results are consistently formatted
• No risk of shell injection

Tool 6: Grep

Purpose: Search file contents with regex.

How It Works

Grep searches for patterns across files:

[Grep] pattern: "async function create" path: "src/services/" type: "ts"
Returns: Matching file paths (or content with line numbers)

When Claude Code Uses Grep

• Finding function definitions: function\s+createUser
• Searching for imports: import.*from.*database
• Finding TODO comments: TODO|FIXME|HACK
• Tracing API endpoints: router\.(get|post|put|delete)
• Finding configuration values: DATABASE_URL

Output Modes

Mode	Returns	Use Case
files_with_matches	File paths only	Finding which files contain a pattern
content	Matching lines with line numbers	Reading the matched code in context
count	Match counts per file	Measuring pattern prevalence

Key Behaviors

• Built on ripgrep (rg) — extremely fast, even on large codebases
• Supports full regex syntax
• Can filter by file type (--type ts) or glob pattern (--glob "*.py")
• Context lines (-A, -B, -C) show surrounding code

How Tools Combine in Real Workflows

Bug Fix Workflow

1. [Grep]  Search for the error message in the codebase
2. [Read]  Read the file containing the error
3. [Read]  Read related files (imports, dependencies)
4. [Edit]  Fix the bug
5. [Bash]  Run relevant tests
6. [Edit]  Fix any test failures
7. [Bash]  Run tests again — all pass

Feature Implementation Workflow

1. [Glob]  Find existing similar features for pattern reference
2. [Read]  Read 3-4 existing implementations to understand patterns
3. [Write] Create new model/schema file
4. [Write] Create new service file
5. [Edit]  Add route to existing router file
6. [Edit]  Update exports/imports
7. [Write] Create test file
8. [Bash]  Run tests
9. [Edit]  Fix failures
10. [Bash] Run tests — all pass
11. [Bash] git add && git commit

Code Review Workflow

1. [Bash]  git diff HEAD~1
2. [Read]  Read each changed file
3. [Grep]  Search for patterns mentioned in the diff
4. [Read]  Read test files for changed modules
5. (Text)  Provide review with specific findings

Tool Selection Insights

Claude Code's tool selection is not random — it follows consistent patterns:

• Start with Read or Grep to understand context before making changes
• Prefer Edit over Write for existing files
• Use Glob before Grep when you know the file type but not the content
• Use Grep before Read when you know what to search for but not which file
• Run Bash after Edit to verify changes work (tests, linting, compilation)
• Chain multiple Edits for coordinated changes across files

Conclusion

Claude Code's six core tools — Read, Write, Edit, Bash, Glob, Grep — are simple individually but powerful in combination. Understanding how they work and when they are selected helps you write more effective prompts, predict Claude Code's behavior, and configure permissions appropriately. The tool system is what transforms Claude from a text-generating model into an autonomous coding agent that can navigate, understand, modify, and verify real codebases.