Coding Agent + AgentFS + LlamaIndex Workflows

A demo where we run Claude Code or Codex 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

If you wish to use the demo with Codex, you need to install the Codex SDK separately (given the size of the library - 140+ MB - its download it disabled by default):

pnpm add @openai/codex-sdk

Moreover, if you wish to run the demo with Codex, you also need to start the MCP server (from a different terminal window, but within the same directory):

pnpm run mcp-start

The MCP will be live on http://localhost:3000/mcp, and you will need to add the MCP configuration in config.toml to the global Codex configuration in $HOME/.codex/config.toml. If you want Codex to use the filesystem MCP by default, you will also need to copy the AGENTS.md file, containing the instructions on how to use the server.

Now run the demo with:

# for the first time
pnpm run start

# If you want to add more files to the database
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

And that all the tests still pass (add new ones if needed):

# here node v22+ is needed
pnpm run test

Once your code is compliant with formatting and linting and all tests are passing, 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.