Built-in tools

The default Step tools use names such as read_file and run_command. Native tools use names such as read and bash. Match arguments to the tool that is actually registered.

​

Tool overview

Step tool	Corresponding native tool	Purpose
read_file	read	Read text and images
write_file	write	Create or overwrite files
edit_file	edit	Replace exact text
run_command	bash / powershell	Run commands
search_files	grep	Search file contents
find_files	find	Find files by name or glob
list_directory	ls	List a directory

​

read_file

Supports text files and JPG, PNG, GIF, WebP, and BMP images. Set path to the file. Use start_line and end_line for line ranges, and max_chars to cap returned characters. Images are returned as attachments; model support determines whether they can be used for inference.

​

run_command

Use command for the command, cwd for its directory, and max_output_chars to limit returned text. The foreground timeout defaults to 120 seconds (from v0.1.3); adjust it with timeout_ms, which accepts 1000 to 600000 milliseconds.

On Windows, Bash commands prefer native Git Bash and do not switch to WSL automatically; PowerShell is a separate execution path. To use WSL, start Step inside WSL or configure the matching shellPath.

run_in_background starts a detached process and returns its PID and log file. Inspect the log for status and use the returned stop command for cleanup. Remaining processes are cleaned up at session end. In background mode, timeout_ms and max_output_chars do not apply. For input-box ! and !! commands, see Interaction and task control.

​

edit_file

Performs an exact text replacement in a single file. The model-facing edit_file uses path, search, replace, replace_all, and then_run; search is the literal text to find (not a regular expression), and replace is the new text. search must match uniquely by default, and repeated matches report an error; set replace_all=true to replace every match. Read the file again after a match failure to avoid editing stale content.

​

write_file

Use path and content to create or completely overwrite a file. Use edit_file for changes that preserve other content.

From v0.1.3, both tools accept the optional then_run parameter to run a verification command after a successful change and return its result. The command follows normal approval; a failed verification does not undo the written file.

​

search_files

The model-facing search_files uses pattern, path, glob, context_lines, and max_results, where pattern is a regular expression. The backend order is ripgrep (downloaded automatically or from the system) > git grep (inside Git repositories) > POSIX grep, reporting an error when none are available. See Data paths for search-tool caches.

​

find_files

Use path, pattern, and max_results to find files by name or glob. Inspect returned paths with a read tool.

​

list_directory

Use path for the directory, include_hidden for hidden entries, and max_entries for the result limit.

​

Enabling and disabling tools

defaultTools selects native built-in tools. For example:

defaultTools = ["read", "grep", "find", "ls"]

Step and extension tools require separate selection. A native tool configuration is not a read-only boundary for the entire session. Native read uses offset / limit, and native edit uses fields such as oldText; these are distinct from the Step tool arguments above.

Launch option	Purpose
--tools	Select tools by registered name
--exclude-tools	Exclude named tools
--no-builtin-tools	Disable native built-in tools
--no-tools	Disable all tools

See Permissions and safety for approval and access boundaries, and The step command for launch options.