Coding Agent Tools
Relevant source files
The following files were used as context for generating this wiki page:- packages/coding-agent/src/tools/index.ts
- packages/coding-agent/src/tools/bash.ts
- packages/coding-agent/src/tools/edit.ts
- packages/coding-agent/src/tools/read.ts
- packages/coding-agent/src/main.ts
- packages/coding-agent/test/tools.test.ts
- packages/coding-agent/src/tools-manager.ts
- packages/mom/src/tools/edit.ts
The Coding Agent Tools are a suite of functions that the AI agent can execute to interact with the user's local environment. These tools provide capabilities for file system manipulation, command execution, and code searching. The agent is designed to be an expert coding assistant, and these tools are the primary mechanism through which it performs tasks like reading files, executing commands, editing code, and writing new files.
The set of available tools is configurable at runtime, allowing users to operate the agent in a "read-only" mode by disabling tools that can modify the file system. The agent's system prompt is dynamically constructed based on the selected tools, ensuring the LLM is aware of its available capabilities and limitations.
Sources: packages/coding-agent/src/main.ts:404-411, 609-610
Core Concepts
Tool Registration and Selection
All available tools are defined and exported from packages/coding-agent/src/tools/index.ts. They are categorized into two main groups:
codingTools: The default set of tools for general coding tasks, includingread,bash,edit, andwrite.allTools: An object containing all defined tools, including the defaultcodingToolsplus additional read-only tools likegrep,find, andls.
Users can specify which tools to enable using the --tools command-line argument. If not specified, the default codingTools are used.
Sources: packages/coding-agent/src/tools/index.ts:25-33, packages/coding-agent/src/main.ts:121-135, 609-610
System Prompt Integration
The agent's awareness of its tools is established by dynamically building a section in the system prompt. This section lists the enabled tools and their descriptions, along with guidelines on how to use them effectively. This process ensures the LLM only attempts to use tools that are actually available in its current configuration.
Sources: packages/coding-agent/src/main.ts:404-489
The following diagram illustrates the tool initialization and system prompt generation flow.
Tool Reference
The following table summarizes the tools available to the coding agent.
| Tool Name | Description | Default |
|---|---|---|
read | Read file contents. | ✓ |
bash | Execute bash commands (ls, grep, find, etc.). | ✓ |
edit | Make surgical edits to files (find exact text and replace). | ✓ |
write | Create or overwrite files. | ✓ |
grep | Search file contents for patterns (respects .gitignore). | ✗ |
find | Find files by glob pattern (respects .gitignore). | ✗ |
ls | List directory contents. | ✗ |
Sources: packages/coding-agent/src/main.ts:389-399, packages/coding-agent/src/tools/index.ts:25-33
read
Reads the content of a specified file. It includes functionality for pagination through large files using offset and limit parameters to manage context size. The tool automatically truncates files that exceed line or byte limits and informs the agent how to retrieve the remaining content.
| Parameter | Type | Description |
|---|---|---|
path | string | The path to the file to read. |
offset | number | The 1-based line number to start reading from. |
limit | number | The maximum number of lines to read. |
Sources: packages/coding-agent/src/tools/read.ts, packages/coding-agent/test/tools.test.ts:32-132
write
Creates a new file or completely overwrites an existing one with the provided content. It can create parent directories if they do not exist.
| Parameter | Type | Description |
|---|---|---|
path | string | The path to the file to write. |
content | string | The content to write to the file. |
Sources: packages/coding-agent/test/tools.test.ts:134-153
edit
Performs a "surgical" replacement of text within a file. This tool is designed for precise changes and includes safety checks to prevent unintended modifications. A similar tool with a different implementation exists in the mom package, which generates a diff string.
| Parameter | Type | Description |
|---|---|---|
path | string | The path to the file to edit. |
oldText | string | The exact text to find. Must be a unique occurrence in the file. |
newText | string | The text to replace oldText with. |
The edit tool follows a strict execution flow to ensure safety and precision.
bash
Executes a shell command. It uses the system's configured shell and has a default timeout to prevent long-running processes from blocking the agent.
| Parameter | Type | Description |
|---|---|---|
command | string | The shell command to execute. |
timeout | number | Optional timeout in milliseconds (default: 60000). |
Sources: packages/coding-agent/src/tools/bash.ts, packages/coding-agent/test/tools.test.ts:196-218
grep
Searches for a pattern within files. This tool is a read-only alternative to using grep via the bash tool. It respects .gitignore files.
| Parameter | Type | Description |
|---|---|---|
pattern | string | The pattern to search for. |
path | string | The file or directory to search in. |
limit | number | The maximum number of matches to return. |
context | number | The number of context lines to show around each match. |
Sources: packages/coding-agent/test/tools.test.ts:220-250
find
Finds files by a glob pattern. This is a read-only alternative to using find via the bash tool and respects .gitignore files.
| Parameter | Type | Description |
|---|---|---|
pattern | string | The glob pattern to match files against. |
path | string | The directory to start the search from. |
Sources: packages/coding-agent/test/tools.test.ts:252-282
ls
Lists the contents of a directory, including hidden dotfiles and directories.
| Parameter | Type | Description |
|---|---|---|
path | string | The path of the directory to list. |
Sources: packages/coding-agent/test/tools.test.ts:284-295
Dependency Management (tools-manager)
The coding-agent relies on external command-line tools like fd (for file autocompletion) and rg (ripgrep, used by the grep tool). The Tools Manager is responsible for ensuring these dependencies are available to the agent.
If a required tool is not found in the system's PATH or the local tools directory (~/.pi/agent/tools), the manager will automatically download the correct binary for the user's operating system and architecture from its official GitHub repository, install it, and make it executable.
Sources: packages/coding-agent/src/tools-manager.ts
The following table lists the tools managed by this system.
| Tool | Name | GitHub Repo |
|---|---|---|
fd | fd | sharkdp/fd |
rg | ripgrep | BurntSushi/ripgrep |
Sources: packages/coding-agent/src/tools-manager.ts:24-67
This diagram shows the process ensureTool follows to provide a tool.
Conclusion
The Coding Agent Tools provide a robust and flexible interface for the AI to interact with a developer's environment. The separation of read-only and write-capable tools, combined with user-configurable selection, allows for both powerful automation and safe, sandboxed operation. The automatic dependency management via tools-manager further simplifies the user experience by ensuring that necessary external binaries are available without manual installation. This toolset is fundamental to the agent's ability to perform complex coding and file-system-related tasks.