kdeps-tools-list_files
v2.0.0List files and directories in a given directory path. Returns names and types (file/dir). Use to discover project structure before reading or editing files. Omit path to list the current working directory.
set tools / shelf tools
LLM context: ~96 tokens when loaded (prompt or tool definition)
Where it runs
Part of the tools set, used in workflow and agent mode. What the model is told about each built-in tool: its description, usage notes and parameters. kdeps runs the tool itself.
- the agent loop builds the request
- the tool definitions are sent to the modeltools/list_files
- the model calls a tool
- kdeps runs it
- the result goes back to the model
Loaded by: kdeps (agent loop), /update, /settings, kdeps run, kdeps install, kdeps list, kdeps uninstall, kdeps update
In the code: kdeps (agent loop)agent.RegisterBuiltinToolsagent.definedAs
Install
A kdeps asset: installed with the first-run profile that includes its set, or the first time a command needs it, and updated without a new release.
Pin a version with kdeps install tools/list_files@<version>.
Contents
List files and directories in a given directory path. Returns names and types (file/dir). Use to discover project structure before reading or editing files. Omit path to list the current working directory.
| Parameter | Type | Description |
|---|---|---|
| path | string | Path to the directory to list (absolute, or relative to the working directory). Omit to list the current working directory. |
Python script (declared in YAML, no Go code)
import json, os, sys
a = json.loads(sys.argv[1])
d = str(a.get("path") or "").strip() or os.getcwd()
d = d if os.path.isabs(d) else os.path.abspath(d)
# An omitted path is the working directory, which the paths: check skips.
if os.path.dirname(d) == d and os.environ.get("KDEPS_ALLOW_ROOT", "").strip().lower() != "true":
sys.exit("list_files: operation on root directory '/' is blocked (set KDEPS_ALLOW_ROOT=true to permit)")
try:
entries = sorted(os.scandir(d), key=lambda e: e.name)
except OSError as e:
sys.exit("list_files: read %s: %s" % (d, e.strerror or e))
print(d + ":")
for e in entries:
print(" [%s] %s" % ("dir" if e.is_dir(follow_symlinks=False) else "file", e.name))
Paths kept in the workspace: path
aliases:
- ls
- list_dir
- list_directory
- dir
version: 2.0.0
aliases: [ls, list_dir, list_directory, dir] # other names a model may call it by; the model is shown only this tool's name
description: List files and directories in a given directory path. Returns names and types (file/dir). Use to discover project structure before reading or editing files. Omit path to list the current working directory.
parameters:
path:
type: string
description: Path to the directory to list (absolute, or relative to the working directory). Omit to list the current working directory.
python:
paths: [path] # checked against the workspace boundary
script: |
import json, os, sys
a = json.loads(sys.argv[1])
d = str(a.get("path") or "").strip() or os.getcwd()
d = d if os.path.isabs(d) else os.path.abspath(d)
# An omitted path is the working directory, which the paths: check skips.
if os.path.dirname(d) == d and os.environ.get("KDEPS_ALLOW_ROOT", "").strip().lower() != "true":
sys.exit("list_files: operation on root directory '/' is blocked (set KDEPS_ALLOW_ROOT=true to permit)")
try:
entries = sorted(os.scandir(d), key=lambda e: e.name)
except OSError as e:
sys.exit("list_files: read %s: %s" % (d, e.strerror or e))
print(d + ":")
for e in entries:
print(" [%s] %s" % ("dir" if e.is_dir(follow_symlinks=False) else "file", e.name))
Versions
| Version | Published | Status |
|---|---|---|
| 2.0.0 | 10/24/2026 | active |
| 1.1.0 | 10/17/2026 | active |
| 1.0.0 | 10/11/2026 | active |
Details
- Author
- kdeps
- License
- Apache-2.0
- Latest Version
- 2.0.0
- Published
- 10/11/2026