> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reliantlabs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Tools Quick Reference

> Auto-generated quick reference for all tools (tags, names, descriptions)

This reference lists all available tools organized by category.

## Tool Tags

Tools are organized by tags for filtering:

| Tag             | Description                                       |
| --------------- | ------------------------------------------------- |
| `tag:readonly`  | Read-only tools (safe for planning mode)          |
| `tag:plan`      | Planning mode tools (read-only + planning tools)  |
| `tag:file`      | File operations                                   |
| `tag:search`    | Search operations                                 |
| `tag:execution` | Command execution                                 |
| `tag:shell`     | Shell tools (bash on Unix, powershell on Windows) |
| `tag:web`       | Web operations                                    |
| `tag:planning`  | Planning and task management tools                |
| `tag:analysis`  | Analysis tools                                    |
| `tag:workflow`  | Workflow builder tools                            |
| `tag:mcp`       | All MCP tools                                     |
| `tag:default`   | Default toolset (commonly used tools)             |

***

## Categories

* [Planning & Task Management](#planning--task-management) (22 tools)
* [File Operations](#file-operations) (4 tools)
* [Information Retrieval](#information-retrieval) (1 tools)
* [Workflow Management](#workflow-management) (16 tools)
* [System & Execution](#system--execution) (1 tools)
* [Other Tools](#other-tools) (5 tools)

***

## Planning & Task Management

*Tools for creating plans, managing tasks, and tracking progress.*

| Tool                                      | Tags                                      | Description                                                                                          |
| ----------------------------------------- | ----------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| [`add_dependency`](#add_dependency)       | planning, plan                            | Create a dependency between two tasks in the current plan.                                           |
| [`add_task`](#add_task)                   | planning, plan, default                   | Add a new task to the current plan. This is your primary tool for dynamic planning and sub-planning. |
| [`bash_list`](#bash_list)                 | execution, shell, readonly, plan, default | Lists background processes in the current workspace.                                                 |
| [`bash_output`](#bash_output)             | execution, shell, readonly, plan, default | Retrieves output from a background process with pagination and regex filtering support.              |
| [`bash_wait`](#bash_wait)                 | execution, shell, readonly, plan, default | Block until a background process exits, then return its exit code and recent output.                 |
| [`component_library`](#component_library) | readonly, plan                            | Component library with 61 production-ready React/TypeScript components for building UIs, dashboar... |
| [`create_plan`](#create_plan)             | planning, plan, default                   | Create a comprehensive plan with tasks for implementing a feature or solving a problem.              |
| [`create_subtask`](#create_subtask)       | planning, plan                            | Create a subtask under an existing task.                                                             |
| [`fetch`](#fetch)                         | web, readonly, plan, default              | Fetches content from a URL and returns it in the specified format.                                   |
| [`get_plan`](#get_plan)                   | planning, readonly, plan                  | Retrieve the current plan for this session.                                                          |
| [`list_ready_tasks`](#list_ready_tasks)   | planning, readonly, plan                  | List tasks that are ready to work on — no unresolved blockers.                                       |
| [`list_tasks`](#list_tasks)               | planning, readonly, plan, default         | List all tasks for the current plan.                                                                 |
| [`load_tool`](#load_tool)                 | default, readonly, plan                   | Dynamically load a tool by name or search for available tools.                                       |
| [`project_analyzer`](#project_analyzer)   | analysis, readonly, plan                  | Analyzes project structure, detects languages, build systems, and test frameworks                    |
| [`read_attachment`](#read_attachment)     | file, readonly, plan, default             | Read the contents of a file the user attached to the conversation.                                   |
| [`remove_dependency`](#remove_dependency) | planning, plan                            | Remove a dependency between two tasks.                                                               |
| [`skill`](#skill)                         | default, readonly, plan                   | Load skills — specialized knowledge and instructions for specific tasks.                             |
| [`sourcegraph`](#sourcegraph)             | analysis, readonly, plan                  | Search code across public repositories using Sourcegraph's GraphQL API.                              |
| [`update_plan`](#update_plan)             | planning, plan                            | Update an existing plan's details or status.                                                         |
| [`update_task`](#update_task)             | planning, plan, default                   | Update a task's status, details, or metadata.                                                        |
| [`view`](#view)                           | file, readonly, plan, default             | File viewing tool that reads and displays the contents of files with line numbers, allowing you t... |
| [`websearch`](#websearch)                 | web, readonly, plan, default              | Search the web using DuckDuckGo's HTML search.                                                       |

### add\_dependency

**Tags:** `planning`, `plan`

Create a dependency between two tasks in the current plan.

DEPENDENCY TYPES:

* blocks: from\_task must complete before to\_task can start
* related: informational link, no execution constraint
* parallel\_with: explicitly marks tasks as parallelizable

EXAMPLES:

* 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.

USE WITH list\_ready\_tasks:
After adding 'blocks' dependencies, use list\_ready\_tasks to see which tasks
have no unresolved blockers and are ready to work on.

***

### add\_task

**Tags:** `planning`, `plan`, `default`

Add a new task to the current plan. This is your primary tool for dynamic planning and sub-planning.

WHEN TO USE:

* 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

SUB-PLANNING WITH parent\_id:

* 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

COMPLEXITY DISCOVERY PATTERNS:

* 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

METADATA OPTIONS:

* 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

SUB-PLANNING EXAMPLES:

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"]

BEST PRACTICES:

* 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

**Tags:** `execution`, `shell`, `readonly`, `plan`, `default`

Lists background processes in the current workspace.

WORKSPACE SCOPING:

* 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

Usage notes:

* 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

Example outputs:

* 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

Examples:

1. List running processes: bash\_list()
2. List all processes including completed: bash\_list(all=true)

***

### bash\_output

**Tags:** `execution`, `shell`, `readonly`, `plan`, `default`

Retrieves output from a background process with pagination and regex filtering support.

WORKSPACE SCOPING:

* 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

This tool allows you to check the stdout and stderr output of a process running in the background,
with support for reading in chunks to handle large outputs efficiently and filtering with regex.

Usage notes:

* 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

MODES OF OPERATION:

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)

PARAMETER COMPATIBILITY:
Valid combinations:

* offset + limit (standard pagination)
* tail (alone)
* regex (alone)
* regex + offset + limit (filtered pagination)
* regex + regex\_case\_insensitive + regex\_context\_before + regex\_context\_after

Invalid combinations (will error):

* tail + regex
* tail + offset
* tail + limit
* regex\_case\_insensitive without regex
* regex\_context\_before/after without regex

Examples:

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)

The response includes metadata:

* 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

**Tags:** `execution`, `shell`, `readonly`, `plan`, `default`

Block until a background process exits, then return its exit code and recent output.

WHY THIS EXISTS:
Waiting by running a sleep command is the wrong tool and costs far more than it
looks. `sleep 300; tail log` occupies a whole turn doing nothing, and it
frequently exceeds the tool timeout and dies, losing the wait entirely. Polling
bash\_output in a loop is better but spends a model round-trip on every check.
bash\_wait blocks server-side: one tool call, no round-trips, no lost work.

WHEN TO USE:

* 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

WHEN NOT TO USE:

* 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)

HOW TO USE:

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>`")

TIMEOUTS ARE NOT FAILURES:
If the process is still running when the budget elapses, this returns normally
with timed\_out: true and the process untouched. Call bash\_wait again to keep
waiting. It never kills the process — use bash\_kill for that.

Because a single call cannot block past the tool-execution ceiling, a very long
build may need a few consecutive bash\_wait calls. That is still dramatically
cheaper than polling, and unlike a sleep it cannot lose the wait.

RETURNS:

* 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

Use bash\_output for the full log, for pagination, or for regex filtering.

***

### component\_library

**Tags:** `readonly`, `plan`

Component library with 61 production-ready React/TypeScript components for building UIs, dashboards, landing pages, pitch decks, charts, and diagrams.

WHEN TO USE:

* 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.

ACTIONS:

* 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)

CATEGORIES: layouts (11), charts (6), diagrams (5), deck (7), ui (32)

TAGS: layout, chart, diagram, deck, ui, landing, marketing, dashboard, analytics, admin, portal, crm, comparison, pricing, hero, form, auth, slide, presentation, saas, funnel, competitive, market, pipeline, process, team, docs, technical, crud, table, stats, detail, search, navigation, modal, dialog, filter, badge, status, tabs, pagination, toast, notification, avatar, dropdown, menu, skeleton, loading, toggle, switch, alert, banner, activity, feed, metric, breadcrumb

OPTIONS:

* forge\_integrated: Set to true in forge-generated projects to get integration guidance for useUiStore, useEventBus, and useAuth

CHARTS handle all coordinate math internally — pass data, get pixels. No spatial reasoning required.

***

### create\_plan

**Tags:** `planning`, `plan`, `default`

Create a comprehensive plan with tasks for implementing a feature or solving a problem.
WHEN TO USE:

* 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.

VISIBILITY: Sub-agents you spawn CAN read this plan. A spawned thread with no
plan of its own resolves list\_tasks / get\_plan / list\_ready\_tasks against its
nearest ancestor's plan, so the board you build here is the board they see.
They can update the status of a task you assigned them; only this thread can
change the plan's shape (add tasks, edit the plan itself).

So a plan is how you delegate, not just how you take notes. Tasks are the units
of work you hand out — write them at the size of one sub-agent's job.

PLAN STRUCTURE:

* 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

INLINE DEPENDENCIES:
You can specify dependencies between tasks at creation time using 1-indexed task positions.
Each task can have a "dependencies" array where each entry specifies:

* 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)

The dependency means: "the task at task\_position has this relationship TO the current task."
For example, if task 3 has dependencies: `[{task_position: 1, type: "blocks"}]`, it means task 1 blocks task 3.

INDEPENDENT IS THE DEFAULT. Tasks with no "blocks" edge between them can run at
the same time — you do NOT need to mark that. Add "blocks" only where a real
data dependency exists: task B consumes something task A creates. Name it in
the task description when you do.

A chain of "blocks" edges says every task must wait for the previous one, which
serializes the whole plan. Only write one when that is true.

Example — fan-out (the common shape; four independent tasks, then a join):

```json theme={null}
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.
```

Example — a genuine chain (each step consumes the last):

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

TASK METADATA:
Each task can optionally include metadata with agent hints:

* 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

BEST PRACTICES:

* 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

**Tags:** `planning`, `plan`

Create a subtask under an existing task.
WHEN TO USE:

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

BEST PRACTICES:

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

***

### fetch

**Tags:** `web`, `readonly`, `plan`, `default`

Fetches content from a URL and returns it in the specified format.

Uses Mozilla Readability to automatically extract main page content, stripping navigation,
footers, ads, and other chrome. Returns only the readable content for text and markdown formats.

WHEN TO USE THIS TOOL:

* 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

HOW TO USE:

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

FEATURES:

* 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

PARAMETERS:

* max\_size: Maximum bytes to fetch (default: 16000, \~16KB)
  Prevents downloading huge files that could overwhelm context

IMPORTANT LIMITATIONS:

* 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

TIPS FOR BETTER RESULTS:

* For GitHub repos, use raw\.githubusercontent.com URLs instead of github.com
  (e.g., [https://raw.githubusercontent.com/org/repo/main/README.md](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)

RESPONSE METADATA:

* 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

**Tags:** `planning`, `readonly`, `plan`

Retrieve the current plan for this session.
WHEN TO USE:

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

RETURNS:

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

***

### list\_ready\_tasks

**Tags:** `planning`, `readonly`, `plan`

List tasks that are ready to work on — no unresolved blockers.

A task is "ready" when:

1. Its status is "pending" (not started yet)
2. All tasks that block it (via 'blocks' dependencies) have status "completed"

This is the deterministic way for agents to know what to pick up next.
Tasks with no blocking dependencies are always ready (if pending).

RETURNS:

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

***

### list\_tasks

**Tags:** `planning`, `readonly`, `plan`, `default`

List all tasks for the current plan.
WHEN TO USE:

* 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

RETURNS:

* 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.

If this thread has no plan of its own, the plan of the nearest ancestor thread
is shown — the board you were spawned from. It is read-only here; you can still
update the status of a task assigned to you.

***

### load\_tool

**Tags:** `default`, `readonly`, `plan`

Dynamically load a tool by name or search for available tools.

Use this when you need a tool that isn't currently loaded. You can:

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

Loaded tools become available immediately on the next turn.

***

### project\_analyzer

**Tags:** `analysis`, `readonly`, `plan`

Analyzes project structure, detects languages, build systems, and test frameworks

***

### read\_attachment

**Tags:** `file`, `readonly`, `plan`, `default`

Read the contents of a file the user attached to the conversation.

WHEN TO USE:

* 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.

HOW TO USE:

* 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.

NOTES:

* 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

**Tags:** `planning`, `plan`

Remove a dependency between two tasks.

Specify from\_task, to\_task, and type to identify which dependency to remove.

***

### skill

**Tags:** `default`, `readonly`, `plan`

Load skills — specialized knowledge and instructions for specific tasks.
Skills provide detailed guidance on how to perform particular operations.
Use 'list' to see available skills, 'load' to load a skill's instructions,
or 'search' to find skills by keyword.
When you load a skill, its instructions become available in the conversation.
Skills may suggest tools to load — use the load\_tool tool if suggested tools are needed.

In multi-repo projects, skills are discovered recursively across all nested
repos. Each skill's source repo is shown in brackets after its description
(e.g. "\[source: api]") and is reflected as a prefix on its path
(e.g. "api/deploy" vs "web/deploy"). Use the prefixed path with 'load'.

READING A LARGE SKILL (action=load):
Every load ends with its total size and whether anything remains, so ONE call
tells you if you have the whole skill. Do not page defensively — page only when
a result says bytes remain, and it will name the exact call to continue with.

A skill too large to deliver at once is read with these, mirroring bash\_output:

* 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.

Examples:
skill(action="load", path="db")                      whole skill + size report
skill(action="load", path="db", section="Seeding")   one section
skill(action="load", path="db", offset=23000)        continue where a window ended
skill(action="load", path="db", regex="foreign key") find the relevant part first

***

### sourcegraph

**Tags:** `analysis`, `readonly`, `plan`

Search code across public repositories using Sourcegraph's GraphQL API.

WHEN TO USE THIS TOOL:

* 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

HOW TO USE:

* 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

QUERY SYNTAX:

* 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

ADVANCED FILTERS:

* 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

EXAMPLES:

* "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

BOOLEAN OPERATORS:

* "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

LIMITATIONS:

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

TIPS:

* 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

**Tags:** `planning`, `plan`

Update an existing plan's details or status.
WHEN TO USE:

* 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

UPDATES ALLOWED:

* Title: Update the plan title
* Description: Add new information, document pivots
* Status: pending|in\_progress|completed|cancelled
* Complexity: simple|moderate|complex

BEST PRACTICES:

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

***

### update\_task

**Tags:** `planning`, `plan`, `default`

Update a task's status, details, or metadata.
WHEN TO USE:

* 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

STATUS OPTIONS:

* 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

ASSIGNEE:

* 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

METADATA OPTIONS:

* 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

BEST PRACTICES:

* 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

**Tags:** `file`, `readonly`, `plan`, `default`

File viewing tool that reads and displays the contents of files with line numbers, allowing you to examine code, logs, or text data.

WHEN TO USE:

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

HOW TO USE:

* 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

FEATURES:

* 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

LIMITATIONS:

* 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

TIPS:

* 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

**Tags:** `web`, `readonly`, `plan`, `default`

Search the web using DuckDuckGo's HTML search.

WHEN TO USE THIS TOOL:

* 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

HOW TO USE:

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

QUERY GUIDELINES:

* 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

IMPORTANT - UNSUPPORTED QUERY SYNTAX:
DuckDuckGo's HTML search does NOT support these features (they will return zero results):

* 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.

EXAMPLES OF GOOD QUERIES:

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

EXAMPLES OF BAD QUERIES (will return 0 results):

* "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

RESEARCH STRATEGY:

* 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

RESPONSE FORMAT:
Returns a list of search results with:

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

LIMITATIONS:

* 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

TIPS:

* 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

*Tools for reading, writing, and modifying files.*

| Tool                            | Tags          | Description                                                                                         |
| ------------------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
| [`edit`](#edit)                 | file, default | Make a precise text replacement in a single file, or create/delete file content. One edit per call. |
| [`find_replace`](#find_replace) | file, default | Performs find and replace operations across multiple files matching a glob pattern.                 |
| [`move_code`](#move_code)       | file          | Move or copy a block of code from one location to another, within the same file or across files.    |
| [`write`](#write)               | file, default | File writing tool that creates or updates files in the filesystem.                                  |

### edit

**Tags:** `file`, `default`

Make a precise text replacement in a single file, or create/delete file content. One edit per call.

NOTE: To make several edits at once, issue multiple edit tool calls IN THE SAME MESSAGE — they run in parallel. Do NOT try to pack multiple edits into one call.

Edits to DIFFERENT files in one message run at the same time. Edits to the SAME file are applied one at a time, in an unspecified order, each one seeing the result of the ones before it. So batch same-file edits freely — but only when they are independent: each old\_string must still match after the others have applied. Two edits whose old\_string regions overlap, or where one creates the text the other matches, must be sent in separate messages, or the second will fail to match.

WHEN TO USE:

* Precise text replacements
* Creating a new file (empty old\_string)
* Deleting specific content (empty new\_string)
* Renaming a variable/function (with replace\_all)

ALWAYS PREFER THIS TOOL OVER write. Turn latency is set by how many tokens you
GENERATE, so rewriting an existing file costs minutes of generation for a change
edit makes in seconds. write is for creating NEW files; for anything that already
exists, use edit. If an old\_string fails to match, re-read the exact region and
retry the edit — falling back to a full rewrite is the most expensive move available.

WHEN NOT TO USE:

* Moving/renaming files: Use Bash mv command

COMMON MISTAKES TO AVOID:

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

USAGE PATTERNS:

## Replace Text

file\_path: "/path/to/file.go"
old\_string: "Include 3-5 lines before AND after"
new\_string: "Your replacement text"
replace\_all: false

## Multiple Edits

Issue one edit call per change, all in the same message. For example, to edit two
files at once, send two edit tool calls in parallel:
edit(file\_path="/path/to/file1.go", old\_string="old text 1", new\_string="new text 1")
edit(file\_path="/path/to/file2.go", old\_string="old text 2", new\_string="new text 2")

## Create New File

file\_path: "/path/to/new/file.go"
old\_string: ""
new\_string: "file contents"

## Delete Content

file\_path: "/path/to/file.go"
old\_string: "text to remove"
new\_string: ""

## Rename Variable

file\_path: "/path/to/file.go"
old\_string: "oldName"
new\_string: "newName"
replace\_all: true

#### 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)

Remember: This tool requires EXACT text matching including all whitespace and indentation.

***

### find\_replace

**Tags:** `file`, `default`

Performs find and replace operations across multiple files matching a glob pattern.
WHEN TO USE:

* 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)

Use preview=true to see what would change before committing. Preview mode does not
require permission, making it ideal for scoping changes.
find\_pattern: "oldFunction"
replace\_text: "newFunction"
file\_glob: "\*\*/\*.js"
preview: true

## Simple Text Replacement

find\_pattern: "oldFunction"
replace\_text: "newFunction"
file\_glob: "\*\*/\*.js"

## Regex with Capture Groups

find\_pattern: "import (.*) from 'old-module'"
replace\_text: "import \$1 from 'new-module'"
use\_regex: true
file\_glob: "\*\*/*.ts"

## Case-Insensitive Replacement

find\_pattern: "TODO"
replace\_text: "FIXME"
ignore\_case: true
file\_glob: "`**/*.{js,ts,jsx,tsx}`"

#### 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

**Tags:** `file`

Move or copy a block of code from one location to another, within the same file or across files.

WHEN TO USE:

* 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

WHEN NOT TO USE:

* 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

HOW IT WORKS:

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

EXAMPLES:

## Move function to end of file

```json theme={null}
{
"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

```json theme={null}
{
"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

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

CRITICAL REQUIREMENTS:

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

BEST PRACTICES:

* 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

**Tags:** `file`, `default`

File writing tool that creates or updates files in the filesystem.

WHEN TO USE:

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

HOW TO USE:

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

FEATURES:

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

LIMITATIONS:

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

REPLACING AN EXISTING FILE:

* 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.

BATCHING — this is the main cost:

* 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.

TIPS:

* 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

*Tools for searching code, finding files, and fetching external content.*

| Tool            | Tags                              | Description                                                                              |
| --------------- | --------------------------------- | ---------------------------------------------------------------------------------------- |
| [`bash`](#bash) | execution, shell, search, default | Execute bash commands for building, testing, and system operations in a stateless shell. |

### bash

**Tags:** `execution`, `shell`, `search`, `default`

Execute bash commands for building, testing, and system operations in a stateless shell.

Uses bash -c to execute commands on Unix/macOS/Linux.

#### WHEN NOT TO USE THIS TOOL

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

#### 🔎 SEARCHING THE CODEBASE

The single best thing you can do when searching the codebase is combine multiple
tools calls in each turn. The vast majority of time is eaten up in LLM turns, so
reducing that is precious. When searching through deeper call chains, the best way
to do this is via an LSP that gives you the full graph, otherwise you may spend 50-100+
calls at \~10s per turn.

## Go — 'gopls' (for Go packages)

gopls call\_hierarchy path/to/file.go:LINE:COL   # callers AND callees
gopls implementation path/to/file.go:LINE:COL   # interface -> concrete types
gopls references     path/to/file.go:LINE:COL   # only when rg is ambiguous
Get LINE:COL from an rg hit first ('rg -n' gives the line; the column is the
1-based offset of the identifier on it). You can CHAIN the lookup and the query
in ONE command rather than spending a turn on each:
f=internal/svc/x.go; l=$(rg -n 'func .*executeApproval' $f | cut -d: -f1); \
gopls call\_hierarchy $f:$l:34; gopls implementation $f:$l:34
Do not use it for plain name lookup — that is a grep, which is faster than gopls.

## Other languages

Capability varies, and a command that is not installed is worse than no advice.
Probe before relying on one: 'command -v `<tool>` >/dev/null && `<tool>` ...'.
TypeScript and C# reach a language server through an MCP bridge when the harness
enables one; that bridge exposes references/definition/hover but NOT call
hierarchy, so caller walks there stay with rg — keep them shallow and verify.
'hover' is still uniquely valuable: it returns an INFERRED type ('const x =
useFoo()' with no annotation), which rg cannot compute at all.
Load the 'code-search' skill for the per-language capability table.

Prefer ripgrep for other generic searches:

* 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

Commands like 'find / -name ...', 'find \~ ...' or 'grep -r ... /usr' are REFUSED
before they run: they read the whole machine, take minutes, and starve every
other agent on this disk.

* 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 "{`{.Dir}`}" `<module>`', 'go env GOMODCACHE', 'npm root'.
* If you truly need a filesystem search, name a specific directory.

#### ⛓️ CHAIN PROBES — ONE CALL ANSWERS MANY QUESTIONS

A turn costs a full model generation whether it carries ONE probe or NINE. The
command string is where you buy that back: separate probes with ';' and label
each with an echo, and one call returns the whole picture.

ls internal/handlers/; echo "=== proto ==="; grep -n '^message|^service' \
proto/services/foo/v1/foo.proto | head -40; echo "=== migrations ==="; \
ls db/migrations/ | tail -5

Chaining also works when a probe DEPENDS on the previous one, which parallel
tool calls cannot express:

f=$(rg -l 'ListWidgetsRequest' proto/); echo "$f"; grep -n 'ListWidgets' -A 12 "\$f"

Reach for it whenever you are about to run a second search to interpret the
first. Measured: agents that chain average \~8 probes per call; agents that do
not average \~3, and the difference is turns — the single largest recoverable
cost in a long run.

Independent tool calls can ALSO run in parallel in one response. Chaining and
parallel calls compose: issue every call you have already decided in the SAME
turn, and chain the probes inside each one. Never split calls you have already
decided across turns — that is the one pattern that costs a generation for
nothing.

#### 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

Usage notes:

* 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).

STATELESS EXECUTION:

* 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.

```bash theme={null}
pytest /foo/bar/tests
```

```bash theme={null}
cd /foo/bar && pytest tests
```

Important:

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

***

## Workflow Management

*Tools for managing and inspecting workflows, presets, and scenarios.*

| Tool                                                    | Tags               | Description                                                         |
| ------------------------------------------------------- | ------------------ | ------------------------------------------------------------------- |
| [`create_workflow`](#create_workflow)                   | workflow           | Create a new workflow draft.                                        |
| [`delete_scenario`](#delete_scenario)                   | workflow           | Delete a test scenario.                                             |
| [`edit_scenario`](#edit_scenario)                       | workflow           | Make precise text replacements in a scenario's YAML definition.     |
| [`edit_workflow`](#edit_workflow)                       | workflow           | Make precise text replacements in the workflow YAML.                |
| [`get_cel_reference`](#get_cel_reference)               | workflow, readonly | Gets the CEL expression reference for workflow development.         |
| [`get_preset`](#get_preset)                             | workflow, readonly | Gets the full configuration of a preset.                            |
| [`get_schema`](#get_schema)                             | workflow, readonly | Look up schema documentation for any workflow type by name.         |
| [`get_workflow`](#get_workflow)                         | workflow, readonly | Gets the full YAML definition of a workflow draft.                  |
| [`get_workflow_suggestions`](#get_workflow_suggestions) | workflow, readonly | Returns static design suggestions for building workflows.           |
| [`list_presets`](#list_presets)                         | workflow, readonly | Lists available presets for agent nodes.                            |
| [`list_scenarios`](#list_scenarios)                     | workflow, readonly | List all test scenarios for the current workflow.                   |
| [`list_workflows`](#list_workflows)                     | workflow, readonly | Lists all available workflows (builtin, project, and user-created). |
| [`run_scenario`](#run_scenario)                         | workflow           | Run an existing test scenario by name.                              |
| [`view_scenario`](#view_scenario)                       | workflow, readonly | View a specific test scenario's full definition.                    |
| [`write_scenario`](#write_scenario)                     | workflow           | Create or update a test scenario with YAML content.                 |
| [`write_workflow`](#write_workflow)                     | workflow           | Replace an existing workflow draft with YAML content.               |

### create\_workflow

**Tags:** `workflow`

Create a new workflow draft.

Returns the draft UUID which you can then use with get\_workflow, edit\_workflow, and write\_workflow.

**Parameters:**

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

**Response:**
Returns JSON with id, name, and slug.

**Example — create with defaults:**

```json theme={null}
{}
```

**Example — create with name and content:**

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

***

### delete\_scenario

**Tags:** `workflow`

Delete a test scenario.

Permanently removes the scenario from the workflow.

***

### edit\_scenario

**Tags:** `workflow`

Make precise text replacements in a scenario's YAML definition.

Use this for small changes like updating expected values or modifying events.
The old\_string must match exactly (including whitespace and indentation).

**Example:**

```json theme={null}
{
"name": "happy_path",
"old_string": "outcome: completed",
"new_string": "outcome: error"
}
```

***

### edit\_workflow

**Tags:** `workflow`

Make precise text replacements in the workflow YAML.

Use this for small changes like:

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

The old\_string must match exactly (including whitespace and indentation).
Include enough context to ensure a unique match.

**Conflict Detection:**
If you provide expected\_version (from get\_workflow), the edit will fail if the
workflow was modified since you last viewed it.

**Example:**

```json theme={null}
{
"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

**Tags:** `workflow`, `readonly`

Gets the CEL expression reference for workflow development.

WHEN TO USE:

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

RETURNS:
Complete CEL reference including:

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

***

### get\_preset

**Tags:** `workflow`, `readonly`

Gets the full configuration of a preset.

WHEN TO USE:

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

PARAMETERS:

* name: The preset name (from list\_presets)

RETURNS:
The complete preset YAML configuration.

***

### get\_schema

**Tags:** `workflow`, `readonly`

Look up schema documentation for any workflow type by name.

WHEN TO USE:

* 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

WHAT YOU CAN QUERY:

* 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

Type detection is automatic - just provide the name.

EXAMPLES:

* 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

**Tags:** `workflow`, `readonly`

Gets the full YAML definition of a workflow draft.

WHEN TO USE:

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

PARAMETERS:

* id: (required) Workflow draft UUID

RETURNS:
The complete workflow YAML definition with validation status, version, and timestamps.
Use the version for conflict detection in edit\_workflow/write\_workflow.

***

### get\_workflow\_suggestions

**Tags:** `workflow`, `readonly`

Returns static design suggestions for building workflows.

WHEN TO USE:

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

RETURNS:
Markdown document with categorized suggestions covering:

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

Note: These are static suggestions. Future calls yield the same results.

***

### list\_presets

**Tags:** `workflow`, `readonly`

Lists available presets for agent nodes.

WHEN TO USE:

* To discover available presets for agent configurations
* To find the right preset for a specific task
* Before using get\_preset to view details

RETURNS:
List of preset names with descriptions.

***

### list\_scenarios

**Tags:** `workflow`, `readonly`

List all test scenarios for the current workflow.

Returns a summary of each scenario including name, description, and last run status.
Use this to see what scenarios exist and their current state.

No parameters needed - the workflow is determined from the current chat context.

***

### list\_workflows

**Tags:** `workflow`, `readonly`

Lists all available workflows (builtin, project, and user-created).

WHEN TO USE:

* To discover available workflows
* To find workflow patterns for common use cases
* Before using get\_workflow to view details

RETURNS:
List of workflow names with descriptions and source (builtin, project, or user).

***

### run\_scenario

**Tags:** `workflow`

Run an existing test scenario by name.

Executes the scenario against the current workflow and returns the results.
Use this after making changes to verify scenarios still pass.

Use list\_scenarios to see available scenario names.

***

### view\_scenario

**Tags:** `workflow`, `readonly`

View a specific test scenario's full definition.

Returns the complete scenario YAML including events, expectations, and last run results.
Use this to examine a scenario's configuration or debug test failures.

***

### write\_scenario

**Tags:** `workflow`

Create or update a test scenario with YAML content.

Creates or updates a scenario with the given YAML definition and runs it.

**Scenario YAML structure:**
name: scenario\_name
description: What this scenario tests
events:

* 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"]

**Targeting nodes:**

* 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"

**Example:**

```json theme={null}
{
"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

**Tags:** `workflow`

Replace an existing workflow draft with YAML content.

**Usage:**

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

The content must be valid workflow YAML with at minimum:

* 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)

**Parameters:**

* 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.

**Response:**
Returns JSON with id, name, slug, and created (false for updates).
The slug can be used in ref: fields to reference this workflow.

***

## System & Execution

*Tools for executing shell commands and managing system processes.*

| Tool                      | Tags                      | Description                                               |
| ------------------------- | ------------------------- | --------------------------------------------------------- |
| [`bash_kill`](#bash_kill) | execution, shell, default | Terminates a background process in the current workspace. |

### bash\_kill

**Tags:** `execution`, `shell`, `default`

Terminates a background process in the current workspace.

WORKSPACE SCOPING:

* 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

This tool sends a termination signal and gives the process time to clean up.
If it doesn't stop gracefully, it will be forcefully killed.

Usage notes:

* 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

Example:

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

*Miscellaneous tools and utilities.*

| Tool                                  | Tags     | Description                                                                                        |
| ------------------------------------- | -------- | -------------------------------------------------------------------------------------------------- |
| [`ask_user`](#ask_user)               | -        | Ask the user one or more questions and wait for their responses. Use this when you need to:        |
| [`metadata_writer`](#metadata_writer) | -        | Writes and updates project metadata YAML file                                                      |
| [`spawn_send`](#spawn_send)           | -        | Send a message to a running sub-agent you spawned, or to your own parent agent.                    |
| [`spawn_status`](#spawn_status)       | readonly | Check on the sub-agents you (the calling thread) have spawned — list them all, or inspect and o... |
| [`worktree`](#worktree)               | -        | Manage git worktrees for parallel development workflows.                                           |

### ask\_user

Ask the user one or more questions and wait for their responses. Use this when you need to:

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

Usage notes:

* 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

Writes and updates project metadata YAML file

***

### spawn\_send

Send a message to a running sub-agent you spawned, or to your own parent agent.

THE RECEIPT IS HONEST — READ IT LITERALLY:
This QUEUES the message for delivery at the target's next turn. It does NOT
mean the target has read it, and it does NOT mean the target has acted on it.
Do not proceed as though your instruction has already taken effect — if you
need to know whether it landed, check back with spawn\_status or wait for a
response.

v1 is parent \u2194 child only: you may message a direct sub-agent (a spawn of
this thread) or your own parent. Messaging a sibling or unrelated agent is
rejected.

If the target has already finished, this FAILS rather than silently doing
nothing \u2014 use spawn(agent\_id=...) to resume it instead.

***

### spawn\_status

**Tags:** `readonly`

Check on the sub-agents you (the calling thread) have spawned — list them all, or inspect and optionally wait on one.

WORKSPACE SCOPING:

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

TWO MODES:

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.

WAITING:
Set wait: true with agent\_id to block server-side until that agent reaches a
terminal state (completed/failed/cancelled/expired), instead of polling this
tool yourself. One call, no round-trips, no lost work — the same shape as
bash\_wait.

TIMEOUTS ARE NOT FAILURES:
If the agent is still running when the budget elapses, this returns normally
with timed\_out: true and the agent untouched. Call spawn\_status again with
wait: true to keep waiting.

Use spawn\_send to message an agent that is still running.

***

### worktree

Manage git worktrees for parallel development workflows.

WHEN TO USE:

* 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 DATA STORAGE:

* 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.

FILE COPYING:

* 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)

EXAMPLES:

Create a worktree with recursive file copy:

```json theme={null}
{
"action": "create",
"name": "feature-auth",
"base_branch": "main",
"copy_files": [".env", ".env.local"]
}
```

List all worktrees:

```json theme={null}
{
"action": "list"
}
```

NOTES:

* 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

***