AI Pilot tools reference

AI Pilot acts through a fixed set of tools. The model decides which tool to call; kaiport carries it out, applies the approval rules and hands the result back to the model. This page lists every tool with its parameters and limits. The tool names also appear in the audit log file ai-audit.jsonl.

Overview

Terminal tabs are SSH connections; storage tabs are FTP, S3, WebDAV and Azure connections in the transfer view.

The connection's Denied commands (AI) and Allowed commands (AI) apply to run_command. read_file and search_files need Send file contents to the AI. See Approvals and safety for the rules in detail.

Terminal tools

run_command

Types a command line into the interactive terminal – the one you see – presses Enter and waits until the shell shows its prompt again.

The result contains the status, the output, the exit code (with shell integration), the duration and the detection method.

Before a command runs, kaiport checks it against the connection's denied and allowed commands and against the list of dangerous commands.

send_input

Sends text and/or a special key to the terminal without waiting for a prompt – to answer a question, quit a program or move around in a full-screen program. Returns the screen afterwards.

read_screen

Returns the text currently visible in the terminal – to follow a long-running command, an interactive program or something you did in the terminal yourself. The optional wait_seconds (0 to 120) waits before reading.

File tools

In terminal tabs, the file tools work over SFTP on the connected system. In storage tabs, they have an extra parameter side: remote for the storage (the default) or local for your computer. Paths are absolute; remote paths start with /.

read_file

Reads a text file (path). Needs Send file contents to the AI. Binary files are refused, and files over 2 MB can't be read. The content handed to the model is capped at Limit per file (KB); a longer file keeps its beginning and its end.

write_file

Creates a file or replaces it completely (path, content). AI Pilot is instructed to read a file before it changes it and to tell you what it changed. In storage tabs, replacing an existing file always needs your approval.

list_dir

Lists a folder (path) with name, type, size, modification date and permissions of each entry. Up to 500 entries are returned.

find_files

Finds files and folders below a folder by metadata only, without reading contents.

search_files

Searches the text files below a folder and returns the matching lines with path and line number – never whole files. Needs Send file contents to the AI.

The search goes up to 6 folder levels deep. At most 100 matching lines are returned, each cut to 200 characters. Binary files and files larger than Limit per file (KB) are skipped. The result lists every file that was read; the card shows the list under Files read.

folder_report

Statistics of a folder tree (path, optional max_depth: 6 by default, at most 12) from metadata only: the number of files and folders and the total size, sizes by file type and extension, the age distribution, the 10 largest files, the 5 oldest and the 5 newest, up to 20 possible duplicates (same name and size), up to 20 empty folders and up to 20 cleanup candidates – temporary files, logs older than 30 days, backups older than 90 days and files over 10 MB unchanged for more than a year.

Storage tools

These tools only exist in storage tabs.

make_dir

Creates a folder (path, side), including missing parent folders where the storage supports that.

rename

Renames or moves a file or folder within the same side (from, to, side). Moving onto an existing name always asks.

delete

Deletes a file or folder (path, side). A folder with contents is only deleted with recursive set to true, which removes everything inside. Always asks.

upload and download

upload copies a file from your computer (local_path) into a folder of the storage (remote_dir). download copies a file from the storage (remote_path) into a folder on your computer (local_dir). Both handle single files, not folders. Replacing an existing file always asks. The transfers appear in the transfer view's Transfers list.

execute_plan

Carries out a list of operations after one approval.

A plan holds up to 200 operations. Operations with missing fields or an unknown op are left out, and AI Pilot is told which. The steps run in order; the first failure stops the plan, and the remaining steps are reported as skipped. A plan always needs your approval. It is marked dangerous when it deletes something or would replace an existing file.

ask_user

Asks you a question (question) with up to five suggested answers (options). You can always type your own answer instead. kaiport never answers a question automatically, not even in Autopilot. If you stop the request instead of answering, AI Pilot is told that you didn't answer.

Command-end detection

To know when a command has finished, kaiport keeps a model of the terminal screen in the background and uses one of two methods. The expanded card shows which one under Detection:

• shell integration – with kaiport's shell integration (OSC 133), the shell reports the end of every command with its exit code. This is exact.
• heuristic – without it, kaiport treats a command as finished when the output has been quiet for about half a second and the cursor line looks like a prompt – it matches the prompt kaiport saw when the session started, ends in a prompt character such as $, #, %, > or ❯ or a Powerline separator, or follows a user@host pattern. There is no exit code; when AI Pilot needs one, it can append ; echo "exit=$?" to the command.

Timeouts

Output limits