agent-tool

Returns usage guide for agent-tool. Call this when you encounter encoding warnings, garbled text, or need to understand agent-tool features. Topics: overview, encoding, indentation, tools, troubleshooting.

Creates a timestamped zip backup of a directory. Output: {dirname}_{YYYYMMDD_HHMMSS}.zip Default excludes: .git, node_modules, __pycache__, binaries. Custom excludes can be added via the excludes parameter.

Computes a hash checksum of a file. Reads the file as raw bytes (no encoding conversion). Supported algorithms: md5, sha1, sha256 (default).

Compresses files and directories into an archive. Supports .zip and .tar.gz formats. Output format is determined by the file extension.

Converts a file's encoding to a different character set. Reads the file with auto-detected encoding, then rewrites it in the target encoding. Supports: UTF-8, UTF-8-BOM, EUC-KR, Shift_JIS, ISO-8859-1, UTF-16, ASCII, Windows-1252, Big5, GB18030. Example: convert EUC-KR file to UTF-8, or add/remove UTF-8 BOM.

Extracts an archive to a directory. Supports .zip and .tar.gz formats. Includes Zip Slip and Zip Bomb protection. Symlinks are skipped for security.

Deletes a single file. Safety: no directory/symlink deletion, no path traversal, no system files, TOCTOU protection. Use dry_run=true to preview.

Compares two files and outputs a unified diff. Encoding-aware: auto-detects file encoding before comparison. Max 50,000 lines per file.

Replaces old_string with new_string in the specified file. Smart indentation: auto-converts between tabs and spaces to match the file's style. Encoding-aware: preserves original file encoding (UTF-8, EUC-KR, Shift-JIS, UTF-8 BOM, etc.). Reads .editorconfig for indentation settings. Use dry_run=true to preview changes without modifying the file.

Reads environment variables. Returns a single variable by name, or lists all with optional filter. Sensitive values (passwords, tokens, keys) are automatically masked for security.

Returns detailed file metadata: size, encoding, line ending, indentation style, and line count. Uses the same encoding detection as read/edit (chardet + .editorconfig).

Discovers installed development tools (compilers, build systems, runtimes) on the system. Returns paths and versions for: Go, .NET/MSBuild, Node.js, Python, Java, Rust, C/C++ (GCC/Clang/MSVC), CMake, Make, Git, Docker, Bun, Deno. Use this before running build commands to avoid PATH issues. Searches environment variables, PATH, and known installation directories.

Reads firewall rules (read-only). Linux: iptables/nftables/firewalld. Windows: netsh advfirewall. Use filter to search by rule name or port number. May require elevated privileges on Linux.

Finds files matching a glob pattern. Supports ** for recursive directory matching. Returns matching file paths sorted by modification time (newest first). Skips hidden directories (.git, etc.) and common vendor directories. Use relative_paths=true to return paths relative to the search directory (saves tokens).

Searches file contents for a regex pattern. Encoding-aware: auto-detects file encoding. Can search a single file or recursively search a directory. Supports glob filtering and case-insensitive search.

Lists directory contents in a tree structure. Shows files and directories with visual tree connectors (├── └──). Skips hidden directories and common build/vendor directories. Use max_depth to control traversal depth (default: 3). Use relative_paths=true to show root as '.' instead of full path (saves tokens).

Applies a unified diff patch to a file. Parses @@ hunk headers, verifies context lines, and applies changes. Encoding-aware: preserves original file encoding. Use dry_run=true to preview without modifying the file.

Execute a command as a new process. Supports background execution and starting in suspended state. WARNING: This tool executes arbitrary commands on the host system. Use with caution. Use suspended=true to start a process in suspended state (Windows: CREATE_SUSPENDED, Linux: SIGSTOP). Use prockill with signal=cont to resume a suspended process.

Kills, suspends, or resumes a process by PID or port number. Supports tree kill (process + all children), signal selection (kill/term/hup/int/stop/cont). Use signal=stop to suspend and signal=cont to resume a process. On Linux, can detect and handle zombie processes by signaling their parent. Use dry_run=true to preview which processes would be affected. Safety: refuses to target PID 0/1 or the agent-tool process itself.

Lists running processes with PID, name, command line, and memory usage. Sensitive information in command-line arguments (passwords, tokens) is automatically masked. Use filter to search by process name, or port to find processes using a specific port.

Reads a file and returns its contents with line numbers. Encoding-aware: auto-detects file encoding (UTF-8, EUC-KR, Shift-JIS, etc.). Supports offset/limit for reading specific line ranges. Negative offset reads from end (e.g. offset=-5 reads last 5 lines).

Renames or moves a file/directory. Atomic operation via os.Rename. Use dry_run=true to preview.

Changes agent-tool runtime configuration. Supports: fallback_encoding, encoding_warnings, max_file_size_mb, allow_symlinks, workspace. Call with no arguments to view current configuration. Example: set fallback_encoding to "EUC-KR" for Korean legacy projects.

Transfer files and manage remote filesystems over SSH (SFTP protocol). Reuses SSH session pool — same authentication and session reuse as the ssh tool. Operations: upload (local to remote), download (remote to local), ls, stat, mkdir, rm, chmod, rename. Async operations: upload_async, download_async (returns transfer_id immediately), status (check progress), cancel. Max file transfer size: 2 GB. Use overwrite=true to replace existing files. Recursive delete is limited to 10,000 items for safety.

Execute commands on a remote server via SSH. Supports password and key-based authentication. SSH agent is used as fallback on Unix. Sessions are automatically pooled and reused for the same host:port:user combination. Idle sessions expire after 10 minutes. Supports IPv6 addresses and ProxyJump (jump_host) for reaching servers through bastion hosts.

Returns system information: OS, CPU cores, RAM, disk space, CPU usage. Set duration_sec (1-20) to measure CPU usage over time.

Creates or overwrites a file with the given content. Encoding-aware: preserves original encoding for existing files, uses .editorconfig hints for new files. Auto-creates parent directories if they don't exist.