Client Filesystem Plugin

The Client Filesystem Plugin lets users attach a local folder from their browser and give the AI agent read/write access to its files during the conversation. It uses the browser's File System Access API so the folder never needs to be uploaded to the server.

Overview

The Client Filesystem plugin:

1. Adds Attach Local Folder and Attach File buttons to the chat input menu
2. Supports drag-and-drop of files onto the chat window — no menu interaction needed
3. Registers client_fs_list_dir, client_fs_read_file, client_fs_copy_from_repo, and client_fs_copy_to_repo tools dynamically — only when a folder is attached to the conversation
4. Provides @-mention fuzzy autocomplete from the attached folder's file index
5. Supports single-file uploads with server-side text extraction (Word, PDF, etc.)

Configuration

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

Configuration Parameters

• enabled (optional): Whether the plugin is active (default: true)

Usage

Attaching a Folder

1. Click the + / attachment icon in the chat input area
2. Select Attach Local Folder
3. Choose a folder — the browser will request permission via the File System Access API
4. The folder name appears in the conversation and the agent gains four tools scoped to it

Agent Tools

Once a folder is attached, the agent has access to:

Tool	Description
client_fs_list_dir	List directory contents. Use "." for the folder root.
client_fs_read_file	Read a file from the attached folder.
client_fs_copy_from_repo	Copy a file from the server-side repo to the attached folder.
client_fs_copy_to_repo	Copy a file from the attached folder to the server-side repository.

All paths are relative to the folder root. Do not include the folder name as a prefix (use src/main.py, not my-folder/src/main.py).

@-Mention Autocomplete

Type @ followed by part of a filename to fuzzy-search across the attached folder's file index. Selecting a result inlines the file's content into the message before sending.

Single-File Upload

The Attach File button lets users upload an individual file. Binary formats (DOCX, PDF) are extracted to text server-side and made available to the agent.

Drag-and-Drop

Files can be dragged from the OS file manager and dropped anywhere onto the chat window. No menu interaction is required — the plugin listens for drag events as soon as its JavaScript bundle loads.

When files are dragged over the chat area, a semi-transparent overlay labeled "Drop files to attach" appears. On drop:

• Each file is uploaded via the same single-file upload flow as the Attach File button
• An attachment pill appears in the input area for each file
• Files are inserted as @-references so they're resolved when the message is sent
• Oversized files that exceed the size limits show an alert instead of being attached

Multiple files can be dropped at once (using a single drag gesture with multiple selected files in the file manager).

Limits (same as single-file upload):

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

How It Works

File reads use browser-side RPC: when the agent calls client_fs_read_file, the backend sends an RPC request over the active WebSocket connection to the browser, which reads the file using the File System Access API and returns the content. This means:

• The folder contents stay on the user's machine; the server only receives individual file contents when the agent explicitly requests them
• The session must have an active browser tab connected for file read/write tools to work
• Tools are injected into the prompt dynamically — they only appear when a folder is attached for the current conversation

UI

Widget	Element	Placement	Description
Attach Local Folder	x-client-fs-menu-item	input-menu	Folder attachment button
Attach File	x-client-fs-file-item	input-menu	Single-file upload button

Drag-and-Drop Overlay

The drop overlay is created dynamically by the plugin's JavaScript bundle — it is not part of the React component tree. The plugin injects a <style> tag and appends a <div class="client-fs-drop-overlay"> inside .chat-container on first drag, then shows/hides it using the .active class.

The .chat-container element has position: relative to anchor the overlay's position: absolute; inset: 0 positioning.

Conversation ID Resolution

The drop handler needs the active conversation ID to associate uploaded files with the correct conversation. It resolves the ID in two ways (in order):

1. From custom element attributes — when either x-client-fs-menu-item or x-client-fs-file-item is mounted, it updates a module-level currentConversationId variable
2. From the URL — if no custom element has been mounted yet (e.g., the input menu was never opened), the handler parses /c/{id} from window.location.pathname

This means drag-and-drop works immediately on page load without requiring any user interaction with the input menu.