Shell Command Execution

Relevant source files

• Anthropic/Claude Code/Tools.json

Overview

The Bash tool provides Claude Code's primary interface for shell command execution in a persistent bash session. This tool handles system commands, test execution, git operations, and command-line utility interaction. The tool supports both synchronous execution (blocking until completion) and background execution (non-blocking with process monitoring), configurable timeouts, and strict command formatting requirements.

Three tools comprise the shell execution system:

• Bash: Executes commands with optional background execution
• BashOutput: Retrieves incremental output from background processes
• KillBash: Terminates running background processes

Related pages: Task Tool and Sub-agent Specialization, File Editing Operations, TodoWrite Task Management System, Search and Discovery Tools.

---

Bash Tool Architecture

The Bash tool executes shell commands in a persistent shell session with configurable timeout, optional background execution, and strict command formatting requirements. All system interaction—including git operations, test execution, and file system operations—flows through this tool.

Bash Tool Schema

The Bash tool is defined in the tools array with name: "Bash" and an input_schema object specifying four parameters:

Parameter	Type	Required	Default	Max Value	Description
command	string	Yes	-	-	Bash command to execute
timeout	number	No	120000ms	600000ms	Timeout in milliseconds (10 minutes max)
description	string	No	-	-	5-10 word command description
run_in_background	boolean	No	false	-	Execute in background without blocking

JSON Schema Structure:

Description Field Examples from Tool Documentation:

Command	Description
ls	Lists files in current directory
git status	Shows working tree status
npm install	Installs package dependencies
mkdir foo	Creates directory 'foo'

Output Constraints:

• Default timeout: 120000ms (2 minutes)
• Maximum timeout: 600000ms (10 minutes)
• Output truncates at 30000 characters

Sources: Anthropic/Claude Code/Tools.json32-59

Command Execution Modes

Bash Tool Execution Flow

Synchronous Execution (Default):

• Blocks until command completes or reaches timeout
• Returns stdout and stderr to assistant immediately
• Used for: file operations, test execution, builds, git commands

Background Execution:

• Returns immediately with bash_id identifier
• Process continues running independently
• Output retrieved incrementally via BashOutput tool
• Critical constraints:
  • Never use for sleep commands (returns immediately without actual delay)
  • Do NOT append & to command string—parameter handles backgrounding automatically

Sources: Anthropic/Claude Code/Tools.json49-52

Command Formatting Requirements

Bash Command Formatting Rules

Path Quoting Rules:

Multiple Command Separation:

Working Directory Management:

Only use cd if the user explicitly requests it.

Directory Verification: Before creating directories or files, use the LS tool to verify the parent directory exists and is the correct location:

Sources: Anthropic/Claude Code/Tools.json36-68

Prohibited Command Patterns

The tool documentation explicitly prohibits certain shell commands in favor of specialized Claude Code tools with optimized permissions and functionality:

Prohibited	Replacement Tool	Reason
find	Glob	Fast file pattern matching
grep	Grep	Pre-configured ripgrep with correct permissions
rg	Grep	Tool has optimized access control
cat / head / tail	Read	Multimodal support (images, PDFs, Jupyter notebooks)
ls	LS	Structured directory listing with glob ignores

Special Note on grep/ripgrep: The tool documentation states: "VERY IMPORTANT: You MUST avoid using search commands like find and grep. Instead use Grep, Glob, or Task to search. You MUST avoid read tools like cat, head, tail, and ls, and use Read and LS to read files. If you still need to run grep, STOP. ALWAYS USE ripgrep at rg first, which all Claude Code users have pre-installed."

However, even rg should be avoided in favor of the Grep tool.

Sources: Anthropic/Claude Code/Tools.json53-55

---

Background Process Management

Background execution supports long-running processes (dev servers, test suites, build watchers) without blocking the assistant. The lifecycle uses three tools: Bash (launch), BashOutput (monitor), KillBash (terminate).

Starting Background Processes

Background Process Launch Flow

Background Execution Tool Call:

Tool Response (includes bash_id identifier):

The response provides a bash_id string that serves as the identifier for subsequent BashOutput and KillBash operations.

Critical Constraints:

• Never use run_in_background for sleep commands (returns immediately without waiting)
• Do NOT append & to command string—backgrounding is automatic
• Assistant can immediately continue with other work
• Shell ID discovery: Use /bashes command to list all active background shells

Sources: Anthropic/Claude Code/Tools.json49-52

Monitoring with BashOutput

The BashOutput tool retrieves output from running or completed background shells. It returns only new output since the last check, enabling incremental monitoring.

BashOutput Tool Schema:

The tool is defined with name: "BashOutput" and accepts two parameters in its input_schema:

Parameter	Type	Required	Description
bash_id	string	Yes	Background shell identifier
filter	string	No	Regex pattern to filter output lines

BashOutput Retrieval Flow

Incremental Output Retrieval

Regex Filtering Behavior: When filter parameter is provided:

1. Only lines matching the regex pattern are returned
2. Non-matching lines are permanently discarded—unavailable in future calls
3. Use for extracting specific information (errors, test results) from verbose output

Example Tool Call with filter parameter:

When the filter parameter contains a regex pattern, only lines matching the pattern are returned. All other output is permanently discarded and unavailable in future BashOutput calls.

Shell ID Discovery: The /bashes command lists all active background shells and their identifiers.

Sources: Anthropic/Claude Code/Tools.json468-487

Terminating with KillBash

The KillBash tool terminates a running background shell by identifier.

KillBash Tool Schema:

The tool is defined with name: "KillBash" and accepts one parameter in its input_schema:

Parameter	Type	Required	Description
shell_id	string	Yes	Background shell identifier to terminate

KillBash Termination Flow

Example Tool Call:

Tool Response:

The shell_id parameter value must match a valid background shell identifier returned by a previous Bash tool call with run_in_background: true.

Termination Triggers:

• User explicitly requests termination
• Process no longer needed (dev server after testing)
• Process appears hung or unresponsive
• Restarting same service with new configuration

Shell ID Discovery: The /bashes command lists all active background shells with their identifiers.

Sources: Anthropic/Claude Code/Tools.json490-505

---

Git Operations

The Bash tool includes extensive documentation for git workflows through the GitHub CLI (gh). Git operations follow structured multi-phase patterns with parallel execution, pre-commit hook handling, and mandatory formatting requirements.

Git Commit Workflow

The Bash tool documentation includes extensive guidelines for git commit operations. The workflow consists of three phases when a user requests creating a git commit:

Phase 1: Information Gathering (Parallel Execution)

The assistant must invoke the Bash tool multiple times in parallel with these command values:

Phase 2: Commit Message Drafting

The assistant analyzes the changes and drafts a commit message:

• Summarize nature of changes (feature, enhancement, bug fix, refactoring, test, docs)
• Ensure accuracy ("add" = new feature, "update" = enhancement, "fix" = bug fix)
• Check for sensitive information (abort if found)
• Draft concise 1-2 sentence message focusing on "why" not "what"
• Match repository's commit style from git log output
• Append mandatory footer:

  🤖 Generated with [Claude Code](https://claude.ai/code)
  
  Co-Authored-By: Claude <[email protected]>
  

Phase 3: Commit Execution (Parallel Execution)

Batch these Bash tool calls in parallel:

HEREDOC Requirement: The tool documentation explicitly requires HEREDOC syntax (<<'EOF') in the command parameter for all commit messages to ensure proper formatting. Example from documentation:

This HEREDOC approach prevents issues with special characters and newlines in the command string submitted to the Bash tool.

Pre-commit Hook Handling:

• If commit fails due to pre-commit hook changes: Retry ONCE
• If commit succeeds but hook modified files: MUST amend commit to include modifications
• If second attempt fails: Pre-commit hook is preventing commit (report to user)

Sources: Anthropic/Claude Code/Tools.json73-107

Pull Request Workflow

The Bash tool documentation includes guidelines for PR creation using GitHub CLI (gh). The workflow consists of three phases:

Phase 1: Branch Analysis (Parallel Execution)

Invoke the Bash tool with these command values in parallel to understand the current branch state since divergence from main:

Critical: The documentation emphasizes examining ALL commits that will be included, not just the latest commit.

Phase 2: PR Summary Drafting

Analyze all changes across all relevant commits:

• Draft PR summary with 1-3 bullet points
• Create test plan checklist
• Include mandatory footer

Phase 3: PR Creation (Parallel Execution)

Invoke the Bash tool with these command values in parallel:

The assistant must return the PR URL to the user after successful creation.

HEREDOC Format for gh pr create: The tool documentation requires HEREDOC syntax in the command parameter when calling gh pr create:

This ensures proper formatting of the PR body text submitted through the gh CLI tool.

Sources: Anthropic/Claude Code/Tools.json109-153

Git Operation Constraints

The tool documentation specifies strict constraints for git operations:

Operation	Policy	Rationale
git config	NEVER update	Prevents configuration tampering
git push (commits)	Only on explicit user request	User authorization required
git push -u (PRs)	Allowed	Required for PR creation workflow
Interactive flags (-i)	NEVER use	No interactive input support
Empty commits	NEVER create	Must have changes to commit
TodoWrite tool	NEVER during git ops	Maintain git workflow focus
Task tool	NEVER during git ops	No sub-agent delegation

GitHub CLI (gh) Integration:

The tool documentation specifies: "Use the gh command via the Bash tool for ALL GitHub-related tasks including working with issues, pull requests, checks, and releases. If given a Github URL use the gh command to get the information needed."

Common gh command values for the Bash tool:

• Create PR: gh pr create --title "..." --body "..."
• View issues: gh issue list
• PR comments: gh api repos/[owner]/[repo]/pulls/[number]/comments
• View specific PR comments: gh api repos/foo/bar/pulls/123/comments

All gh operations are executed through the Bash tool with the GitHub CLI command in the command parameter.

Sources: Anthropic/Claude Code/Tools.json77-78 Anthropic/Claude Code/Tools.json103-106 Anthropic/Claude Code/Tools.json109-111 Anthropic/Claude Code/Tools.json150-153

Tool Restrictions During Git Operations

The tool documentation enforces strict separation of concerns during git workflows to maintain focus and performance:

Prohibited Tools During Git Operations:

Tool	Prohibition Scope	Reason
TodoWrite	Commit + PR workflows	Maintain git workflow focus
Task	Commit + PR workflows	No sub-agent delegation
Read / Edit / Write	All git operations	No additional code exploration

Exception for Read Tool: The Read tool may only be used for viewing images/screenshots if user provides file paths, but NOT for code exploration during git operations.

Workflow Isolation:

The tool documentation explicitly states: "NEVER run additional commands to read or explore code, besides git bash commands" and "DO NOT use the TodoWrite or Task tools" during git commit and PR workflows.

Sources: Anthropic/Claude Code/Tools.json103 Anthropic/Claude Code/Tools.json150-151

---

Integration with Other Claude Code Systems

Git operations integrate with Claude Code's broader tool ecosystem while maintaining strict separation of concerns:

Tool Usage Restrictions During Git Operations

Prohibited Tools:

• TodoWrite: Not used during commit or PR workflows Anthropic/Claude Code/Tools.json103 Anthropic/Claude Code/Tools.json151
• Task: No sub-agent delegation during git operations Anthropic/Claude Code/Tools.json103 Anthropic/Claude Code/Tools.json151
• Read/Edit/Write: No additional code exploration beyond git commands Anthropic/Claude Code/Tools.json103

Allowed Tools:

• Bash: Exclusive tool for all git and gh operations
• Read: Only for reading images/screenshots if user provides paths (not for code exploration during git ops)

Workflow Boundaries

Diagram: Git Operations Workflow Boundaries
This diagram shows how git operations form isolated phases where only the Bash tool is permitted.

The strict tool separation ensures git workflows remain focused and performant, preventing scope creep into code exploration or task management that would slow the commit/PR process.

Sources: Anthropic/Claude Code/Tools.json103 Anthropic/Claude Code/Tools.json150-151