File System & Terminal Tools

Relevant source files

The following files were used as context for generating this wiki page:

• src/tools/bash.ts
• src/tools/edit.ts
• src/tools/read.ts
• src/tools/write.ts
• src/tools/index.ts
• src/agent/setup.ts
• src/agent/prompt.ts

Introduction

The File System & Terminal Tools represent the primary mechanism through which the pi-digby agent interacts with its host environment. These tools provide the agent with the ability to execute shell commands, read and write files, perform surgical text edits, and manage directory structures. They are designed to operate directly on the host machine, typically within a persistent workspace directory backed by AWS EFS.

These tools are integrated into the agent's execution loop via the AgentSession and are exposed to the LLM through structured schemas. Every tool execution is serialized and tracked, with built-in safeguards such as output truncation and execution timeouts to maintain stability and cost-efficiency.

Sources: src/agent/setup.ts:88-90, src/agent/prompt.ts:182-192, CLAUDE.md:10-15

Tool Architecture and Registration

Tools are organized as a collection of AgentTool objects. The createTools function in src/tools/index.ts instantiates the standard suite, which is then registered during the agent setup process. Each tool defines a JSON schema for its parameters using TypeBox, ensuring that the LLM provides valid input.

The diagram shows the initialization and execution flow of the toolset within the agent harness.
Sources: src/tools/index.ts, src/agent/setup.ts:98-105

Core Tool Definitions

Bash Tool

The bash tool allows the agent to execute arbitrary shell commands. It uses child_process.spawn with setsid to create a new process group, allowing the agent to kill entire process trees (including children) if a timeout is reached.

Parameter	Type	Description
label	string	Brief description shown to the user.
command	string	The actual bash command to execute.
timeout	number (optional)	Execution limit in seconds.

Outputs are truncated to the last 2000 lines or 50KB to prevent context window overflow. If truncated, the full output is saved to a temporary file in the system's temp directory.
Sources: src/tools/bash.ts:13-25, src/tools/bash.ts:32-40, src/tools/bash.ts:92-105

Read Tool

The read tool is a multi-purpose utility for inspecting file contents. It supports both plain text and image files (jpg, png, gif, webp).

• Text Processing: Implements pagination via offset (1-indexed) and limit. It enforces a strict limit on output size (typically 100KB or 1000 lines).
• Image Processing: Detects image MIME types via binary header sniffing. If an image is detected, it attempts to resize the image before returning it as base64 data to the LLM.

Sources: src/tools/read.ts:11-20, src/tools/read.ts:28-45, src/tools/read.ts:50-70

Write and Edit Tools

File modification is handled through two distinct approaches: destructive overwriting and surgical replacement.

Tool	Logic	Key Safety Feature
write	Creates or overwrites a file with full content.	Automatically creates parent directories if they don't exist.
edit	Replaces a specific block of text (old_text) with new_text.	Fails if old_text appears zero or more than one time in the file.

The edit tool generates a unified diff string with line numbers and context lines (default 4) to provide feedback on the change.
Sources: src/tools/write.ts:15-22, src/tools/edit.ts:104-122, src/tools/edit.ts:10-20

Execution Lifecycle and Safety

Tool execution follows a strict sequence diagram to ensure that the user interface is updated and that the agent can be aborted.

This diagram illustrates the flow from an LLM tool-call request to the observation returned after interacting with the host system.
Sources: src/tools/bash.ts:25-27, src/tools/write.ts:18-19, src/agent/setup.ts:320-330

Operational Constraints

1. Working Directory: The agent's base working directory is determined at startup, typically mapping to /data in the Docker container, which is an EFS-backed persistent volume.
2. Environment Sync: The agent maintains a SYSTEM.md log to track environment modifications such as package installations (apk add, npm install) and configuration changes.
3. Output Truncation: Tools utilize a shared truncation utility to prevent excessive data from being sent to the LLM.
   • truncateHead: Used by read to show the beginning of a file.
   • truncateTail: Used by bash to show the most recent logs/output.

Sources: src/agent/prompt.ts:167-175, src/agent/prompt.ts:50-55, src/tools/bash.ts:8-10, src/tools/read.ts:9-10

Summary

The File System & Terminal Tools provide a robust interface for the pi-digby agent to perform engineering tasks. By combining high-level file operations (read, write, edit) with a powerful terminal interface (bash), the system allows the agent to function as a full-featured coding assistant while maintaining safety through timeouts, unique-string requirements for edits, and aggressive output truncation.