Tools Quick Reference

​

Tool Tags

​

Categories

• Planning & Task Management (22 tools)
• File Operations (4 tools)
• Information Retrieval (1 tools)
• Workflow Management (16 tools)
• System & Execution (1 tools)
• Other Tools (5 tools)

​

Planning & Task Management

​

add_dependency

• blocks: from_task must complete before to_task can start
• related: informational link, no execution constraint
• parallel_with: explicitly marks tasks as parallelizable

• Task A blocks Task B: add_dependency(from_task=“A-id”, to_task=“B-id”, type=“blocks”) Means B cannot start until A completes.
• Tasks can run together: add_dependency(from_task=“A-id”, to_task=“B-id”, type=“parallel_with”) Explicitly marks A and B as safe to run in parallel.
• Informational link: add_dependency(from_task=“A-id”, to_task=“B-id”, type=“related”) No execution constraint, just documents a relationship.

​

add_task

• When you discover additional work that needs to be done
• When you encounter missing dependencies or prerequisites
• When breaking down complex work into more steps
• When pivoting approach requires new tasks

• Use parent_id to create subtasks under an existing task when you discover complexity
• Break down tasks that prove more complex than initially planned
• Create hierarchical task structures for better organization
• Each subtask inherits context from parent but can have specialized metadata

• Implementation agent finds task needs research → add subtask with preferred_agent: “research”
• Research agent discovers multiple integration points → add subtasks for each integration
• Any agent finds unfamiliar tech/patterns → add subtask with tool_hints: [“search_first”, “use_subagent”]
• Task requires multiple phases → add sequential subtasks with position ordering

• preferred_agent: Which agent should handle this (planning/research/implementation/debugging/tdd/finalize)
• tool_hints: Suggested tools to use [“use_bash”, “use_subagent”, “search_first”, “test_first”]
• dependencies: What this task depends on (packages, files, other tasks)
• notes: Important context or discoveries
• priority: high/medium/low

1. Complex Implementation Discovery: parent_id: “task_123”, title: “Research authentication patterns”, preferred_agent: “research”, notes: “Found unfamiliar OAuth flow”
2. Multi-Step Breakdown: parent_id: “task_456”, title: “Setup database schema”, position: 1 parent_id: “task_456”, title: “Create migration scripts”, position: 2
3. Cross-Agent Coordination: parent_id: “task_789”, title: “Write integration tests”, preferred_agent: “tdd”, dependencies: [“API endpoints complete”]

• Add tasks as soon as you discover they’re needed
• Use parent_id when expanding existing tasks that prove complex
• Include metadata hints for better execution
• Position subtasks logically in sequence
• Use descriptive titles and comprehensive descriptions
• Create subtasks for different agent specializations when needed

​

bash_list

• Processes are scoped to the current workspace (worktree)
• Multiple chats in the same workspace share the same process list
• This enables coordination: one chat can start a server, another can check its status
• Use BashOutput to view output and BashKill to terminate any workspace process

• By default, shows only running processes in the current workspace
• Use ‘all: true’ to include completed, failed, and killed processes
• Process IDs can be used with BashOutput and BashKill tools

• Running processes: Shows ID, command, and how long they’ve been running
• Completed processes: Shows ID, command, exit code, and duration
• Failed processes: Shows ID, command, exit code, and error indication

1. List running processes: bash_list()
2. List all processes including completed: bash_list(all=true)

​

bash_output

• Can read output from any process in the current workspace, regardless of which chat started it
• Multiple chats in the same workspace share process visibility
• This enables monitoring: check on servers or builds started by other chats

• Process IDs are provided when you start a background process with run_in_background: true
• The tool will indicate if the process is still running or has completed
• If the process has completed, the exit code will be provided
• Output is not cleared after reading - you can re-read from any position

1. Standard Pagination (default):
   • offset: Start reading from byte N (default: 0)
   • limit: Read up to N bytes (default: 16000)
   • Can be combined: offset + limit
2. Tail Mode:
   • tail: Get last N lines
   • Cannot be combined with: regex, offset, limit
3. Regex Filter Mode:
   • regex: Filter output to lines matching pattern
   • When set, tool filters FIRST, then applies offset/limit to filtered results
   • Can be combined with: offset, limit, regex_case_insensitive, regex_context_before, regex_context_after
   • Cannot be combined with: tail
   • Optional parameters:
     • regex_case_insensitive: Case-insensitive matching
     • regex_context_before: Include N lines before match (like grep -B)
     • regex_context_after: Include N lines after match (like grep -A)

• offset + limit (standard pagination)
• tail (alone)
• regex (alone)
• regex + offset + limit (filtered pagination)
• regex + regex_case_insensitive + regex_context_before + regex_context_after

• tail + regex
• tail + offset
• tail + limit
• regex_case_insensitive without regex
• regex_context_before/after without regex

1. Start a background process: bash(command=“npm run dev”, run_in_background=true)
2. Get first chunk: bash_output(process_id=“<id>”)
3. Get next chunk: bash_output(process_id=“<id>”, offset=16000)
4. Get last 100 lines: bash_output(process_id=“<id>”, tail=100)
5. Filter for errors: bash_output(process_id=“<id>”, regex=“ERROR|FATAL”)
6. Filter with context: bash_output(process_id=“<id>”, regex=“ERROR”, regex_context_after=3)
7. Filter and paginate: bash_output(process_id=“<id>”, regex=“WARN”, offset=0, limit=10000)

• has_more: true if more output is available
• next_offset: where to start reading for the next chunk
• total_available: total bytes available in the (filtered or original) output
• filter_applied: true if regex was used
• total_matches: number of matching lines (when filtered)
• matches_in_response: number of matches in this chunk

​

bash_wait

• Waiting for a long build, test suite, or install to finish
• Any time the next thing you do depends on a background process being done

• A long-running server you never expect to exit (use bash_output to check on it)
• You only want progress so far, not completion (use bash_output)

1. Start the work in the background: bash(command=“npm test”, run_in_background=true)
2. Do any useful work that does not depend on the result — read the next file, prepare the following edit. The process runs while you do.
3. Wait for it: bash_wait(process_id=“<id>”)

• Exit code and status once the process has exited
• The last tail_lines lines of output (default 50), so a passing build or a failing test usually needs no follow-up call
• timed_out: true, with no exit code, if the budget elapsed first

​

component_library

• Building any UI — search for relevant components first
• Creating charts or diagrams — components handle all coordinate math
• Building pitch deck slides — use deck components as templates
• Need a layout pattern — search by use case (dashboard, landing, portal, crm)
• Building CRUD/admin interfaces — badge, modal, tabs, pagination, toast, etc.

• search: Find components with unified keyword search Examples: search(query=“crud table admin”), search(query=“chart dashboard”), search(tag=“deck”)
• get: Retrieve full source code for a specific component Example: get(name=“quadrant_chart”)
• install: Write a component file to disk at the given path Example: install(name=“sidebar_left”, path=“src/components/layouts/sidebar_left.tsx”)
• list: Browse all components (optionally filtered by tag or category)

• forge_integrated: Set to true in forge-generated projects to get integration guidance for useUiStore, useEventBus, and useAuth

​

create_plan

• AFTER you preform your initial research and analyze the problem.
• Use this tool when you need to organize complex work into structured steps
• You typically should create plans AFTER your findings. Avoid creating tasks to research, explore, identify, or search through the codebase. You should first perform your research so you can create an informed plan.
• ESPECIALLY when you are going to delegate. If you are about to spawn sub-agents, plan first: the task graph is what tells you which of them can run at the same time. An orchestrator that spawns without a plan has no record of what is independent, and ends up delegating one agent at a time.

• Title: Clear, concise title for the plan
• Description: Detailed description including:
  • Main objective
  • Approach/strategy
  • Alternative approaches (if applicable)
  • Success criteria
• Complexity: simple|moderate|complex
• Tasks: List of tasks with title, description, optional metadata, and optional dependencies
• The plan will be associated with the current session

• task_position: The 1-indexed position of another task in the tasks array
• type: “blocks” (the other task must COMPLETE first — a real data dependency), “related” (informational only), or “parallel_with” (emphasis that two tasks are safe together; rarely needed, since anything without a “blocks” edge already is)

tasks: [
{title: "Design schema"},
{title: "Implement API",       dependencies: [{task_position: 1, type: "blocks"}]},
{title: "Implement worker",    dependencies: [{task_position: 1, type: "blocks"}]},
{title: "Implement frontend",  dependencies: [{task_position: 1, type: "blocks"}]},
{title: "End-to-end tests",    dependencies: [
{task_position: 2, type: "blocks"},
{task_position: 3, type: "blocks"},
{task_position: 4, type: "blocks"}]}
]
Tasks 2, 3 and 4 all wait on the schema and on nothing else, so once it lands
all three are ready together and should be delegated in ONE turn.

tasks: [
{title: "Write migration"},
{title: "Regenerate ORM from applied schema", dependencies: [{task_position: 1, type: "blocks"}]}
]

• preferred_agent: Which agent should handle this task
• tool_hints: Suggested tools to use
• dependencies: Informational dependency notes (free-form text)
• notes: Important context
• priority: high/medium/low

• Break down work into clear, actionable tasks
• Cut tasks along boundaries that do not overlap (package, module, directory), so independent tasks can be worked at the same time without collisions
• Use inline dependencies to define the task graph upfront, and add “blocks” ONLY where one task genuinely consumes another’s output
• Include a mini-roadmap in the description
• Document alternative approaches for pivoting
• Be specific about what needs to be done
• Consider edge cases and potential blockers
• Consider changing state in parallel with plan creation, if states are available.

​

create_subtask

• When breaking down a complex task into smaller steps
• To add more granular tracking
• When discovering additional work while implementing

• Keep subtasks focused and specific
• Use subtasks for logical groupings of work
• Don’t create too many levels of nesting

​

fetch

• Use when you need to download content from a URL
• Helpful for retrieving documentation, API responses, or web content
• Useful for getting external information to assist with tasks

• Provide the URL to fetch content from
• Specify the desired output format (text, markdown, or html)
• Optionally set a timeout for the request

• Automatic content extraction using Mozilla Readability (strips nav, ads, footers)
• Supports three output formats: text, markdown, and html
• Automatically handles HTTP redirects
• Detects likely JavaScript-rendered pages and warns you
• Sets reasonable timeouts to prevent hanging

• max_size: Maximum bytes to fetch (default: 16000, ~16KB) Prevents downloading huge files that could overwhelm context

• Cannot render JavaScript. Single-page apps (SPAs) will return little or no content. The response metadata will include possible_js_rendered=true when this is detected. For JS-heavy sites, consider using browser tools instead.
• Default maximum response size is 16KB (use max_size to adjust)
• Only supports HTTP and HTTPS protocols
• Cannot handle authentication or cookies
• Some websites may block automated requests

• For GitHub repos, use raw.githubusercontent.com URLs instead of github.com (e.g., https://raw.githubusercontent.com/org/repo/main/README.md)
• For API docs that are JS-rendered SPAs, look for the OpenAPI/Swagger JSON spec URL instead
• Use text or markdown format for documentation (html returns raw markup with all chrome)
• If the response says possible_js_rendered=true, the page needs JavaScript to render. Try finding an alternative URL, a raw content source, or use browser tools.
• Adjust max_size for larger documents (but consider context limits)

• content_length: Size of the extracted content
• raw_html_size: Size of the original HTML before extraction (for HTML pages)
• truncated: Whether content was truncated to fit max_size
• encoding_used: The format that was applied
• page_title: Page title extracted by Readability (when available)
• possible_js_rendered: True if the page appears to be JavaScript-rendered (very little content extracted)
• used_readability: True if Readability content extraction was applied

​

get_plan

• When you need to review the current plan
• To check plan status and progress
• To understand what needs to be done

• Plan details including title, description, status, and complexity
• Returns error if no plan exists for the session

​

list_ready_tasks

1. Its status is “pending” (not started yet)
2. All tasks that block it (via ‘blocks’ dependencies) have status “completed”

• List of ready tasks with their details
• Total count of ready tasks vs total pending

​

list_tasks

• When you need to see all tasks in the plan
• To check task progress and status
• To understand what work needs to be done
• BEFORE delegating: the ready set tells you what can be worked at once

• List of all tasks with their status, title, and hierarchy
• Tasks are ordered by position and show parent-child relationships
• Assignee for any task that has been claimed, so you can see what other agents are already working on and avoid handing out the same task twice
• A count of tasks that are READY (pending with no incomplete blocker). Ready tasks have no dependency between them, so they are meant to be delegated together in one turn rather than one after another.

​

load_tool

• Load a specific tool by name: {"name": "sourcegraph"}
• Search for tools by keyword: {"query": "workflow"}

​

project_analyzer

​

read_attachment

• When the conversation references an attachment (by id) whose contents you have not yet seen.
• Specifically for PDF attachments: their pages are read on demand through this tool.

• Provide the attachment_id from the attachment reference.
• For PDFs: use the pages parameter to read a page range (e.g. “1-5”). PDFs larger than 10 pages require a page range; max 20 pages per request.

• PDF pages are returned as a native document block the model can read directly (text and layout).
• Image and text attachments are already provided inline in the conversation and do not need this tool.

​

remove_dependency

​

skill

• section: fetch one markdown section by heading. Preferred — every load lists the skill’s sections, so this is usually one targeted call rather than guessing byte ranges.
• offset / limit: page through the current view by byte range.
• regex (+ regex_case_insensitive, regex_context_before, regex_context_after): deliver only matching lines, numbered, to locate content before fetching it.

​

sourcegraph

• Use when you need to find code examples or implementations across public repositories
• Helpful for researching how others have solved similar problems
• Useful for discovering patterns and best practices in open source code

• Provide a search query using Sourcegraph’s query syntax
• Optionally specify the number of results to return (default: 10)
• Optionally set a timeout for the request

• Basic search: “fmt.Println” searches for exact matches
• File filters: “file:.go fmt.Println” limits to Go files
• Repository filters: “repo:^github.com/golang/go$ fmt.Println” limits to specific repos
• Language filters: “lang:go fmt.Println” limits to Go code
• Boolean operators: “fmt.Println AND log.Fatal” for combined terms
• Regular expressions: “fmt.(Print|Printf|Println)” for pattern matching
• Quoted strings: ""exact phrase"" for exact phrase matching
• Exclude filters: “-file:test” or “-repo:forks” to exclude matches

• Repository filters:
  • “repo:name” - Match repositories with name containing “name”
  • “repo:^github.com/org/repo$” - Exact repository match
  • “repo:org/repo@branch” - Search specific branch
  • “repo:org/repo rev:branch” - Alternative branch syntax
  • “-repo:name” - Exclude repositories
  • “fork:yes” or “fork:only” - Include or only show forks
  • “archived:yes” or “archived:only” - Include or only show archived repos
  • “visibility:public” or “visibility:private” - Filter by visibility
• File filters:
  • “file:.js$” - Files with .js extension
  • “file:internal/” - Files in internal directory
  • “-file:test” - Exclude test files
  • “file:has.content(Copyright)” - Files containing “Copyright”
  • “file:has.contributor([email protected])” - Files with specific contributor
• Content filters:
  • “content:“exact string"" - Search for exact string
  • “-content:“unwanted"" - Exclude files with unwanted content
  • “case:yes” - Case-sensitive search
• Type filters:
  • “type:symbol” - Search for symbols (functions, classes, etc.)
  • “type:file” - Search file content only
  • “type:path” - Search filenames only
  • “type:diff” - Search code changes
  • “type:commit” - Search commit messages
• Commit/diff search:
  • “after:“1 month ago"" - Commits after date
  • “before:“2023-01-01"" - Commits before date
  • “author:name” - Commits by author
  • “message:“fix bug"" - Commits with message
• Result selection:
  • “select:repo” - Show only repository names
  • “select:file” - Show only file paths
  • “select:content” - Show only matching content
  • “select:symbol” - Show only matching symbols
• Result control:
  • “count:100” - Return up to 100 results
  • “count:all” - Return all results
  • “timeout:30s” - Set search timeout

• “file:.go context.WithTimeout” - Find Go code using context.WithTimeout
• “lang:typescript useState type:symbol” - Find TypeScript React useState hooks
• “repo:^github.com/kubernetes/kubernetes$ pod list type:file” - Find Kubernetes files related to pod listing
• “repo:sourcegraph/sourcegraph$ after:“3 months ago” type:diff database” - Recent changes to database code
• “file:Dockerfile (alpine OR ubuntu) -content:alpine:latest” - Dockerfiles with specific base images
• “repo:has.path(.py) file:requirements.txt tensorflow” - Python projects using TensorFlow

• “term1 AND term2” - Results containing both terms
• “term1 OR term2” - Results containing either term
• “term1 NOT term2” - Results with term1 but not term2
• “term1 and (term2 or term3)” - Grouping with parentheses

• Only searches public repositories
• Rate limits may apply
• Complex queries may take longer to execute
• Maximum of 20 results per query

• Use specific file extensions to narrow results
• Add repo: filters for more targeted searches
• Use type:symbol to find function/method definitions
• Use type:file to find relevant files

​

update_plan

• When you need to modify the plan based on new information
• When pivoting to a different approach
• When marking a plan as completed or cancelled

• Title: Update the plan title
• Description: Add new information, document pivots
• Status: pending|in_progress|completed|cancelled
• Complexity: simple|moderate|complex

• Document why changes are being made
• Keep the description updated with current approach
• Use this to track progress and pivots

​

update_task

• When starting work on a task (mark as in_progress)
• When completing a task (mark as completed)
• When a task is blocked or failed
• To update task description with findings
• To add notes, hints, or discoveries to metadata
• To claim a task by setting assignee + in_progress

• pending: Not started yet
• in_progress: Currently working on it
• completed: Successfully finished
• failed: Could not complete
• blocked: Waiting on something (add blocker to notes)
• skipped: Decided not to do
• cancelled: No longer needed

• Free-form text identifying who is working on this task
• Use a descriptive label: spawn title, role name, or agent identifier
• Claim pattern: update_task(task_id=“X”, status=“in_progress”, assignee=“researcher-auth”)
• Other agents see assignments in list_tasks and skip claimed work

• notes: Add discoveries, blockers, or important context
• preferred_agent: Suggest which agent should handle this
• tool_hints: Suggest tools to use [“use_bash”, “search_first”]
• dependencies: Document what this depends on
• next_steps: What to do after this task

• Update status when you start and finish tasks
• Add descriptions to document what was done
• Use metadata.notes for blockers when marking as blocked
• Add tool_hints for complex tasks to guide future execution
• Set assignee when claiming a task to prevent duplicate work

​

view

• Reading contents of specific files (source code, configs, logs)
• Examining text-based file formats

• Provide the file path
• Optional: offset (starting line) and limit (number of lines)
• For PDFs: use the pages parameter to read a page range (e.g. “1-5”). PDFs larger than 10 pages require a page range; max 20 pages per request.
• Issue multiple view tools in a single request for improved performance

• Displays file contents with line numbers for easy reference
• Can read from any position in a file using the offset parameter
• Handles large files by limiting the number of lines read
• Automatically truncates very long lines for better display
• Suggests similar file names when the requested file isn’t found

• Maximum output size is 64KB (~16K tokens) - larger files are truncated with head+tail
• Default reading limit is 1500 lines, which reads most source files whole
• Lines longer than 500 characters are truncated
• Cannot display binary files (executables, archives, etc.)
• Images up to 5MB are supported (JPEG, PNG, GIF, BMP, SVG, WebP)
• PDFs up to 5MB are supported; large PDFs are read a page range at a time via the pages parameter

• Prefer ONE whole-file read over several paged reads: each call costs a model round-trip, while the read itself takes milliseconds. Omit offset/limit unless the file is genuinely too big to arrive in one piece.
• A file OVER ~64KB cannot arrive whole whatever limit you pass — the response is capped and you get head+tail with the middle removed. Two calls settle it, and neither is a search: read the head (default) to get the shape, then ONE offset read for the region you need. The truncation notice tells you the total line count, so you can aim the second call directly.
• Do NOT fall back to repeated ‘grep’ on a large file to page through it by symbol. Measured: eleven agents greping one 52KB proto one message at a time was the single largest recoverable cost in a long run — each grep is a whole turn and returns less context than one offset read.
• Issue several view calls in a SINGLE message to read independent files at once
• Use with Glob tool to first find files you want to view
• For code exploration, first use Grep to find relevant files, then View to examine them
• If output is truncated, use offset to read the remaining section

​

websearch

• Finding current information not available in the assistant’s training data
• Researching documentation, tutorials, or examples online
• Looking up error messages or debugging information
• Finding libraries, tools, or frameworks
• Checking current status of services or projects
• Discovering recent developments or news about technologies

• Provide a search query as you would in a web browser
• Optionally specify the number of results (default: 10, max: 20)

• Use simple, natural language queries with specific keywords
• Keep queries short and focused (3-8 words works best)
• Use minus (-) to exclude terms: python tutorial -django
• Quotes work for simple exact phrases: “react hooks” tutorial

• Boolean operators: OR, AND (e.g. “PUT” OR “POST” will FAIL)
• Complex quoted phrase combinations (multiple quoted phrases with operators)
• site: operator is unreliable and often returns no results
• filetype: operator is unreliable If you need boolean-style searches, run multiple simple queries instead.

• “golang context timeout example” - Simple keywords
• “anthropic claude api documentation” - Natural language
• “Customer.io transactional API” - Product + feature
• “react hooks tutorial 2024” - Topic + timeframe

• “PUT” OR “POST” OR “PATCH” email content - Boolean operators don’t work
• site:customer.io/docs/api specific-page - site: is unreliable
• “exact phrase 1” OR “exact phrase 2” - Complex boolean combos fail

• Start with broad queries, then narrow based on results
• If a search returns 0 results, SIMPLIFY the query - don’t add complexity
• After 3-4 searches on the same topic, synthesize what you have rather than keep searching
• For API documentation, search for the official SDK/client library on GitHub instead
• For GitHub content, prefer fetching raw.githubusercontent.com URLs over github.com

• Title: The title of the search result
• Description: A brief description/snippet from the page
• URL: The link to the resource

• Maximum of 20 results per query
• May have rate limits if used excessively
• DuckDuckGo HTML search has limited query syntax (see above)
• Results may be less comprehensive than Google for niche technical queries

• Start with fewer results (5-10) for faster responses
• Use specific queries to get more relevant results
• Combine with the fetch tool to retrieve full page content from results

​

File Operations

​

edit

• Precise text replacements
• Creating a new file (empty old_string)
• Deleting specific content (empty new_string)
• Renaming a variable/function (with replace_all)

• Moving/renaming files: Use Bash mv command

• Insufficient context in old_string (needs 3-5 lines)
• Forgetting whitespace/indentation must match exactly
• Not checking if text appears multiple times

​

Replace Text

​

Multiple Edits

​

Create New File

​

Delete Content

​

Rename Variable

​

CRITICAL REQUIREMENTS

1. UNIQUENESS (when replace_all=false):
   • Include 3-5 lines of context BEFORE
   • Include 3-5 lines of context AFTER
   • Match whitespace/indentation EXACTLY
2. VERIFICATION CHECKLIST: Check how many times text appears Include enough context for uniqueness Verify parent directories exist (new files)
3. FAILURE CONDITIONS:
   • old_string not found → FAILS
   • Multiple matches (without replace_all) → FAILS
   • Whitespace mismatch → FAILS

​

BEST PRACTICES

• Include ample context
• Use replace_all for systematic renames
• Parallelize independent edits as separate calls in one message
• Verify edits don’t break code

​

WORKS WELL WITH

• AFTER: Bash (test changes)
• ALTERNATIVE: Write (complete rewrite)

​

PARAMETERS

• file_path: Absolute path (required)
• old_string: Text to find (exact match)
• new_string: Replacement text
• replace_all: Replace all occurrences (optional)

​

find_replace

• Renaming variables, functions, or classes across multiple files
• Updating imports or module references project-wide
• Fixing consistent typos or naming conventions
• Batch updating configuration values
• Refactoring patterns across the codebase WHEN NOT TO USE:
• Single file edits: Use Edit tool instead
• Complex structural changes: Use Patch tool
• Context-dependent replacements: Use Edit or Patch for precision FEATURES:
• Glob pattern file filtering (e.g., ”**/*.js”, “src/**/*.{ts,tsx}”)
• Regular expression support with capture groups
• Case-insensitive matching option
• Preview mode to see changes before applying
• Automatic file history tracking USAGE PATTERNS:

​

Preview First (Recommended)

​

Simple Text Replacement

​

Regex with Capture Groups

​

Case-Insensitive Replacement

​

CRITICAL REQUIREMENTS

1. PREVIEW FIRST:
   • ALWAYS call with preview=true first to verify the pattern matches and scope
   • Preview shows diffs of what would change without modifying any files
   • After reviewing the preview, call again without preview to apply
2. FILE READING:
   • Checks modification times to prevent conflicts
   • Validates file access permissions
3. PATTERN MATCHING:
   • Literal text matching by default
   • Regex patterns with use_regex=true
   • Case sensitivity controlled by ignore_case
4. SAFETY CHECKS:
   • Atomic operation (all or nothing)
   • Preserves file history

​

BEST PRACTICES

• ALWAYS use preview=true first to see what changes would be made
• Use specific file globs to limit scope
• Review the preview diffs carefully before applying
• Test regex patterns with preview before committing

​

WORKS WELL WITH

• BEFORE: preview=true (see changes first)
• BEFORE: Grep (find occurrences)
• AFTER: Bash (run tests)
• ALTERNATIVE: Edit (single file)
• ALTERNATIVE: Patch (complex multi-file edits)

​

PARAMETERS

• find_pattern: Text or regex pattern to find (required)
• replace_text: Replacement text (required)
• file_glob: File filter pattern (optional, defaults to all files)
• ignore_case: Case-insensitive matching (optional, default false)
• use_regex: Treat pattern as regex (optional, default false)
• preview: Preview mode - show what would change without applying (optional, default false) Remember: Use preview=true first, then apply.

​

move_code

• Reorganizing code within a file
• Moving a function/method to a different file
• Extracting code into a new location
• Copying code snippets between files
• Reordering functions in a file

• For simple cut/paste of small text - use edit tool
• For renaming across files - use find_replace tool
• For complex multi-file refactors - consider using the refactor agent

1. Extracts lines source_start to source_end from source_file
2. Inserts the extracted code AFTER target_line in target_file
3. If operation is “move” (default), deletes the original lines from source
4. If operation is “copy”, keeps the original lines

​

Move function to end of file

{
"source_file": "/path/to/file.go",
"source_start": 50,
"source_end": 75,
"target_file": "/path/to/file.go",
"target_line": 200,
"operation": "move"
}

​

Copy code block to another file

{
"source_file": "/path/to/original.go",
"source_start": 10,
"source_end": 30,
"target_file": "/path/to/new_file.go",
"target_line": 15,
"operation": "copy"
}

​

Insert at beginning of file

{
"source_file": "/path/to/source.go",
"source_start": 100,
"source_end": 120,
"target_file": "/path/to/target.go",
"target_line": 0,
"operation": "move"
}

1. Line numbers are 1-indexed
2. source_start and source_end are INCLUSIVE
3. target_line = 0 inserts at the very beginning
4. For same-file moves, the tool handles line number shifts automatically

• For same-file moves, be aware that line numbers shift after the operation
• Add blank lines in the extracted code if needed for proper spacing
• Check for any imports/dependencies that might need to be added to target file

​

write

• Creating new files or updating existing files
• Saving generated code, configurations, or text data

• Provide the file path and content to write
• Parent directories are created automatically

• Creates new files or overwrites existing ones
• Auto-creates parent directories
• Checks for external modifications for safety
• Avoids unnecessary writes when content unchanged

• Cannot append (rewrites entire file)
• Replaces the ENTIRE file — to change part of one, prefer Edit

• Just write over it. Do NOT delete it first — that costs an extra turn and removes the very guard that protects you.
• Reading it first is optional, not required. An unread file is overwritten and the result carries a diff of what was replaced (capped at 60 lines) so you can repair a mistaken clobber with Edit.
• Reading it first is what ARMS the safety check: once you have read a file, a Write is REJECTED if it changed on disk since. That is how you find out another agent owns the file too. Read first when that matters — a shared file, a concurrent run — and report the rejection rather than re-issuing the Write.

• A turn costs a full model generation whether it carries one write or six, so the TURN COUNT is the cost, not the file count. Issue every write whose content you ALREADY HOLD in ONE message; they run in parallel.
• The exception is a write whose content depends on a previous write’s result. That one waits for it.

• Use the LS tool to verify the correct location when creating new files
• Combine with Glob and Grep tools to find and modify multiple files
• Always include descriptive comments when making changes to existing code

​

Information Retrieval

​

bash

​

WHEN NOT TO USE THIS TOOL

• File editing → Use Edit/Write tools
• File reading → Use View tool

​

🔎 SEARCHING THE CODEBASE

​

Go — ‘gopls’ (for Go packages)

​

Other languages

• Otherwise use ‘rg’ when available, falling back to ‘grep -r’ / ‘find’ when it is not.
• ALWAYS search from a relative path (‘rg pattern .’, ‘rg pattern internal/’), never an absolute root.
• Exclude vendored trees, which are large and rarely what you want: rg —glob ‘!node_modules’ —glob ‘!.git’ —glob ‘!dist’ —glob ‘!vendor’ (‘rg’ already honours .gitignore, which usually covers these.)
• Bound the results: ‘rg -l’ for filenames only, ‘rg -m 20’, or pipe to ‘head’. An unbounded match dump can exhaust the output budget on a large repo.
• ⚠️ ‘rg -r’ IS NOT RECURSIVE — do not reach for it out of grep habit. In rg, -r is —replace, so ‘rg -r pattern .’ silently treats your PATTERN as the replacement text and the next argument as the pattern, printing rewritten lines that look like real matches. rg already searches recursively by default, so the flag you want is no flag at all: ‘rg pattern .’.
• Other flags that differ from grep: -t/-T select file TYPES (‘rg -t go’), not the grep meanings, and -f reads patterns from a file.

​

🚫 NEVER SCAN THE FILESYSTEM

• To find something in the project → search a relative path, as above.
• To find a DEPENDENCY’s source on disk → ask the package manager, do not scan: ‘go list -m -f "" <module>’, ‘go env GOMODCACHE’, ‘npm root’.
• If you truly need a filesystem search, name a specific directory.

​

⛓️ CHAIN PROBES — ONE CALL ANSWERS MANY QUESTIONS

​

Output Processing

• Default output limit is 16000 bytes (use max_output to customize)
• Use tail_lines to get only the last N lines of output
• Output metadata includes truncation info and original size

• The command argument is required.
• You can specify an optional timeout in milliseconds (up to 600000ms / 10 minutes). If not specified, commands will timeout after 60 seconds.
• Use ‘run_in_background: true’ to run long-running commands in the background. You can then use BashOutput to check output, BashKill to terminate, and BashList to see all running processes.
• Searching the codebase IS a use of this tool (prefer ‘rg’, scoped to a relative path — see above). For reading whole files, prefer the View tool over ‘cat’/‘head’/‘tail’.
• VERY IMPORTANT: YOU MUST AVOID WRITING FILES USING SHELL. Please use the appropriate edit and create tools.
• When issuing multiple commands, use the ’;’ or ’&&’ operator to separate them. DO NOT use newlines (newlines are ok in quoted strings).

• IMPORTANT: Each command runs in a fresh, stateless shell. Environment variables and directory changes from previous commands do NOT persist.
• IMPORTANT: The current working directory is ALWAYS automatically set to the current worktree. There is NO need to cd to the worktree before running commands - just run them directly.
• To change to a subdirectory within the worktree, use ‘cd’ as part of a compound command (e.g., ‘cd subdir && npm test’).
• Environment variables set in prior shell sessions will NOT be included. Use the ‘env’ parameter to set environment variables for a specific command execution.
• If you need to maintain state across commands (e.g., activating a virtual environment), combine commands with && or ; operators.
• Background processes run in separate shell instances and also start fresh without inherited state.

pytest /foo/bar/tests

cd /foo/bar && pytest tests

• Return an empty response - the user will see the output directly
• Never update git config

​

Workflow Management

​

create_workflow

• name: (optional) Workflow name. A random name is generated if omitted.
• content: (optional) Complete workflow YAML. The default agent template is used if omitted.

{}

{
"name": "my-review-workflow",
"content": "name: my-review-workflow\nentry: [agent]\nnodes:\n  - id: agent\n    type: call_llm"
}

​

delete_scenario

​

edit_scenario

{
"name": "happy_path",
"old_string": "outcome: completed",
"new_string": "outcome: error"
}

​

edit_workflow

• Adding or modifying a node
• Updating an edge condition
• Changing input parameters

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"old_string": "  - id: agent\n    type: call_llm",
"new_string": "  - id: agent\n    type: call_llm\n    model: \"{{inputs.model}}\""
}

​

get_cel_reference

• When writing conditions, args, or dynamic values in workflows
• To understand available namespaces and their fields
• To see available custom functions

• All namespaces (inputs, workflow, nodes, iter, output, outputs)
• Field documentation for each namespace
• Custom functions (parseJson, coalesce, etc.)
• Common patterns and examples

​

get_preset

• To view preset configurations
• To understand what a preset provides
• To copy and adapt preset settings

• name: The preset name (from list_presets)

​

get_schema

• When you see a field type like “thread: ThreadConfig” and need details
• When you need to understand node output structure (e.g., CallLLMOutput)
• To explore top-level types (Workflow, Edge)
• To get full field documentation for any type

• Node types: call_llm, loop, workflow, run, execute_tools, join, etc.
• Input types: string, number, boolean, enum, model, message, etc.
• Config types: ThreadConfig, SaveMessageConfig, ProjectConfig, ResponseTool, etc.
• Output types: CallLLMOutput, ExecuteToolsOutput, RunOutput, LoopOutput, etc.
• Top-level: Workflow, Edge, EdgeCase

• get_schema(name=“call_llm”) // Node type
• get_schema(name=“ThreadConfig”) // Config type
• get_schema(name=“CallLLMOutput”) // Output structure
• get_schema(name=“Workflow”) // Top-level workflow structure
• get_schema(name=“Edge”) // Edge routing structure

​

get_workflow

• To view the current state of the workflow you’re editing
• Before making edits to understand the structure

• id: (required) Workflow draft UUID

​

get_workflow_suggestions

• Before starting a new workflow design
• When encountering complexity or unexpected behavior
• To learn best practices for edges, joins, loops, and conditions

• Structure and organization
• Edge routing patterns
• Node vs edge conditions
• Join behavior with conditional sources
• Loop patterns and outputs
• Testing strategies

​

list_presets

• To discover available presets for agent configurations
• To find the right preset for a specific task
• Before using get_preset to view details

​

list_scenarios

​

list_workflows

• To discover available workflows
• To find workflow patterns for common use cases
• Before using get_workflow to view details

​

run_scenario

​

view_scenario

​

write_scenario

• node: node_id # Optional: target specific node output: # Mock output for the node message: role: assistant text: “Hello!” response_text: “Hello!” expect: outcome: completed # or “error” reached: [“node1”, “node2”] not_reached: [“node3”]

• Top-level nodes: node: “call_llm”
• Inner loop nodes: node: “agent_loop.call_llm” (dot-separated)
• Nested loops: node: “outer_loop.inner_loop.call_llm”

{
"id": "workflow-uuid",
"name": "happy_path",
"content": "name: happy_path\ndescription: Test happy path\nevents:\n  - output:\n      message:\n        role: assistant\n        text: Hello!\n      response_text: Hello!\nexpect:\n  outcome: completed"
}

​

write_workflow

{
"id": "550e8400-e29b-41d4-a716-446655440000",
"content": "name: my-workflow\nentry: [agent]\nnodes:\n  - id: agent\n    type: call_llm"
}

• name: Workflow name
• entry: List of entry point node IDs
• nodes: Array of node definitions
• edges: Array of edge definitions (optional for single-node workflows)

• id: (required) Workflow draft UUID.
• name: (optional) Overrides the name in YAML. Used for display name.
• content: (required) Complete workflow YAML content.
• expected_version: (optional) Version number for conflict detection.

​

System & Execution

​

bash_kill

• Can kill any process in the current workspace, regardless of which chat started it
• Multiple chats in the same workspace share process visibility
• This enables coordination: one chat can stop a server started by another

• Process IDs are provided when you start a background process with run_in_background: true
• You can only kill processes that are currently running
• After killing a process, its output is still available via BashOutput
• Use BashList to see all running background processes in the workspace

1. Start a background process: bash(command=“npm run dev”, run_in_background=true)
2. Kill the process: bash_kill(process_id=“<id-from-step-1>”)

​

Other Tools

​

ask_user

1. Clarify ambiguous instructions
2. Get user preferences or decisions
3. Offer choices about implementation direction
4. Confirm before taking significant actions

• The user will always have an option to provide freetext input in addition to any predefined options.
• If you recommend a specific option, list it first and add “(Recommended)” to the label.
• Use allow_multiple: true when choices are not mutually exclusive.
• Group related questions in a single call (up to 4 questions).

​

metadata_writer

​

spawn_send

​

spawn_status

• Only shows/waits on agents YOU spawned (your direct children), never a sibling’s or another thread’s sub-agents.

1. LISTING (omit agent_id): returns every sub-agent you spawned — agent_id, title, preset, status, elapsed time, last activity time, turn count, and whether it appears gated on a question or approval (best-effort — this signal can be unavailable and is never a hard guarantee).
2. SINGLE AGENT (agent_id set): returns that agent’s status and its LAST ASSISTANT MESSAGE — “is it done, and what did it say?” without cancelling it.

​

worktree

• Creating isolated development environments for features/bugs
• Setting up parallel workspaces for agents
• Managing multiple concurrent work streams ACTIONS:

1. create - Create a new git worktree Required: name Optional: branch, base_branch, copy_files, force, session_id
2. list - List all worktrees No parameters required
3. get - Get details of a specific worktree Required: name
4. delete - Delete a worktree Required: name

• Worktree information is automatically stored in CEL context as ‘worktree_data’
• Available fields: id, name, path, branch, base_branch, repo_id
• Use in subsequent steps: worktree_data.path, worktree_data.branch, etc.

• copy_files: Searches recursively for matching files (e.g., “.env” finds all .env files in any directory)
• Directory structure is preserved (frontend/.env -> worktree/frontend/.env)

{
"action": "create",
"name": "feature-auth",
"base_branch": "main",
"copy_files": [".env", ".env.local"]
}

{
"action": "list"
}

• Worktree paths are stored in ~/.reliant/worktrees/<repo_id>/<name>
• Each worktree gets its own branch and working directory
• Use force=true to recreate existing worktrees
• Worktree data is stored globally for cleanup tracking