Skip to content

Tool reference ​

The built-in tools of a chat with loop:, by group. The catalog and permission modes are on Built-in tools.

File tools ​

read_file, write_file, edit_file, list_files, md5_file, and tail_file run in the agent loop with no setup and no API key. All six are python: blocks in their tool assets (see Built-in tools) and run on the system python. Before the tool runs, kdeps compares each path argument with KDEPS_WORKSPACE_ROOT and the root-directory guard.

kdeps permits paths under ~/.kdeps and /tmp with no prompt, also when the workspace root is a different folder. On Windows, the permitted temp directory is the process temp directory. kdeps blocks a directory that has only the same name, and it always blocks /. kdeps converts a relative path to the absolute path in the working directory. Then it checks that path and gives it to the script.

Permission modes, lean mode, and harness reminders stay on Built-in tools.

Each of these tools is also a workflow component. The component POSTs to /apis/tools.kdeps.io/v1/tools/{name}/call and passes file_path (path for list_files). The session's last file, match_id, and the colored diff stay in the agent loop.

File operations ​

Always available. No environment variables required.

ToolDescription
read_fileRead a text file with a 1-based line number on every line. PDF, DOCX, EPUB, RTF and ODT are refused with a pointer to load_document, which extracts their text
write_fileWrite or overwrite a file with the exact bytes given (no newline translation), then read it back to verify
edit_fileReplace or append on one line: line or match, then text or append
list_filesList directory contents
md5_fileCompute a file's MD5 hash - a low-cost way to check if the content changed
tail_fileRead the last N lines of a file without loading the whole thing

Line numbers ​

read_file prefixes every line with its 1-based number and renders it cat -A style: tabs as ^I, other control characters as ^X, and $ at the true line end ( 42⇥code$). Indentation, trailing whitespace and stray control characters stay visible. edit_file's line uses these numbers.

Size cap ​

read_file refuses a file, and write_file refuses content, larger than the file-read-limit event (1 MiB by default). The agent loop passes the event's value to the script. A workflow component that calls the tool gets the 1 MiB default.

yaml
# ~/.kdeps/events/file-read-limit.yaml
name: file-read-limit
on:
  bytes: 4194304  # read_file and write_file refuse anything past 4 MiB
run: reject

Optional file_path ​

read_file treats file_path as optional: omit it and it reads the file most recently read, edited, or written this session. This helps when the model means "the file that I read last" and calls read_file with only offset/limit. write_file, edit_file, md5_file, and tail_file always need an explicit path.

Colored diff ​

write_file and edit_file print a colored diff under the tool call: removed lines red, added green, with a few context lines. kdeps shortens large diffs (for example, a full new file). The diff shows only in the terminal. The model gets a short result.

Jumping from search_local to read_file with match_id ​

A search_local result that finds its query in a file carries match_id, line and revision besides path/snippet. Pass match_id to read_file instead of file_path to jump to that hit. context_before/context_after (default 20 each, like edit_file's anchor view) set how much code comes back:

xml
<invoke name="search_local">
  <parameter name="path">/app</parameter>
  <parameter name="query">func handleLogin</parameter>
</invoke>
json
{"results": [{"path": "/app/server.go", "match_id": "match-4a9f21bc", "line": 112, "revision": "sha256:...", "snippet": "..."}]}
xml
<invoke name="read_file">
  <parameter name="match_id">match-4a9f21bc</parameter>
  <parameter name="context_after">40</parameter>
</invoke>

A match_id is local to the process. kdeps keeps a maximum number of them and removes the oldest first. Use it to connect a search to a read in the same session. It is not a permanent reference. If kdeps cannot find a match_id (removed, or from a different process), it gives a clear error with the ID. An explicit file_path always has priority over match_id.

Line edits with edit_file are on Edit file.

Edit file ​

edit_file changes one line of an existing file. Give the line number (or words that are on the line). Then give the replacement text or the text to append. It is a declared python tool in tools/edit_file.yaml. That YAML file contains all of its behavior. Reads, whole-file writes and match_id are on File tools.

text
read_file (line numbers) -> edit_file {file_path, line | match, text | append} -> edited line(s), numbered

Replace a line ​

json
{"file_path": "/repo/app.py", "line": 12, "text": "    timeout = 30"}

Line 12 becomes timeout = 30. text can have several lines. They replace the one line.

If text has no indentation, the tool adds the indentation of line 12 to each line. "text": "timeout = 30" gives the same result.

Replace words on a line ​

json
{"file_path": "/repo/app.py", "line": 12, "match": "30", "text": "60"}

Only the first 30 on line 12 becomes 60. Without line, the tool uses the first line that contains match.

Append ​

json
{"file_path": "/repo/app.py", "line": 12, "append": "    retries = 3"}

The tool inserts retries = 3 after line 12. If you give no line and no match, the text goes after the end of the file.

Result and errors ​

The result is the edited line number and the line(s) as they now read:

text
edited /repo/app.py at line 12:
    12	    timeout = 60

A call fails and leaves the file unchanged when:

  • you give both text and append, or neither of them (an empty value is the same as no value, so text cannot clear a line)
  • line is outside the file, or the line does not contain match
  • no line contains match

To create or rewrite a whole file, use write_file.

Shell execution ​

bash_exec, one of the built-in tools, runs a shell command and returns its output to the model.

kdeps removes HTML escapes from a command before it validates and runs the command. If the text went through an HTML step before, some models write &amp;&amp; for &&, &quot; for ", or &lt;/&gt; for </>. kdeps does the same for sql_query, because an escaped comparison (WHERE x &lt; 5) is the same problem there.

A non-zero exit returns that output with the error. The model sees stderr and the end of stdout, not only exit status 1. A long go test log keeps the summary at the end.

Use these two related tools to manage background jobs:

ToolDescription
bash_job_listShow all background jobs with status (running/done/failed), elapsed time, and command
bash_job_waitBlock until a job completes and return its full output. Pass the job's job_id.

Set KDEPS_ALLOW_BASH=false to disable all three bash_* tools.

Memory and identity ​

memory_save, memory_search, memory_delete, and memory_query read and write the agent store during a turn. identity_get returns the configured name, email, and address. They are always registered. The rules for every tool are on Built-in tools.

Memory tools ​

Always available. You do not need environment variables.

memory_save, memory_search, and memory_delete run through the kdeps API. A call with no memory store returns memory_save: memory store is not configured, and the same sentence for memory_search and memory_delete. The agent attaches its store before the call.

memory_query runs through the kdeps API. An empty query returns memory_query: query is required. A call with no agent loop returns memory_query: agent loop is not configured (memory_query is an agent-mode tool). The agent installs the loop before the call.

ToolDescription
memory_saveSave a fact to persistent memory. Injected into every LLM call automatically.
memory_searchSearch memory entries by key or value. At most 20 matches, best first (key hit, then more query words, then newer); each value cut at 500 characters.
memory_deleteRemove a memory entry by key.
memory_queryRun an expr-lang relational query over agent state: memory (persistent entries) and tool_calls (recent tool call history). Supports filter(), map(), join(), union(). String matching is infix: .value contains "x", .key startsWith "x", .value matches "regex"; contains(...) is a parse error.

kdeps keeps memory for each project as markdown notes in the knowledge vault, <vault>/projects/<project>/memory/ (see Persistent memory). Facts stay across sessions. kdeps extracts facts from each turn automatically. A [MEMORY: key] value line saves a fact with no call to memory_save.

The memory_* tools are how the model reads and writes memory during a turn.

Identity tool ​

Always available. identity_get returns the agent's configured name, email, and address - see Agent Identity for how to set one. Returns "No identity configured for this agent." when unset. Never returns account credentials, even if configured. A model that can read a password can leak it in its own output.

Data tools ​

calculator, the SQLite tools, and the local embedding store are always on. The SQLite tools use db_path. If db_path is not set, they use KDEPS_SQL_DB_PATH. Wolfram, remote RAG, and the rerankers register only when you set their key or URL. They are declared HTTP tools, and their tool asset fully defines them. Before sql_query text runs, kdeps removes its HTML escapes, as for bash_exec.

Permission modes stay on Built-in tools.

Computation ​

ToolRequired env varDescription
calculator(none)Evaluate an arithmetic expression: numbers, + - * / // % **, parentheses and the math module's functions and constants (sqrt(16), log(8, 2), pi). A python: block in tools/calculator.yaml; exponents above 10000 are rejected
wolfram_alphaWOLFRAM_APP_IDWolfram Alpha queries

Data and SQL ​

The three SQLite tools are python: blocks in their tool assets (Python's built-in sqlite3). Each tool opens the file read-only (mode=ro), so a query cannot write to it. First, the tool compares db_path with KDEPS_WORKSPACE_ROOT. Paths under ~/.kdeps and /tmp are also permitted. sql_ops (named connections, any driver) stays in Go.

ToolRequired env varDescription
sql_list_tablesdb_path or KDEPS_SQL_DB_PATHList the tables in a SQLite file
sql_describe_tablesameThe table's CREATE TABLE statement
sql_querysameRun one SELECT or WITH query; tab-separated rows, column names first

Embeddings and reranking ​

ToolRequired env varDescription
embedding_vectorize(none)Convert text to embeddings and index it in the local embedding DB
embedding_search(none)Semantic search over the local embedding DB
retrieve_contextKDEPS_RAG_BASE_URLRetrieve chunks from a remote RAG endpoint (only registered when the URL is set)
cohere_rerankCOHERE_API_KEYRerank results using Cohere
voyageai_rerankVOYAGEAI_API_KEYRerank results using VoyageAI
jina_rerankJINA_API_KEYRerank results using Jina

Action tools ​

http_request, search_local, transcribe_audio, transcribe_audio_offline, ocr_image, and load_document are always on. Zapier and Google cache register when you set their credentials (the Zapier tools are declared HTTP tools). Commits the agent creates carry a co-author trailer. Permission modes stay on Built-in tools.

Git commit attribution ​

Commits that the agent creates have a co-author trailer with the names of kdeps and the model that wrote them. The trailer records the model that made the commit:

text
Co-Authored-By: kdeps (deepseek/deepseek-reasoner) <noreply@kdeps.com>

The model name changes with the location where the model runs:

ModelTrailer
Cloud providerkdeps (deepseek/deepseek-reasoner) <noreply@kdeps.com>
Cloud providerkdeps (openai/gpt-4o-mini) <noreply@kdeps.com>
Ollamakdeps (ollama/llama3.2) <noreply@kdeps.com>
llamafilekdeps (hfuser/gemma4-2-9b llamafile) <noreply@kdeps.com>
GGUFkdeps (hfuser/gemma4-2-9b gguf) <noreply@kdeps.com>

Cloud and Ollama model names start with the provider (provider/model). Local llamafile and GGUF names already have their HuggingFace namespace, so kdeps adds the runtime to the end. Often the same repository has both forms.

With no model configured, the trailer falls back to Co-Authored-By: kdeps <noreply@kdeps.com>.

A configured identity takes priority over all of the above: with identity.name/identity.email set, the trailer becomes Co-Authored-By: Sales Bot <sales-bot@example.com> and does not give the model name.

Actions and integrations ​

ToolRequired env varDescription
zapier_list_actionsZAPIER_NLA_API_KEYList available Zapier NLA actions
zapier_run_actionZAPIER_NLA_API_KEYExecute a Zapier NLA action
google_cache_createGOOGLE_API_KEYCreate a Google AI cached content object
google_cache_listGOOGLE_API_KEYList Google AI cached content objects
google_cache_deleteGOOGLE_API_KEYDelete a Google AI cached content object

google_cache_create, google_cache_delete, and google_cache_list run through the kdeps API. The agent registers them for the model only when you set GOOGLE_API_KEY. A call with the key unset returns google_cache_create: disabled (GOOGLE_API_KEY is unset), and the same sentence for google_cache_delete and google_cache_list.

Resource-backed tools ​

These always-on tools invoke the corresponding kdeps executor directly:

ToolDescription
http_requestMake an HTTP request (GET/POST/PUT/DELETE/PATCH)
search_localSearch files in a folder (path), or, with no path, every folder of the working project: its own and its search folders, best hits of each in turn. Dot-directories, vendor/build folders (node_modules, vendor, target, caches), and files over 1 MiB are skipped. Key and credential files are never returned
transcribe_audioTranscribe an audio file through a Whisper API (OpenAI, Groq, or a local HTTP server); a declared HTTP tool
transcribe_audio_offlineTranscribe offline with whisper.cpp (whisper-cli), no API key; a declared exec tool
ocr_imageExtract text from an image via tesseract (local, no API key); a declared exec tool
load_documentLoad and extract text from a document

Harness reminders ​

remind: true on a harness section puts its text onto every prompt and every tool result. Permission modes stay on Built-in tools.

Every prompt and every tool result ​

Each harness section has a normal place. A preamble section goes into the system prompt. A standalone entry operates only at its call site. Examples are a nudge, a praise line, and the compaction, judge, and refine prompts. remind: true overrides this.

The raw text of the section then goes onto each prompt, from the first turn. It also goes onto each tool result, also when its trigger does not occur.

yaml
# ~/.kdeps/harness/tools-reminder.yaml (or harness/ in the workflow project)
name: tools-reminder
kind: standalone
remind: true        # add this text to every prompt and every tool result
body: >-
  Every capability you have is a kdeps tool. Call it.

Use it for a model that needs guidance more often than its normal place gives: a sandbox habit, a recurring unwanted pattern, a house style. Each reminder adds its tokens to every turn and every tool result, so keep the text short.

  • Reminders are independent of disabled:. A disabled section can still be a reminder.
  • An override file replaces the shipped entry of the same name, so copy the shipped body: when you only want to add remind: true.

kdeps has the Apache 2.0 License.