Built-in Tools
Relevant source files
The following files were used as context for generating this wiki page:
The Oh My Pi (OMP) ecosystem relies on a robust set of Built-in Tools to provide agents with the capabilities required for autonomous software engineering. These tools are the primary mechanism through which an agent interacts with the file system, executes code, searches for information, and manages its internal memory. They are designed to improve correctness, completeness, and grounding by allowing agents to perform surgical edits, complex searches, and code intelligence operations directly within the repository context.
Built-in tools are categorized by their function, ranging from basic file I/O (e.g., read, write, edit) to specialized language server protocol (LSP) integrations and cross-agent delegation via the task tool. Agents are governed by a strict Tool Policy that mandates the use of specialized tools over shell equivalents to ensure maximum reliability and safety during operations.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:120-125, packages/coding-agent/DEVELOPMENT.md:104-110
Tool Categories and Inventory
The system maintains a comprehensive inventory of tools that can be discovered and used by agents based on their current task domain.
File and Code Manipulation
These tools provide the core capabilities for reading, searching, and modifying the codebase.
| Tool Name | Purpose | Primary Use Case |
|---|---|---|
read | File/Directory Reading | Listing directory entries or reading specific file segments. |
edit | Surgical Edits | Applying precise changes to existing files. |
write | Create/Overwrite | Creating new files or completely replacing content. |
lsp | Code Intelligence | Definitions, references, type info, and code actions. |
grep | Regex Search | Finding text patterns across the repository. |
glob | Globbing | Mapping structure and finding files by pattern. |
ast_grep | Structural Discovery | Syntax-aware structural search. |
ast_edit | Codemods | Syntax-aware code modifications. |
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:143-165, packages/coding-agent/DEVELOPMENT.md:112-115
Execution and Environment
Tools used to run code and interact with external systems or different execution backends.
| Tool Name | Description |
|---|---|
bash | Execution of real binaries and short fact-computing pipelines. |
eval | Default for complex compute, loops, and stateful programs. |
job | Management of long-running execution tasks. |
ssh | Remote execution and interaction via SSH. |
debug | Debugger integration for troubleshooting code. |
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:156-163, packages/coding-agent/DEVELOPMENT.md:120-124
Tool Policy and Governance
Agents operate under a set of "Inviolable" rules regarding tool usage. The Tool Policy emphasizes using the most specialized tool available for a given task.
Specialization Over Shell
Agents MUST use specialized tools over shell equivalents (e.g., using grep tool instead of rg via bash). The bash tool is restricted to "litmus" tests: single binary calls or short pipelines returning specific facts like counts or checksums. Any command requiring control flow (loops, conditionals) or complex shell quoting must be moved to eval.
Exploration Strategy
The "Hope is not a strategy" principle dictates that agents must never open files blindly. Instead, they follow a structured exploration path:
- Map structure using
glob. - Locate targets using
grep. - Analyze unknown code via
tasksubagents. - Read segments using
readwith offset/limit to minimize context bloat.
Sources: packages/coding-agent/src/prompts/system/system-prompt.md:126-140, packages/coding-agent/src/prompts/system/system-prompt.md:172-180
Architecture and Data Flow
The tool execution architecture involves the interaction between the AgentSession, the Tool Registry, and specific tool implementations.
Tool Execution Flow
When an agent decides to use a tool, it generates a tool call which is then routed through the session's execution logic.
The diagram above shows the decision logic for selecting and executing a tool within the OMP environment.
Tool Discovery and BM25 Search
For sessions where discovery is enabled, the system uses a BM25-based search index to locate relevant tools. This is particularly useful for discovering MCP (Model Context Protocol) tools provided by external servers.
This diagram illustrates the flow of the search_tool_bm25 tool, which helps agents find tools they don't yet have in their immediate inventory.
Sources: packages/coding-agent/test/tools/search-tool-bm25.test.ts:88-110, packages/coding-agent/src/prompts/system/system-prompt.md:113-118
Implementation Details
The analyze_files Tool
An example of a complex built-in tool is analyze_files. It acts as a wrapper that spawns parallel quick_task subagents to perform analysis on multiple files simultaneously. It uses a ToolSession that carries settings, authentication storage, and an output schema to drive structured results.
// From packages/coding-agent/src/commit/agentic/tools/analyze-file.ts:60-75
const analyses = await Promise.all(
params.files.map((file, index) => {
const relatedFiles = formatRelatedFiles(params.files, file, numstat);
const assignment = prompt.render(analyzeFilePrompt, {
file,
goal: params.goal,
related_files: relatedFiles,
});
const taskParams: TaskParams = {
agent: "quick_task",
id: `AnalyzeFile${index + 1}`,
description: `Analyze ${file}`,
assignment,
};
return taskTool.execute(`${toolCallId}-${index + 1}`, taskParams, signal);
}),
);
Sources: packages/coding-agent/src/commit/agentic/tools/analyze-file.ts:60-75, packages/coding-agent/src/commit/agentic/tools/analyze-file.ts:32-45
TUI Sanitization and Output
Every built-in tool that interacts with the user interface must follow strict sanitization rules to prevent terminal corruption. This include:
- Tabs to spaces: Using
replaceTabs(). - Path shortening: Replacing home directories with
~viashortenPath(). - Truncation: Limiting line lengths and using
PREVIEW_LIMITSconstants.
Sources: AGENTS.md:130-140
Conclusion
Built-in tools form the backbone of the Oh My Pi agent's agency. By providing a controlled and specialized interface to the host environment, OMP ensures that agents can perform complex engineering tasks with high precision and safety. The combination of direct file manipulation tools, structural search, and the ability to delegate work to specialized sub-agents via the task system allows for scalable and grounded code interaction.