LM Studio Tool Plugin - Filesystem Access

Source code | LM Studio listing

Allows filesystem access for the following actions:

• write_file
• read_file
• delete_file
• copy_file
• move_file
• create_directory
• delete_directory
• copy_directory
• move_directory
• list_files
• path_exists
• find_file

JSON Response Contract

All tools now return a JSON string with one of the following shapes:

Error Object

• code: stable machine-readable error code
• message: human-readable explanation

Current error codes include:

• DIR_NOT_SET

path_exists can also return:

• PATH_OUTSIDE_BASE

move_file can also return:

• SOURCE_PATH_OUTSIDE_BASE
• DESTINATION_PATH_OUTSIDE_BASE
• SOURCE_EQUALS_DESTINATION
• SOURCE_FILE_NOT_FOUND
• SOURCE_NOT_FILE

copy_file can also return:

• SOURCE_PATH_OUTSIDE_BASE
• DESTINATION_PATH_OUTSIDE_BASE
• SOURCE_EQUALS_DESTINATION
• SOURCE_FILE_NOT_FOUND
• SOURCE_NOT_FILE
• DESTINATION_IS_DIRECTORY
• DESTINATION_EXISTS

copy_directory can also return:

• SOURCE_PATH_OUTSIDE_BASE
• DESTINATION_PATH_OUTSIDE_BASE
• SOURCE_EQUALS_DESTINATION
• DESTINATION_INSIDE_SOURCE

move_directory can also return:

• SOURCE_PATH_OUTSIDE_BASE
• DESTINATION_PATH_OUTSIDE_BASE

File Move Behavior

move_file moves a file from source_path to destination_path within the configured base directory.

• Both paths must resolve inside the configured base directory.
• source_path must exist and be a file.
• If destination exists and overwrite is not true, the tool returns DESTINATION_EXISTS.
• If needed, parent directories for destination_path are created automatically.

File Copy Behavior

copy_file copies a file from source_path to destination_path within the configured base directory.

• Both paths must resolve inside the configured base directory.
• source_path must exist and be a file.
• Source and destination cannot be the same path.
• If destination exists and overwrite is not true, the tool returns DESTINATION_EXISTS.
• If needed, parent directories for destination_path are created automatically.

Directory Copy Behavior

copy_directory copies a directory from source_path to destination_path within the configured base directory.

• Both paths must resolve inside the configured base directory.
• source_path must exist and be a directory.
• Source and destination cannot be the same path.
• Destination cannot be nested inside source.
• If destination exists and overwrite is not true, the tool returns DESTINATION_EXISTS.

Directory Move Behavior

move_directory moves a directory from source_path to destination_path within the configured base directory.

• Both paths must resolve inside the configured base directory.
• source_path must exist and be a directory.
• Destination cannot be the same as source, and cannot be nested inside source.
• If destination exists and overwrite is not true, the tool returns DESTINATION_EXISTS.
• If needed, parent directories for destination_path are created automatically.

File Delete Behavior

delete_file deletes a single file at file_name within the configured base directory.

• The resolved path must stay inside the configured base directory.
• The target must exist and be a file (not a directory).
• On success, the tool returns deleted: true with file_name and relative_path.

Directory Delete Behavior

delete_directory deletes a directory at directory_path within the configured base directory.

• The resolved path must stay inside the configured base directory.
• The target must exist and be a directory (not a file).
• By default recursive is false; non-empty directories return DIRECTORY_NOT_EMPTY.
• Set recursive: true to delete non-empty directories.

File Search Behavior

find_file searches recursively inside the configured base directory:

Example find_file success payload:

Path Input Rules

write_file, read_file, find_file, and create_directory accept names with spaces and common path characters. Path safety is enforced by keeping all resolved paths inside the configured base directory.

Path Exists Behavior

path_exists checks whether a path exists inside the configured base directory.

• If the path exists, it returns exists: true and path_type as file or directory.
• If the path does not exist, it returns ok: true with and .

Testing

This project uses vitest for unit tests.

Install dependencies and run tests:

Watch mode:

Coverage report:

Coverage output is generated in coverage/ with HTML (coverage/index.html) and lcov formats. The coverage run includes a threshold gate and fails if global coverage drops below: statements 80%, lines 80%, functions 70%, branches 60%.