AI Assistant

Shell Tools

Claude Code provides three tools for executing commands in a shell environment: BashTool for Unix-like systems, PowerShellTool for Windows, and REPLTool for sandboxed Python/Node execution.

BashTool

The primary shell execution tool. Runs commands in the user's shell with full access to the system environment.

Parameters

commandstringrequired

The shell command to execute. Can include pipes, redirects, and compound statements.

timeoutnumber

Optional timeout in milliseconds. Defaults to 120,000ms (2 minutes). Maximum varies by configuration.

run_in_backgroundboolean

When true, runs the command in the background. The user is notified when it completes. Do not use & at the end when using this parameter.

descriptionstring

A clear, concise description of what the command does. Used for UI display and accessibility.

Working Directory Persistence

The working directory persists between commands via an internal tracking mechanism, but shell state (environment variables, aliases) does not persist between separate tool invocations. Each command runs in a fresh shell initialized from the user's profile.

Background Execution

Commands can be run in the background using run_in_background: true. Background tasks:

  • Are registered in the app state's task system
  • Produce notifications when they complete
  • Can be stopped via the TaskStop tool
  • Auto-background after 15 seconds in assistant mode (blocking budget)

Command Classification

BashTool classifies commands for UI purposes:

find, grep, rg, ag, ack, locate, which, whereis: collapsed in the UI as search operations.

Security

BashTool implements multiple security layers:

  • AST-based command parsing: Commands are parsed into an AST (utils/bash/ast.ts) for security analysis
  • Sandbox support: Commands can run inside a sandboxed environment via SandboxManager
  • Read-only validation: In plan mode, commands are checked against a read-only allowlist
  • Permission matching: Supports wildcard pattern matching for permission rules (e.g., git * matches any git command)
  • Destructive command warnings: Warns about irreversible operations
  • sed edit detection: Parses sed commands to detect file edits and apply write permission checks
  • UNC path blocking: On Windows, blocks UNC paths to prevent NTLM credential leaks

The progress threshold is 2 seconds. Commands that run longer than this show progress output in the UI. This helps users understand what long-running commands are doing.

Key Properties

  • Read-only: Depends on the command (analyzed per invocation)
  • Concurrency-safe: No
  • maxResultSizeChars: 100,000

PowerShellTool

The Windows equivalent of BashTool. Executes PowerShell commands on Windows systems.

Parameters

commandstringrequired

The PowerShell command or script to execute.

timeoutnumber

Optional timeout in milliseconds.

run_in_backgroundboolean

Run the command in the background.

descriptionstring

Description of what the command does.

Behavior

PowerShellTool mirrors BashTool's architecture but adapts for the PowerShell environment:

  • Uses the detected PowerShell path (cached at startup via getCachedPowerShellPath)
  • Classifies PowerShell-specific commands for UI collapsing:
    • Search: Select-String, Get-ChildItem (recursive), findstr, where.exe
    • Read: Get-Content, Get-Item, Test-Path, Get-Process, Get-Service, Format-Hex
    • Neutral: Write-Output, Write-Host
  • Resolves aliases to canonical cmdlet names for accurate classification
  • Shares the sandbox infrastructure with BashTool

Availability

PowerShellTool is only available when:

  • The platform is Windows, OR
  • PowerShell is explicitly enabled via configuration

Key Properties

  • Read-only: Depends on the command
  • Concurrency-safe: No

REPLTool

A sandboxed execution environment for Python and Node.js. Available in Anthropic's internal builds.

Architecture

REPLTool acts as a transparent wrapper around the primitive file and shell tools. When REPL mode is active:

  1. Primitive tools (FileRead, FileWrite, FileEdit, Glob, Grep, Bash, NotebookEdit, Agent) are hidden from direct model use
  2. These tools remain accessible inside the REPL VM context
  3. The model interacts with a single REPL tool that delegates to the underlying primitives

Tool Wrapping

The REPL VM context includes these primitive tools:

function getReplPrimitiveTools(): readonly Tool[] {
  return [
    FileReadTool,
    FileWriteTool,
    FileEditTool,
    GlobTool,
    GrepTool,
    BashTool,
    NotebookEditTool,
    AgentTool,
  ]
}

REPL mode provides a single entry point that the model uses to perform all file, search, and shell operations. This reduces context window usage from multiple tool schemas to one, while maintaining full functionality.

Key Properties

  • Availability: Internal (Anthropic) builds only
  • Concurrency-safe: No
  • Transparent wrapper: Yes (delegates rendering to inner tool progress)

Key Source Files

  • src/tools/BashTool/BashTool.tsx: BashTool implementation with command classification
  • src/tools/BashTool/bashSecurity.ts: Security analysis for shell commands
  • src/tools/BashTool/bashPermissions.ts: Permission matching for shell commands
  • src/tools/PowerShellTool/PowerShellTool.tsx: PowerShell implementation
  • src/tools/REPLTool/primitiveTools.ts: Primitive tools available inside the REPL VM
File Tools PreviousWeb ToolsNext