useAgentThreadFilesystem() hook
useAgentThreadFilesystem() is the thread workspace file hook. It exposes the top-level listing for the thread filesystem and the helper methods that read individual files or nested directories inside that workspace.Usage
The following example shows a basic usage of useAgentThreadFilesystem().
import { useEffect } from 'react';import { useAgentThreadFilesystem } from '@wacht/nextjs';export default function FilesystemPane({ threadId,}: { threadId: string;}) { const { filesystem, getFile } = useAgentThreadFilesystem(threadId, true); useEffect(() => { const firstFile = filesystem.files.find((entry) => !entry.is_dir); if (firstFile) { void getFile(firstFile.path); } }, [filesystem.files, getFile]); return <div>{filesystem.files.length} items</div>;}Return value
The hook returns the following fields and methods.
›filesystem?: ProjectTaskWorkspaceListing | undefined;
filesystem?: ProjectTaskWorkspaceListing | undefined;Current top-level filesystem listing.
›exists?: boolean | undefined;
exists?: boolean | undefined;Whether the workspace exists at all.
›files?: ProjectTaskWorkspaceFileEntry[] | undefined;
files?: ProjectTaskWorkspaceFileEntry[] | undefined;Current entries in the listing.
›getFile?: (path: string) => Promise<ProjectTaskWorkspaceFileContent & { blob: Blob }> | undefined;
getFile?: (path: string) => Promise<ProjectTaskWorkspaceFileContent & { blob: Blob }> | undefined;Loads one file from the thread workspace and returns file metadata plus a `Blob`.
›listDirectory?: (path?: string) => Promise<ProjectTaskWorkspaceListing> | undefined;
listDirectory?: (path?: string) => Promise<ProjectTaskWorkspaceListing> | undefined;Reads a nested directory listing without replacing the hook API contract.
Overview
The top-level hook state is a directory listing, not file content. File content stays on demand through
getFile(), which is why the hook works well for explorer panes where the user navigates a tree and opens files lazily.