Tool System Reference

Read file contents with optional line ranges for large files. Works with all text formats. Essential for understanding code before modifications.

Use Cases:

• Reading configuration files before editing them
• Understanding existing implementation patterns in a codebase
• Reviewing test files to understand current coverage

Example:

# Read entire file
file_read("src/components/Button.tsx")

# Read specific range for large files
file_read("package-lock.json", start_line=1, max_lines=50)

Best Practices:

• Use line ranges for files over 500 lines to avoid context overload
• Read only the sections relevant to your current task
• For large files, use grep_content first to identify relevant line numbers before reading

Limits:

• Files larger than 256KB return only the first 256KB of content
• Very large files (>10,000 lines) should be read in sections to avoid context window exhaustion and slow response times

Precise text replacement using exact string matching. Supports multiple replacement operations and preserves file structure and formatting.

Use Cases:

• Updating function implementations with new logic
• Modifying configuration values across files
• Refactoring variable or function names

Best Practices:

• Ensure the old_text string is unique enough to avoid unintended matches
• Use multiple=true when renaming variables or making repeated changes
• Always verify file paths before editing to avoid modifying wrong files
• Use file_edit for targeted changes; for complete rewrites, use file_write instead

Create new files from scratch or completely replace existing file contents. Handles any text-based format.

Use Cases:

• Generating new components, modules, or configuration files
• Creating test files for new functionality
• Writing complete file rewrites when file_edit would be impractical

Best Practices:

• Double-check paths before writing to prevent accidental overwrites of important files
• Use only for new files or complete rewrites
• For partial modifications, prefer file_edit which is safer and more precise

Find files matching glob patterns like **/*.ts or src/**/*.js. Supports filtering by directory path, exclude patterns, and result limiting.

Use Cases:

• Finding all components of a specific type in a project
• Locating test files across the codebase
• Identifying configuration files scattered across directories

Example Patterns:

**/*.tsx          # All TypeScript React files
src/**/*.test.js  # All test files in src
**/config.*       # All config files anywhere

Best Practices:

• Use specific patterns to narrow scope (src/**/*.ts instead of **/*)
• Exclude large directories like node_modules to improve performance
• Set max_results to prevent overwhelming output on large codebases

# Good: Specific scope
glob("src/components/**/*.tsx", max_results=50)

# Less efficient: Too broad
glob("**/*")  # Returns thousands of results

Search file contents using regex patterns with context lines before and after matches. Supports case-insensitive searching and filtering by file type using glob patterns.

Use Cases:

• Finding function definitions and their implementations
• Locating API endpoint handlers across the codebase
• Searching for specific error messages or log statements

Example:

# Find authentication-related code
grep_content("auth.*login", glob="**/*.ts")

# Search with context lines
grep_content("TODO", glob="src/**", context_before=2, context_after=2)

Performance Tips:

• Literal string searches are faster than complex regex patterns
• Case-insensitive searches (case_sensitive=false) are slower
• Request only the context lines you actually need

List files containing pattern matches, returning only file paths without content. Faster than grep_content when you only need to know which files match. Supports regex patterns and glob filtering.

Use Cases:

• Identifying which files need refactoring before starting work
• Finding all files that import a specific module
• Locating files containing deprecated patterns or APIs

Recommended Workflow:

1. Use grep_file to quickly identify relevant files
2. Read specific files with file_read to examine details
3. Use grep_content only when you need surrounding context

Display directory hierarchy with configurable depth and exclude patterns to filter the output.

Use Cases:

• Understanding the overall structure of an unfamiliar project
• Verifying that directory organization matches expectations
• Finding specific subdirectories within a large codebase

Execute shell commands with configurable timeout, descriptive summaries, and support for command chaining via &&.

Use Cases:

• Running test suites and build processes
• Installing or updating dependencies
• Executing git operations (commit, push, pull)
• Running database migrations or scripts

Example:

# Clear summary and reasonable timeout
bash("npm test", timeout=60000, summary="Run Jest test suite")

# Chained dependent commands
bash("npm install && npm run build", timeout=120000)

Limits:

• Maximum timeout: 120 seconds (2 minutes, hard limit)
• Commands exceeding the timeout are automatically terminated
• Set explicit timeouts appropriate to expected execution time

Best Practices:

• Always provide clear summaries so the command's purpose is obvious
• Chain dependent commands with && to ensure proper sequencing
• Review destructive commands carefully before execution (rm, drop, truncate)

Security Considerations:

• Commands execute with your user permissions
• Never run commands from untrusted sources
• Use Plan Mode for review when working in shared codebases
• Avoid commands that might expose credentials or sensitive data

For operations exceeding 2 minutes:

• Break the work into smaller, sequential commands
• Run in background and check results separately
• Execute manually in your terminal for full control

Launch specialized subagents with isolated contexts to handle specific tasks without consuming main conversation context. Supports parallel execution for efficiency.

Built-in Subagent:

• @verifier: Quick validation checks for implementation logic, syntax verification, and isolated testing

Use Cases:

• Delegating research and validation to keep main context focused on development
• Running verification checks without cluttering the conversation
• Performing parallel code review and security assessment

Best Practices:

• Delegate validation and review tasks to preserve main context for active development
• Launch multiple subagents in parallel when tasks are independent
• Use subagents for isolated verification that doesn't need conversational continuity

Performance Benefits:

• Reduced total execution time through parallel processing
• Efficient resource utilization with automatic task orchestration
• No limits on the number of concurrent subagents

Context Management Strategy:

• Read files strategically, requesting only what's needed for the current task
• Offload validation and review work to subagents
• Monitor context consumption during long sessions
• Break complex operations into tracked steps with todo_update

Efficient Workflow Pattern:

1. Planning: Use glob/grep to identify the scope of changes needed
2. Reading: Read only the relevant files or sections
3. Execution: Delegate appropriate tasks to subagents
4. Verification: Run quick checks with @verifier subagent

Create and manage task lists to track progress through complex implementations. Supports status tracking (pending, in_progress, completed).

Use Cases:

• Breaking down complex implementations into manageable, trackable steps
• Maintaining visibility into progress across multi-file changes
• Coordinating multi-step workflows with clear status indicators

Query internet search engines with control over result count and freshness filtering to find recent information.

Use Cases:

• Finding official documentation for unfamiliar APIs or libraries
• Researching specific error messages to find solutions
• Checking current best practices and up-to-date recommendations

Retrieve web page contents and analyze them with specific queries to extract structured information.

Use Cases:

• Reading and extracting key information from documentation pages
• Analyzing API documentation to understand usage patterns
• Extracting code examples and implementation details from tutorials