AFS SystemFS Example

This example demonstrates how to create a chatbot that can interact with your local file system using the AIGNE Framework and AIGNE CLI. The example utilizes the SystemFS module to provide file system access to AI agents through the AIGNE File System (AFS) interface.

AIGNE File System (AFS) is a virtual file system abstraction that provides AI agents with unified access to various storage backends. For comprehensive documentation, see AFS Documentation.

Prerequisites

• Node.js (>=20.0) and npm installed on your machine
• An OpenAI API key for interacting with OpenAI's services
• Optional dependencies (if running the example from source code):
  • Pnpm for package management
  • Bun for running unit tests & examples

Quick Start (No Installation Required)

export OPENAI_API_KEY=YOUR_OPENAI_API_KEY # Set your OpenAI API key

# Mount your current directory and chat with the bot about your files
npx -y @aigne/example-afs-system-fs --path . --chat

# Mount a specific directory (e.g., your documents)
npx -y @aigne/example-afs-system-fs --path ~/Documents --mount /docs --description "My Documents" --chat

# Ask questions about files without interactive mode
npx -y @aigne/example-afs-system-fs --path . --input "What files are in the current directory?"

Installation

Clone the Repository

git clone https://github.com/AIGNE-io/aigne-framework

Install Dependencies

cd aigne-framework/examples/afs-system-fs

pnpm install

Setup Environment Variables

Setup your OpenAI API key in the .env.local file:

OPENAI_API_KEY="" # Set your OpenAI API key here

Using Different Models

You can use different AI models by setting the MODEL environment variable along with the corresponding API key. The framework supports multiple providers:

• OpenAI: MODEL="openai:gpt-4.1" with OPENAI_API_KEY
• Anthropic: MODEL="anthropic:claude-3-7-sonnet-latest" with ANTHROPIC_API_KEY
• Google Gemini: MODEL="gemini:gemini-2.0-flash" with GEMINI_API_KEY
• AWS Bedrock: MODEL="bedrock:us.amazon.nova-premier-v1:0" with AWS credentials
• DeepSeek: MODEL="deepseek:deepseek-chat" with DEEPSEEK_API_KEY
• OpenRouter: MODEL="openrouter:openai/gpt-4o" with OPEN_ROUTER_API_KEY
• xAI: MODEL="xai:grok-2-latest" with XAI_API_KEY
• Ollama: MODEL="ollama:llama3.2" with OLLAMA_DEFAULT_BASE_URL

For detailed configuration examples, please refer to the .env.local.example file in this directory.

Run the Example

# Run with your current directory
pnpm start --path .

# Run with a specific directory and custom mount point
pnpm start --path ~/Documents --mount /docs --description "My Documents"

# Run in interactive chat mode
pnpm start --path . --chat

How SystemFS Works

This example uses the SystemFS module from @aigne/afs-system-fs to mount your local file system into the AIGNE File System (AFS). This allows AI agents to interact with your files through a standardized interface.

Key Features

• File Operations: List, read, write, and search files in mounted directories
• Recursive Directory Traversal: Navigate through subdirectories with depth control
• Fast Text Search: Uses ripgrep for blazing-fast content search across files
• Metadata Support: Access file timestamps, sizes, types, and custom metadata
• Path Safety: Sandboxed access limited to mounted directories

Available Operations

The SystemFS module provides these AFS operations:

list(path, options?) - List directory contents

// List files in root directory
await systemFS.list("")

// List files recursively with depth limit
await systemFS.list("", { recursive: true, maxDepth: 2 })

// List with sorting and limits
await systemFS.list("", {
  orderBy: [['path', 'asc']],
  limit: 10
})

read(path) - Read file or directory

// Read file content
const file = await systemFS.read("README.md")
console.log(file.content) // File contents as string

// Read directory metadata
const dir = await systemFS.read("src")
console.log(dir.metadata.type) // "directory"

write(path, entry) - Write or create files

// Write a text file
await systemFS.write("notes.txt", {
  content: "My notes",
  summary: "Personal notes file"
})

// Write JSON data
await systemFS.write("config.json", {
  content: { setting: "value" },
  metadata: { format: "json" }
})

search(path, query, options?) - Search file contents

// Search for text in files
const results = await systemFS.search("", "TODO")

// Search with regex patterns
const matches = await systemFS.search("", "function\\s+\\w+")

// Limit search results
const limited = await systemFS.search("", "error", { limit: 5 })

Example Usage

Try these commands to explore the file system capabilities:

Basic File Operations

# List all files in current directory
npx -y @aigne/example-afs-system-fs --path . --input "List all files in the root directory"

# Read a specific file
npx -y @aigne/example-afs-system-fs --path . --input "Read the contents of package.json"

# Search for specific content
npx -y @aigne/example-afs-system-fs --path . --input "Find all files containing the word 'example'"

Interactive Chat Examples

# Start interactive mode
npx -y @aigne/example-afs-system-fs --path . --chat

Then try asking:

• "What files are in this directory?"
• "Show me the contents of the README file"
• "Find all TypeScript files"
• "Search for functions in the codebase"
• "Create a new file called notes.txt with some content"
• "List all files recursively with a depth limit of 2"

Advanced Usage

# Mount multiple directories or specific paths
npx -y @aigne/example-afs-system-fs --path ~/Projects --mount /projects --description "My coding projects" --chat

The chatbot can help you navigate, search, read, and organize files in your mounted directories through natural language commands.

How this Example Works

Mount a local directory as an AFS module

Just following code snippet shows how to mount a local directory using SystemFS:

AIAgent.from({
  ...,
  afs: new AFS().use(
    new SystemFS({ mount: '/source', path: '/PATH/TO/Bitcoin/Project', description: 'Codebase of Bitcoin project' }),
  ),
  afsConfig: {
    injectHistory: true,
  },
}),

Call AFS tools to retrieve context

User Question: What's the purpose of this project?

{
  "toolCalls": [
    {
      "id": "call_nBAfMjqt6ufoR22ToRvwbvQ6",
      "type": "function",
      "function": {
        "name": "afs_list",
        "arguments": {
          "path": "/",
          "options": {
            "recursive": false
          }
        }
      }
    }
  ]
}

The agent will call the afs_list tool to list the files in the root directory

{
  "status": "success",
  "tool": "afs_list",
  "options": {
    "recursive": false
  },
  "list": [
    {
      "id": "/README.md",
      "path": "/source/README.md",
      "createdAt": "2025-10-30T14:03:49.961Z",
      "updatedAt": "2025-10-30T14:03:49.961Z",
      "metadata": {
        "type": "file",
        "size": 3489,
        "mode": 33188
      }
    },
    // ... other files
  ]
}

Then use afs_read to read specific file content

{
  "toolCalls": [
    {
      "id": "call_73i8vwuHKXt2igXGdyeEws7F",
      "type": "function",
      "function": {
        "name": "afs_read",
        "arguments": {
          "path": "/source/README.md"
        }
      }
    }
  ]
}

Finally, prompt builder will combine the retrieved file content and construct the final message for the agent to answer the user question.

{
  "messages": [
    {
      "role": "system",
      "content": "You are an ...",
    },
    {
      "role": "user",
      "content": [
        {
          "type": "text",
          "text": "What's the purpose of this project?"
        }
      ]
    },
    {
      "role": "agent",
      "toolCalls": [
        {
          "id": "call_TLvilbEhXqg3WFsFAKqm69W9",
          "type": "function",
          "function": {
            "name": "afs_list",
            "arguments": {
              "path": "/source",
              "options": {
                "recursive": false
              }
            }
          }
        }
      ]
    },
    {
      "role": "tool",
      "content": "... list result ...", // Here would be the actual list result
      "toolCallId": "call_TLvilbEhXqg3WFsFAKqm69W9"
    },
    {
      "role": "agent",
      "toolCalls": [
        {
          "id": "call_73i8vwuHKXt2igXGdyeEws7F",
          "type": "function",
          "function": {
            "name": "afs_read",
            "arguments": {
              "path": "/source/README.md"
            }
          }
        }
      ]
    },
    {
      "role": "tool",
      "content": "... read file content ...", // Here would be the actual file content
      "toolCallId": "call_73i8vwuHKXt2igXGdyeEws7F"
    }
  ]
}

The final answer from the agent would be:

This repository is Bitcoin Core — the reference implementation of the Bitcoin protocol. Its purpose is to provide a full-node Bitcoin client that:

    * Connects to the Bitcoin peer-to-peer network, downloads blocks and transactions, and fully validates them against consensus rules (so you don’t have to trust others).
    * Acts as a reference implementation of Bitcoin protocol behavior used by wallets, services, and other implementations.
    * Includes an optional wallet and a GUI (and an RPC interface) for interacting with the node.
    * Provides developer tooling, tests (unit, integration, regression), and documentation to maintain security and correctness.

For an overview see the README (https://bitcoincore.org) and to get ready-to-run binaries use https://bitcoincore.org/en/download/. The project is released under the MIT license.