Built-in Tools
zqagent includes 21 built-in tools, categorized as follows (tool names appear in approval cards):
| Category | Tools |
|---|---|
| File | read_file, write_file, replace_in_file, list_files, grep |
| Shell | run_shell (executes commands consecutively in the same shell session; in Auto mode, allowlisted commands are automatically permitted), shell_task_output, shell_task_kill (manage background tasks of run_shell) |
| Network | web_search, web_fetch |
| Git | git_log, git_status, git_diff (read-only) |
| Patch | apply_patch, apply_unified_diff |
| Collaboration | ask_user, propose_plan, request_directory |
| Task | todo_write (shared progress state) |
| Sub-agent | explore (sub-agent, read-only research) |
| Media | media (ffmpeg / ffprobe wrapper: probe metadata, trim, transcode, extract audio track, extract frames, thumbnails, compress) |
File
read_file— Read file contentswrite_file— Write (create or overwrite) a filereplace_in_file— Exact string replacement, suitable for local modificationslist_files— List directory structuregrep— Search file contents by regex
Shell
run_shell executes commands consecutively in the same shell session. In Auto mode, the command allowlist is automatically permitted; in interactive mode, you can always allow specific commands with C (safer than allowlisting the entire tool).
Long-running commands can be sent to the background with run_in_background; after returning a task_id, use shell_task_output to view cumulative output and run status, and shell_task_kill to terminate (along with the child process tree).
The shell used is selected automatically by the runtime: macOS / Linux use Node's default /bin/sh (behavior unchanged); Windows prefers a POSIX-style shell (BusyBox-w32 in the same directory → Git Bash → PowerShell), and only falls back to cmd.exe if none are available, writing the selected shell into the tool description to remind the model to adjust command style. You can override with ZQAGENT_SHELL (keyword or executable path) and ZQAGENT_BUSYBOX; see the README section "Multi-platform packaging and release → Shell and search on Windows" for details.
The grep tool prefers the embedded / installed ripgrep, falling back to the built-in pure Node scanner when missing (full JS regex support), and works directly in pure Windows environments as well.
When the traditional Windows console (cmd.exe/conhost) cannot render emoji and Unicode table borders, the CLI automatically degrades to ASCII markers (✅→[OK], ❌→[x], ⚠️→[!] …); modern terminals such as Windows Terminal / VS Code terminal retain emoji. Use ZQAGENT_EMOJI=1/0 to force enable/disable.
Network
web_search— Web searchweb_fetch— Fetch web page content
Git (read-only)
git_log / git_status / git_diff read-only view of repository history and status.
Patch
apply_patch / apply_unified_diff apply code patches, suitable for batch modifications.
Collaboration
ask_user— Ask the user a questionpropose_plan— Submit a plan proposalrequest_directory— Request a working directory
Task and Sub-agent
todo_write— Maintain shared task progressexplore— Launch a sub-agent for read-only research
Media
media wraps the local ffmpeg / ffprobe, with a single tool covering metadata probing (probe), trimming, transcoding, audio track extraction, frame extraction, thumbnails, and compression, without going through the shell.
ffmpeg is located via a four-level fallback: ① environment variables ZQAGENT_FFMPEG / ZQAGENT_FFPROBE → ② workspace <workspace>/.agent/bin → ③ single-file embedded resources / PATH → ④ if none are found, structured guidance is returned (including op="setup" to automatically download official static builds, run_shell install commands, manual installation, and environment variable syntax). Install commands and license notices for each platform are in the return value's install_commands / notes.
Viewing and Disabling
Enter /tools in the CLI to list all tools (including source, risk, and disabled status), use /tool disable <name> to temporarily disable and /tool enable <name> to re-enable.