A demo where we run Claude Code within a fully-virtualized file system (AgentFS), orchestrating it with LlamaIndex Workflows and adding the possibility of reading unstructured files (e.g. PDFs or Word/Google docs) with LlamaCloud.

Set Up and Run

Clone this repository:

git clone https://github.com/run-llama/agentfs-claude
cd agentfs-claude

Install all necessary dependencies:

pnpm install 
# you can use other package managers, but pnpm is preferred

Now run the demo with:

# for the first time
pnpm run start

# for follow-ups
pnpm run clean-start

And follow the prompts in the terminal

How it works

All the filesystem-bound operations are performed on the AgentFS (and not on the real files), thanks to the filesystem MCP that exposes the following tools:

read_file: read a file, providing its path
write_file: write a file, providing its path and content
edit_file: edit a file, providing the old string and the new string to replace the old one with
list_files: list all the available files
file_exists: check whether or not a file exists, providing its path

What happens under the hood when the agent is running:

All text-based files in the current directory are uploaded to a LibSQL database and indexed
Non text-based files (namely in PDF/DOCX/DOC/PPTX/XLSX format) are parsed by LlamaParse and uploaded with their content converted to markdown text
When the agent performs a filesystem-bound operation, it calls one of the tools from the filesystem MCP
Other tools (such as WebSearch/Todo/Task) run normally
If the agent was to call one of the disallowed tools (Read, Write, Edit and Glob), a PreToolUse hook would deny the tool call and redirect the agent to using the filesystem MCP tools

The integration with LlamaIndex Workflows offers the perfect harnessed environment:

Files are pre-loaded from the current directory into AgentFS in the first step of the workflow
The prompt from the user and other information (resume a session, use plan mode or not) are collected from the user directly using human-in-the-loop
The agent runs in its own step, when everything is ready

Example prompt

Run the agent in this directory, and prompt it with:

Explore all the available files to you, find the task file, read it and act in accordance with it. If needed, read other files (such as the document on observability in LlamaIndex Workflows).

In this sense, the agent should first list all the files, then read data/task.docx and follow the task in it, also reading data/observability_in_llamaindex_workflows.pdf since the task asks for instrumentation of a LlamaIndex Workflows.

Contributing

If you wish to contribute, make sure that your code follows the formatting and linting guidelines, running:

pnpm run check

Once your code is compliant with formatting and linting, you can create a pull request from a non-default branch of your fork (e.g. feat/awesome-feature, fix/great-fix).

License

This project is distributed under an MIT License.