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.

Access profiles

The folder holds the user's own files, and the server-side half of every copy
resolves through whatever the sandbox mounted for that turn. So this plugin
works for a user with every repository and for one with none — a
chat-only tier attaches a folder, the agent reads a document out of it, edits it
in the empty workspace and writes the result back. What it cannot express is a
partial scope (repos: [names]): client_fs_copy_from_repo names a path in
the working directory, and nothing downstream re-derives which repository that
path came from. For such a profile the tools are withheld and the plugin's HTTP
routes return 403. See Access Profiles.

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, PDF and Excel uploads are converted to text for the agent. Any other file (a zip, say) is staged as-is for the agent to inspect with a shell tool. The original bytes are always staged so the agent can copy the file into a repo (for example "add the PDF I just uploaded").

Limit (upload and drag-and-drop): 50 MB per file.