File Explorer

The File Explorer is a hands-on, VSCode-style surface for browsing and editing files by hand in your coding workspace -- the human counterpart to the agent's coding tools, over the same workspace and the same security boundary. Use it when you want to make a small, precise change yourself instead of asking the assistant.

The feature is opt-in and off by default. Turn it on with FILE_EXPLORER_ENABLED=true.

Enabling it

The File Explorer edits files inside the coding workspace, so it reuses the coding tools' security boundary. You need both:

FILE_EXPLORER_ENABLED=true
CODING_ENABLED=true
CODING_WORKSPACE_DIR=/path/to/your/workspace

When FILE_EXPLORER_ENABLED is off, the launcher icon is hidden, /files is not offered, and the API is inert -- the runtime is unchanged.

Opening it

Two ways, both opening the same full-screen overlay:

• Click the file-tree icon in the sidebar footer (next to the Cron icon).
• Type /files in the chat input.

The layout

The overlay is split left/right, with an adjustable divider you can drag:

• Left -- file tree. A tree rooted at your workspace, loaded one level at a time. A single click selects an item (clicking a folder also expands/collapses it); double-click a file to open it in a tab (pressing Enter opens it too). Right-click a node for its actions (folders and files show the right options):
  • On a folder: New File, New Folder, Download as ZIP, Rename, Delete.
  • On a file: Open, Download, Rename, Delete. Rename opens a small dialog for the new name. You can also drag an item onto a folder to move it.
• Right -- editor. A tabbed monaco editor (the editor that powers VS Code), in a light theme. Open several files as tabs; each tab shows a dot when it has unsaved changes. The editor's own right-click menu provides Copy / Cut / Paste / Find and more; a tab's right-click menu adds Download. Text files open in the editor; PDFs and images open in a built-in viewer (see below). You can also split the editor into groups and drag tabs between them (see below).

Editing, saving, and deleting

• Open -- opening a file shows a brief loading indicator, then its contents in a tab.
• Save -- press Ctrl/Cmd+S or click Save. A pending indicator shows until the save completes.
• Delete -- deleting a file or folder asks for a final confirmation ("cannot be undone") and shows a blocking indicator until it finishes. Deleting a folder removes its contents.
• Tabs -- right-click a tab for Close, Close Others, or Close All.
• Unsaved changes -- any close that would drop unsaved work asks first: closing a tab, a bulk close that includes unsaved tabs, or closing the whole explorer. For the explorer close, confirming discards your in-progress edits and reopens those files in their saved state next time -- because someone else may be editing the same file, you should not be locked into your local draft.

Uploading files and folders

Bring local files -- and whole folders -- into the coding workspace from your browser:

• Upload files. Click the Upload files icon in the tree toolbar to upload into the workspace root, or right-click a folder and choose Upload files here. Select one or more files.
• Upload a folder. Click the Upload folder icon (or a folder's Upload folder here) and pick a folder -- its structure is recreated under the target directory.

Multiple files are supported, and an animated progress bar shows the overall upload progress across all files; the tree refreshes when the upload finishes. An existing file is overwritten (last-write-wins). Uploads are bounded by FILE_EXPLORER_MAX_UPLOAD_BYTES (100 MiB total per upload by default) and FILE_EXPLORER_MAX_UPLOAD_FILES (500 files per upload by default); an over-cap upload is refused with a clear error, and every destination stays inside the workspace (a path-traversal attempt is rejected).

Downloading files and folders

• Download a file. Right-click a file in the tree (or an open editor tab) and choose Download.
• Download a folder. Right-click a folder and choose Download as ZIP -- the folder is packaged into a ZIP on the fly. The toolbar's download icon downloads the whole workspace.

Downloads are bounded by FILE_EXPLORER_MAX_DOWNLOAD_BYTES (100 MiB by default, for a single file and for a folder ZIP's total uncompressed size) and FILE_EXPLORER_MAX_DOWNLOAD_ENTRIES (5000 files per ZIP by default). A target over a limit is refused with a clear error. These caps are separate from the editor's open/save cap, so you can download files larger than the editor will open.

Previewing PDFs and images

Opening a PDF shows a built-in pdf.js viewer with zoom in / out and page navigation; opening an image shows a viewer with zoom and pan (mouse wheel and on-screen controls). These replace the old "binary file -- read-only" message for those types. Previews are view-only. The PDF viewer is fully self-hosted (no external/CDN requests), keeping the localhost-first / offline posture.

While viewing an image or PDF, an Attach to chat button appears in the tab bar. It adds the open file to the chat message composer -- it closes the File Explorer and attaches the file just like a drag-and-drop, so you can hand a workspace file to the assistant without downloading it first. The button is enabled only when the explorer has no unsaved edits (so closing it is safe).

Splitting the editor

You can work on several files side by side:

• Split -- drag a tab to the left / right / top / bottom edge of an editor pane to split it into a new group in that direction. The split icon in a group's toolbar also splits the active tab to the right.
• Move -- drag a tab onto another group's tab strip to move it there. A given file lives in one group at a time. Drag the divider between groups to resize them.
• An empty group disappears automatically. The split layout is temporary -- it resets to a single group the next time you open the explorer.

Limits and behavior

• Text only. Binary files are detected and opened read-only -- the editor does not edit binary content.
• Size caps. A file larger than FILE_EXPLORER_MAX_FILE_BYTES (5 MiB by default) is listed in the tree but refused for open/save. Each directory level lists up to FILE_EXPLORER_MAX_TREE_ENTRIES entries (1000 by default).
• Saving is last-write-wins, with a safety check: if the file changed on disk since you opened it, the save is rejected so you do not silently overwrite an external edit. There is no live file watcher in this version -- use the tree's Refresh to re-read.

Security

Everything stays inside CODING_WORKSPACE_DIR: every path is resolved through the same workspace jail the coding tools use, so the explorer cannot read or write outside the workspace. The feature is off by default, requires CODING_ENABLED, and every change (save, create, delete, rename/move) is authenticated (loopback is exempt for local dev).

Note on paste over a network. Pasting via the editor's right-click menu uses the browser clipboard, which browsers only allow on a secure (HTTPS) origin when you are not on localhost. See Operations for HTTPS/TLS if you access ChatWalaʻau over your LAN. Ctrl/Cmd+V works regardless.

Configuration reference

Variable	Default	Description
FILE_EXPLORER_ENABLED	false	Master switch for the whole feature.
FILE_EXPLORER_MAX_FILE_BYTES	5242880	Max size (bytes) a file may be opened/saved at.
FILE_EXPLORER_MAX_TREE_ENTRIES	1000	Max entries returned per directory level.
FILE_EXPLORER_MAX_DOWNLOAD_BYTES	104857600	Max size (bytes) for a single-file download and a folder ZIP (total uncompressed).
FILE_EXPLORER_MAX_DOWNLOAD_ENTRIES	5000	Max number of files included in a folder ZIP.
FILE_EXPLORER_MAX_UPLOAD_BYTES	104857600	Max total size (bytes) across all files in one upload.
FILE_EXPLORER_MAX_UPLOAD_FILES	500	Max number of files in one upload (a folder upload sends one per descendant).

The File Explorer also requires CODING_ENABLED and CODING_WORKSPACE_DIR (see Configuration).