Client Filesystem Plugin

Lets users attach a local folder (or drop individual files) from the browser so the agent can read and copy those files during the conversation. The folder stays on the user's machine; the server only sees contents when the agent or an @-mention actually reads a file.

Folder attach uses the browser File System Access API. It needs a Chromium browser (Chrome or Edge) and a secure context (HTTPS or localhost). Firefox and Safari are not supported. The conversation's browser tab must stay connected while the agent uses the folder tools.

Configuration

plugins:
  - module: codumentor.plugins.client_fs
    class: ClientFsPlugin
    args:
      enabled: true

Parameters

Key	Type	Default	Description
`enabled`	bool	`true`	Master switch.

Usage

Attach a folder

Click + in the chat input and choose Attach Local Folder
Grant permission when the browser prompts
A banner in the conversation shows the attached folder; the agent gets four tools scoped to it

After a reload, a long idle, or a revoked permission, the banner offers Resume access (one click, if the browser still has the handle) or Re-attach (pick the folder again).

Paths the agent uses are relative to the folder root (src/main.py, not my-folder/src/main.py). Use "." for the folder root.

Tool	Description
`client_fs_list_dir`	List directory contents
`client_fs_read_file`	Read a file from the attached folder
`client_fs_copy_from_repo`	Copy a repo file into the attached folder
`client_fs_copy_to_repo`	Copy a file from the attached folder into the repo

These tools appear only while a folder is attached and accessible.

The Document Editor can open a .docx from the attached folder and write it back on save.

@-mentions

Type @ plus part of a filename to search the attached folder. Choosing a result inlines that file's content into the message.

Attach a file or drag-and-drop

Attach File uploads one file. Drag files from the OS file manager onto the chat window to attach several at once. Oversized files are rejected with an alert.

Word and PDF uploads are converted to text for the agent. The original bytes are also staged so the agent can copy the file into a repo (for example "add the PDF I just uploaded"). If text cannot be extracted, the file is still staged so it can be copied as-is.

Limits (upload and drag-and-drop):

Text files: 200 KB
Binary documents (PDF, DOCX): 20 MB