File Explorer

Bundled file explorer module for browsing, editing, and uploading filesystem content.

What it does

file-explorer is a bundled module for navigating filesystem paths in the running Clapilot environment (workspace/container-mounted paths). It combines a Finder-style file table with an inline editor/preview pane: browse and search folders, open and edit text files, preview browser-renderable documents, create folders, and upload individual files or whole folders.

Since March 6, 2026, file-explorer is rendered directly inside the React app shell instead of an iframe (it was the first bundled module to move). The module backend contract stayed unchanged; only the UI host moved into the standard Clapilot view hierarchy.

How to open it

Web: /modules/file-explorer (bundled module, slug file-explorer; manifest bundled-modules/file-explorer/module.json, entry: index.html, renderer: react, icon folder).
Backend: bundled-modules/file-explorer/api/handler.mjs.
React host UI: src/components/modules/file-explorer-module.tsx; route integration: src/app/(app)/modules/[slug]/page.tsx.
Legacy bundled frontend assets remain in bundled-modules/file-explorer/ui/index.ts (compiled to ui/index.js) but are not the active runtime while renderer is react.

Key workflows

Browse and search

Pick a root or type a path in the path selector; absolute and relative navigation are supported, with back/forward history buttons.
Sort the Finder-style table by name, modified time, size, or type (ascending/descending).
Use the search input to search the currently opened folder and all subfolders by name (GET /search). Results show the relative subfolder location under each entry name; a truncation hint appears when the capped recursive walk stops early.
The last opened directory is restored after a browser reload: the current path is mirrored into the ?path= URL query parameter and into localStorage, so reloading (or sharing the URL) reopens the same folder. If the remembered path no longer exists, the module falls back to the default root.

Open, preview, and edit files

Open a text file to edit it in the inline editor canvas on the right side of the file list, then save it back (POST /save-file).
Images, PDFs, audio, and video render inline in the right-side preview pane instead of falling back to the text editor; browser-renderable files are not blocked by a fixed inline preview size limit.
Download fetches the raw file.

Manage and upload

Row actions: Open, Download, Copy Path, Rename, Delete, New Folder Here, Upload Files/Folder Here. They are available both from the row ... dropdown and from a right-click context menu on any row.
Right-clicking the empty list area opens a folder context menu with New Folder, Upload Files, Upload Folder, and Refresh for the current directory.
Create-folder, rename, and delete flows use app-styled dialogs (no browser-native prompt/confirm).
Folder upload uses browser directory selection (webkitdirectory) and preserves nested relative paths.
Drag & drop supports both individual files and folders and uploads into the currently open directory. Single-file uploads go through the same upload-folder endpoint as folder uploads.

How the agent can drive it

The File Explorer is UI-only: there are no file_explorer_* agent tools. Agents that need filesystem access use their native runtime shell/file tool contracts instead. Other clients may reuse the module API directly — for example, the Apple client downloads chat media through the authenticated GET /api/modules/file-explorer/api/download route.

Module API reference

Base: /api/modules/file-explorer/api

Route	Purpose
`GET /roots`	list available root paths
`GET /list?path=<path>`	list a directory
`GET /search?path=<path>&q=<query>`	recursive name search under a directory; returns `{ results, truncated }`, capped at 200 results / depth 12 / 25k scanned entries / 8s, skipping `node_modules`, `.git`, `.next`, and `/proc`, `/sys`, `/dev`, `/run`
`GET /file?path=<path>`	read file content
`GET /download?path=<path>`	download raw file
`POST /mkdir` (`{ path }`)	create a folder
`POST /rename` (`{ path, newName }`)	rename a file/folder
`POST /delete` (`{ path }`)	delete a file/folder
`POST /upload-folder` (`multipart/form-data` with `targetPath` + repeated `files`)	upload files or whole folders
`POST /save-file` (`{ path, content }`)	save inline-edited text content

Configuration & limits

Paths are restricted to the roots exposed by GET /roots (workspace/container-mounted paths of the running Clapilot environment).
The module uses the same app-shell layout behavior as native Clapilot pages, so chat/sidebar sizing is handled by the main React hierarchy instead of iframe host offsets.

Troubleshooting

A file opens as garbled text: non-text formats render in the preview pane only when the browser can display them; other binary formats should be downloaded instead of opened.
Uploads land in the wrong place: drag & drop always uploads into the currently open directory; navigate there first or use Upload Folder Here on the target row.